Skip to main content

APIs

Streaming and Errors

KriyaOS chat APIs support streaming responses using Server-Sent Events (SSE). This enables your UI to render assistant answers token-by-token and display active tool executions, while masking internal infrastructure errors from end users.

Stream Event Protocol​

When calling the chat endpoint with stream=true, the API returns a text/event-stream response formatted according to the Vercel AI SDK UI message stream specification.

Each line in the stream represents a separate event chunk. The main events you will receive include:

1. session-created / start​

Emitted as soon as the session is initialized.

{
  "type": "start",
  "messageMetadata": {
    "sessionId": "sess_1234567890"
  }
}

2. text-start​

Signals that the assistant has started generating a response.

{
  "type": "text-start",
  "id": "msg_0987654321"
}

3. text-delta​

Emits response chunks (tokens) as they are generated by the underlying model.

{
  "type": "text-delta",
  "id": "msg_0987654321",
  "delta": " Hello"
}

4. text-end​

Signals that the current text generation is complete.

{
  "type": "text-end",
  "id": "msg_0987654321"
}

5. finish​

Emitted at the end of the streaming sequence. Contains metadata about the completed session, the finishReason (e.g. stop, length, content-filter, tool-calls), and any retrieved knowledge sources (RAG chunks).

{
  "type": "finish",
  "finishReason": "stop",
  "messageMetadata": {
    "sessionId": "sess_1234567890",
    "retrievedChunks": [
      {
        "id": "chunk_abc123",
        "text": "Pricing for Creator plan is $29/mo...",
        "score": 0.92
      }
    ]
  }
}

6. data-tool-activity​

Allows the frontend to show tool activity indicator states in real-time (e.g., when the agent invokes an MCP tool like the Google Calendar adapter).

Tool Start Event​

{
  "type": "data-tool-activity",
  "data": {
    "type": "tool-start",
    "serverId": "internal-google-calendar",
    "serverName": "Google Calendar",
    "toolName": "book-appointment",
    "toolTitle": "Book appointment"
  }
}

Tool End Event​

{
  "type": "data-tool-activity",
  "data": {
    "type": "tool-end",
    "serverId": "internal-google-calendar",
    "serverName": "Google Calendar",
    "toolName": "book-appointment",
    "toolTitle": "Book appointment",
    "status": "success"
  }
}

Error Handling & Safety​

Errors are split into two categories to prevent leaking internal stack traces or provider details to end users.

1. HTTP Error Responses​

Validation, Authentication, and Rate Limiting errors occur before the stream begins and are returned as standard HTTP JSON responses.

Validation Error (400 Bad Request)​

Returned if the payload exceeds message size caps (e.g., public chat character bounds).

{
  "error": "Message text cannot exceed 8000 characters"
}

Rate Limiting (429 Too Many Requests)​

Returned if too many public chat requests are made from the same client IP.

  • The response includes a Retry-After header indicating the wait time in seconds.
{
  "error": "Too many requests"
}

2. Runtime Stream Failures​

If an error occurs during token generation (e.g., model provider timeout or database disconnect), the stream writer catches the exception and masks it.

  • Instead of leaking backend traces, the stream emits a safe, client-friendly error string:
"Chat response stream failed"
  • The backend logs the full error context safely to the internal application logger (using pino) for developer troubleshooting.

Security Boundary

Streaming errors never leak raw API keys, provider response bodies, or DynamoDB table structures.

Continue Reading

Public Chat API

Call the unauthenticated public chat API.

Secure Chat API

Call the authenticated secure chat API.