# 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.