raia API

Leverage our API to connect applications or workflows to AI Agents built on raia Platform.

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.

View OpenAPI spec

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	POST /conversations/start to create a multi-channel conversation (email/SMS/voice) GET /conversations/{id} to fetch a thread by ID POST /conversations/{id}/messages to push a user message (and receive the agent’s reply)
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	POST /agent-files/upload (multipart) to add training docs GET /agent-files/by-api-key to list all files
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.