REST API Reference — raia Developer Hub

Interactive reference — US

Swagger UI (US)

Explore every endpoint and try requests live, authenticated with your Agent Secret Key.

Open Swagger

Interactive reference — EU

Swagger UI (EU)

EU-hosted Swagger docs for agents running in the EU region.

Open Swagger

Machine-readable spec

OpenAPI JSON

Download the raw OpenAPI spec to generate clients in any language (TypeScript, Python, Go, etc.).

View openapi.json

Overview

The raia REST API lets you programmatically create conversations, send messages, and retrieve conversation history from your own applications.

Authentication

All requests authenticate with a Bearer token in the Authorization header. Your token is the Agent Secret Key, generated in raia Command when you enable the API Skill.

http

Authorization: Bearer {your-agent-secret-key}

Security note

Agent Secret Keys are scoped to a single agent. Never expose this key in client-side code — make all API calls from a secure backend.

Core Endpoints

The API is built around two primary resources: conversations and conversation-messages.

Method	Endpoint	Description
`POST`	`/api/v1/conversations`	Create a new conversation thread
`GET`	`/api/v1/conversations/{id}`	Retrieve a specific conversation
`DELETE`	`/api/v1/conversations/{id}`	Delete a conversation and its messages
`POST`	`/api/v1/conversation-messages`	Send a message to an existing or new conversation
`GET`	`/api/v1/conversation-messages`	Retrieve message history for a conversation

Sending a Message

The most common operation is sending a message to the agent and receiving a response — a single call to POST /api/v1/conversation-messages.

Request payload

json

{
  "message": "I need help resetting my password.",
  "conversationId": "optional-thread-id-for-existing-chats",
  "channel": "api",
  "context": "User is on the login page.",
  "user": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "customData": {
      "plan": "enterprise",
      "accountId": "12345"
    }
  }
}

Response payload

json

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "role": "assistant",
  "content": "I can help you reset your password. I've just sent a reset link to jane@example.com.",
  "createdAt": "2026-06-20T10:00:00Z"
}

Frequently asked questions

How do I maintain conversation history?

Omit conversationId on the first message — the API creates a new conversation and returns its ID. Include that ID on subsequent messages and the agent automatically remembers the context.

What is the customData object used for?

It carries arbitrary JSON about the user or their state into the agent's context, so the agent can personalize replies (e.g., knowing the user is on an enterprise plan without asking).

Are there rate limits?

Yes — limits depend on your plan. Exceeding them returns 429 Too Many Requests. Implement exponential backoff retries.