# raia API

Integrating AI Agents into existing applications or workflows is key to building autonomous agents. raia provides a robust yet simple API to connect to AI Agents built and trained on the AI Platform.

<a href="https://api.raia2.com/api/external/docs/openapi.json" class="button primary" data-icon="arrow-up-right-from-square">View OpenAPI spec</a>

### Swagger Links

US Region: <https://api.raia2.com/api/external/docs/>

EU Region: <https://api-eu.raia2.com/api/external/docs/>

raia exposes a REST-style, JSON-over-HTTPS interface that lets you programmatically start conversations with an AI agent, stream messages, manage agent resources (files, skills, webhooks), and retrieve logs. All endpoints live under the `https://api.raia2.com/external/` base path, use standard HTTP verbs, and return structured status codes (2xx success, 4xx auth / validation errors, 5xx unexpected server faults).

***

**1. Authentication & headers**

* Every agent you create in Launch Pad can generate its own **Secret API Key** by enabling the **API Skill**.
* Send that key on every call via a custom header:

```
Agent-Secret-Key: YOUR_API_KEY
```

This single header authenticates and scopes the request to *that* agent instance【2:file:6†L1-L8】.

***

**2. Core resource groups & flagship endpoints**

| Resource                            | Typical use-cases                                                      | Key endpoints (all require `Agent-Secret-Key`)                                                                                                                                                                                                                                             |
| ----------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Conversations**                   | Start a new thread, post user messages, fetch history, or wipe threads | <p><code>POST /conversations/start</code> to create a multi-channel conversation (email/SMS/voice)  </p><p><code>GET /conversations/{id}</code> to fetch a thread by ID  </p><p><code>POST /conversations/{id}/messages</code> to push a user message (and receive the agent’s reply) </p> |
| **Agents**                          | Look up basic agent metadata for the calling key                       | `GET /agents/by-api-key` returns the agent profile                                                                                                                                                                                                                                         |
| **Agent Files (knowledge & packs)** | Upload documents, list, add/remove from the assistant                  | <p><code>POST /agent-files/upload</code> (multipart) to add training docs</p><p><code>GET /agent-files/by-api-key</code> to list all files </p>                                                                                                                                            |
| **Webhooks**                        | Push real-time conversation data to your stack                         | `POST /agents/webhooks` registers a webhook with triggers like `each_message` or `end_dialog`                                                                                                                                                                                              |

All endpoints echo common error shapes (403 invalid key, 404 not-found, 500 unexpected) so you can branch logic cleanly.

***

**3. Typical conversational workflow**

1. **Start** – `POST /conversations/start` with the user’s channel & identifiers. Response returns a `conversationId`.
2. **Chat** – `POST /conversations/{conversationId}/messages` whenever the user (or your app) speaks; the agent’s reply comes back in the same call.
3. **Stream / monitor** – poll `GET /conversations/{id}/messages` or rely on a webhook to receive every turn.
4. **Upload knowledge** – `POST /agent-files/upload` with PDFs/Markdown, then `PUT /agent-files/{id}/add-to-assistant` to make them searchable.
5. **House-keeping** – use DELETE endpoints to prune files or threads once they’re obsolete.

***

**4. Security & limits**

* Keys are scoped per-agent; rotate them anytime in the UI ( **Update API Key** ) to invalidate old tokens
* raia is SOC-2 compliant; all traffic is TLS-encrypted.
* Standard rate-limits apply (check the **external docs** link in the UI), and 429s indicate back-off.

***

**5. Ecosystem integrations**

* A maintained **n8n community node** lets no-code builders hit the same endpoints for triggers/actions
* Webhook payloads include rich JSON (user info, transcript, scores) so you can fan-out to CRMs, BI, or ticketing automatically.

***

#### TL;DR

If you can send an HTTPS request with an `Agent-Secret-Key`, you can:

* spin up or resume a multi-channel conversation in one call,
* stream messages back and forth in real time,
* inject or retrieve files for RAG-style answers, and
* wire the agent into any workflow via first-class webhooks.

Full OpenAPI docs are always available at **`/api/external/docs`** for SDK generation or Postman import.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.raiaai.com/api-reference/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.