API Reference

REST API Reference

The Runa API is organized around REST. All requests use JSON and are authenticated with Bearer tokens.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Find your API key in the Runa dashboard under Settings → API Keys.

Base URL

https://api.useruna.ai

Endpoints

POST/v1/chat

Send a message to the agent and receive a response.

Request Body

{
  "productId": "prod_abc123",
  "sessionId": "sess_xyz",
  "message": "Show me last month's revenue"
}

Response

{
  "id": "msg_001",
  "reply": "Here is your revenue for last month...",
  "toolCalls": [],
  "sessionId": "sess_xyz"
}

GET/v1/conversations

List all conversations for your product.

Response

{
  "conversations": [
    { "id": "sess_xyz", "startedAt": "2026-03-01T10:00:00Z", "messageCount": 5 }
  ],
  "total": 1
}

GET/v1/conversations/:id

Get a specific conversation with full message history.

Response

{
  "id": "sess_xyz",
  "messages": [
    { "role": "user", "content": "Show me revenue", "timestamp": "..." },
    { "role": "assistant", "content": "Here is your revenue...", "timestamp": "..." }
  ]
}

POST/v1/knowledge

Add a knowledge source to your product.

Request Body

{
  "type": "url",
  "url": "https://docs.yourproduct.com",
  "name": "Help Center"
}

Response

{
  "id": "ks_001",
  "status": "indexing",
  "name": "Help Center",
  "createdAt": "2026-03-01T10:00:00Z"
}

GET/v1/knowledge

List all knowledge sources.

Response

{
  "sources": [
    { "id": "ks_001", "name": "Help Center", "type": "url", "status": "ready" }
  ]
}

DELETE/v1/knowledge/:id

Delete a knowledge source.

Response

{ "deleted": true, "id": "ks_001" }

POST/v1/tools

Request Body

{
  "name": "get_revenue",
  "description": "Fetches revenue data for a given period",
  "endpoint": "https://api.yourapp.com/revenue",
  "method": "GET"
}

Response

{
  "id": "tool_001",
  "name": "get_revenue",
  "status": "active"
}

GET/v1/analytics

Get analytics data for your product.

Response

{
  "conversations": 4821,
  "messagesTotal": 19284,
  "avgSessionLength": 4.2,
  "topIntents": ["revenue_query", "user_lookup", "export_data"]
}