raia API — Developer Guide

Every path below is relative to a regional base URL. Use the region your agent runs in — keys are not shared across regions.

The API uses secret keys sent as request headers — not bearer tokens. Which header you send determines what you are allowed to do.

Agent-Secret-Key: {your-agent-secret-key}

The most common flow is three calls: create (or find) a user, open a conversation, then send messages to it.

1. Create a user — POST /api/external/users

{
  "email": "jane@example.com",
  "firstName": "Jane",
  "lastName": "Doe"
}

2. Create a conversation

curl -X POST https://api.raia2.com/api/external/conversations \
  -H "Agent-Secret-Key: $RAIA_AGENT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b" }'

3. Send a message and read the reply

curl -X POST https://api.raia2.com/api/external/conversations/{id}/messages \
  -H "Agent-Secret-Key: $RAIA_AGENT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How do I reset my password?",
    "context": "User is on the login page."
  }'

All 91 operations in API v1.0.0, grouped by resource. Open the interactive guide for full request and response schemas.

Exceeding a limit returns 429 Too Many Requests. Retry with exponential backoff and queue non-urgent traffic.