API reference

Create an API key

In the dashboard, open Developer Access and click Generate New Key. Give the key a name and, if you like, an Expiration Date; leave it empty and the key never expires. You need the permission to manage API keys.

• The full key is shown only once, right after you create it. Copy it immediately: Kyros stores only a hash of the key and can’t show it to you again.
• In the list, each key is identified by its name and its prefix (starting with sk_).
• Revoke Access invalidates a key immediately. Applications using it can no longer reach the API.
• A key belongs to the workspace you created it in and works only for that workspace’s assistants.

Authenticate with the X-API-Key header

Send the key in the X-API-Key header with every request. An API key sent as Authorization: Bearer is not recognized, and the request fails with 401.

X-API-Key: YOUR_API_KEY

If the header is missing or the key is invalid, expired or revoked, the API responds with 401.

All endpoints live under the path /api/v1/harness/. The examples use https://API-HOST as a placeholder for the host. Ask for the API host via the contact page. ASSISTANT_ID stands for your assistant’s ID (a UUID).

Send a message: the chat endpoint

POST /api/v1/harness/ASSISTANT_ID/chat runs one turn of the conversation: you send a message and the assistant answers. The request body is JSON with two fields:

• message (required, not empty) – the message to the assistant.
• thread_id (optional) – the thread_id from an earlier response, to continue that conversation. Without it, a new conversation starts; an unknown ID also starts a new one.

curl -X POST "https://API-HOST/api/v1/harness/ASSISTANT_ID/chat" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "How long does shipping to Canada take?"}'

Example response (shortened; content and numbers are made up, and “example.com” stands for a sample store):

{
  "thread_id": "THREAD_ID",
  "message_id": "MESSAGE_ID",
  "answer": "Orders to Canada arrive in 5–7 business days. You can find shipping costs on our shipping page.",
  "citations": [
    {
      "source_id": 1,
      "url": "https://www.example.com/shipping",
      "name": "Shipping & delivery"
    }
  ],
  "contexts": ["…"],
  "tool_calls": [
    {
      "tool_call_id": "TOOL_CALL_ID",
      "tool_name": "research",
      "args": { "query": "shipping time Canada" },
      "result_preview": "…"
    }
  ],
  "usage": {
    "input_tokens": 2140,
    "output_tokens": 38,
    "total_tokens": 2178,
    "duration_ms": 2350
  }
}

The response fields:

• thread_id – the conversation ID; send it back with your next message.
• message_id – the ID of the assistant’s reply (may be null).
• answer – the full answer text.
• citations – the sources from your knowledge base that the answer is based on, each with source_id, url and name; empty if no source was used.
• contexts – the passages the assistant read from the knowledge base during this turn.
• tool_calls – the tools the assistant called (tool_call_id, tool_name, args, result_preview).
• usage – tokens (input_tokens, output_tokens, total_tokens) and duration in milliseconds (duration_ms).

What applies to API requests

The response is not streamed: the API replies once the assistant has finished and returns the whole text at once. API requests use the same settings as the chat widget – the assistant’s model, instructions and knowledge base. Incoming messages go through the same content moderation, and every message uses credits, just as in the widget.

Other endpoints

• GET /api/v1/harness/ASSISTANT_ID/chat/THREAD_ID/messages – returns a conversation’s history (thread_id, messages, card_actions).
• POST /api/v1/harness/ASSISTANT_ID/kb/search – searches the assistant’s knowledge base without calling the model (body: query, optionally limit and more); not billed, and no conversation is created.
• GET /api/v1/harness/ASSISTANT_ID/kb/documents – lists the ingested documents in the assistant’s knowledge bases with their status; filter with q and status, page with skip and limit.

Error codes

• 401 – the key is missing, invalid, expired or revoked.
• 400 – the assistant is not active, or the ID belongs to an assistant that doesn’t support this API.
• 403 – your plan includes no model the assistant can answer with.
• 404 – unknown assistant ID; for the history endpoint, also an unknown conversation.
• 422 – the request body is invalid, for example message is missing or empty.
• 429 – a usage limit of your plan has been reached, for example your credits.
• 502 – the turn could not be completed.

Without your own API client

If you only need data from the conversation to reach your system, you may not need the REST API at all: the actions on an Interactive Card (Beta) can call your own API, store a submission, send a chat message or open a link. To simply embed the chat widget, the embedding guide is all you need; install guides for specific platforms are under integrations.