API Reference

Reference for the implemented public REST API, hosted widget stream transport, and the dashboard routes that often look similar but are not the same API surface.

Quickstart

1. Create an agent-scoped API key from API Keys.
2. Give the key the smallest permission set for the workflow: chat, retrieve, ingest, or trace_read.
3. Call the public API base URL with either Authorization: Bearer ... or x-api-key.

curl -X POST https://api.kravos.ai/v1/chat \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"What are your opening hours?"}'

Successful JSON responses use this shape:

{
  "data": {},
  "meta": {
    "requestId": "req_abc123"
  }
}

Base URLs

Authentication

Public API requests authenticate with either header format:

Authorization: Bearer spk_...

or:

x-api-key: spk_...

Agent keys created in the dashboard are scoped to one agent and currently use the spk_ raw-key prefix. Org-scoped keys exist for organization automation and MCP-style platform access, but /v1 and /api/sdk routes reject org keys because those routes must resolve a single agent.

Permission compatibility

Permissions are checked with directional compatibility so keys created through either vocabulary keep working:

• Alias groups (bidirectional): holding any member of a group satisfies a requirement for any other member. chat ↔ chat:write; retrieve ↔ sources:read ↔ retrieval:read; ingest ↔ ingest.read ↔ ingest.write ↔ sources:write; skill_fetch ↔ skills:read; usage.read ↔ usage:read.
• Base permission fallback: a key holding ingest satisfies fine-grained ingest.read / ingest.write checks.
• One-directional legacy grant: keys created with chat, retrieve, or ingest historically received usage.read; that grant is preserved, so those keys satisfy GET /v1/usage. The reverse never holds — usage.read does not grant chat access.
• A literal * permission satisfies every check.

Allowed origins

The API service accepts CORS requests, then the key allowlist decides whether the request is allowed:

• empty allowedOrigins means any origin is accepted
• a non-empty list requires an Origin header
• the Origin value must exactly match one configured URL
• blocked origins return 403; revoked, inactive, or expired keys return 401

This lets browser-based integrations use public endpoints without turning allowed origins into a hard product cap.

Request IDs

Send x-request-id when you have one. If you omit it, the API creates one. JSON responses include meta.requestId, and the x-request-id response header is exposed for browser clients.

Errors

Public /v1 JSON errors use this envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key",
    "details": {}
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

details is present only for validation failures or other structured errors.

Runtime failures follow a safe rule: 4xx and 504 responses from the agent runtime are propagated with their machine-readable codes, while any other runtime failure returns 500 TURN_FAILED without internal details. The Platform MCP chat tools follow the same rule and surface runtime 5xx failures as a generic tool error that references the request ID instead of leaking internals.

Pagination And Filtering

List endpoints use cursor pagination on the public API.

nextCursor is null when there are no more results. Use enum values for status and type; invalid filters are not applied by the current implementation. Agent-run cursors are the last event sequence. Continue requesting pages until hasMore is false; there is no total trace retrieval cap.

Choose The Right Endpoint

• use POST /v1/chat when you want one complete reply
• use POST /v1/chat/stream when the client should render tokens as they arrive
• use POST /v1/retrieve when you only want source chunks, not AI generation
• use /v1/sources* when you are managing ingestion programmatically
• use /v1/conversations* when you need API-created transcript history
• use GET /v1/agent-runs/:runId when you need a redacted execution trace for one completed or running turn
• use GET /v1/usage when you need current-period usage counters

Usage Semantics

GET /v1/usage is scoped to the key agent: data.turns.used counts platform turns recorded for that agent, data.ingestionJobs.used counts jobs created on that agent's sources, data.sources.active counts that agent's sources, and data.tokens reports the additive { input, output } token aggregate from AI messages of that agent's conversations — all within the current period. Period bounds come from the tenant subscription, falling back to the current calendar month. Plan limit values are tenant entitlements and are reported as limits, never as used amounts. The route only admits agent-scoped keys and fails closed with 500 INTERNAL_ERROR if agent context is missing. This is the REST plan-counter surface; tenant cost aggregates are available through the Platform MCP get_usage tool instead.

Chat Turn Request And Response

Both POST /v1/chat and POST /v1/chat/stream share one request contract.

Identity: exactly one of three

Provide exactly one identity target. Supplying more than one returns 400 VALIDATION_ERROR.

Omit all three to let the API create a fresh anonymous identity for the turn.

Response shape

data.reply is always a string — the complete assistant reply text. data.citations is an array of source citations used to ground the reply, and data.media is an array of media attachments shared in the turn. Both are always present and may be empty.

data.endUserId is the resolved internal end user ID. It is present whenever an end user identity was resolved for the turn — anonymous persistent turns, endUserId, and externalEndUserId — and omitted for conversation-target and ephemeral (persist: false) turns.

{
  "data": {
    "reply": "We are open 9am-6pm Monday to Friday.",
    "conversationId": "clx...",
    "endUserId": "clx...",
    "citations": [],
    "media": []
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Realtime token behavior

POST /v1/chat returns realtimeToken and realtimeUrl by default whenever a conversation exists, so realtime capable clients can upgrade without an extra request. Pass includeRealtimeToken: false to omit both fields entirely, for example when the client never uses the hosted realtime transport.

Streaming headers

POST /v1/chat/stream returns the SSE stream with content-type: text/event-stream and the x-request-id header. When an end user identity was resolved for the turn, the stream also sets x-end-user-id to the internal end user ID. Both x-request-id and x-end-user-id are CORS-exposed, so browser clients can read them.

Endpoints

curl -X POST https://api.kravos.ai/v1/chat \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message":"What are your opening hours?"}'

{
  "message": "What are your opening hours?",
  "conversationId": "optional",
  "endUserId": "optional",
  "externalEndUserId": "optional-stable-caller-id",
  "persist": true,
  "includeRealtimeToken": true
}

{
  "data": {
    "reply": "We are open 9am-6pm Monday to Friday.",
    "conversationId": "conv_abc123",
    "endUserId": "end_user_abc123",
    "citations": [],
    "media": [],
    "realtimeToken": "rt_abc123",
    "realtimeUrl": "wss://realtime.kravos.ai/v1"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl -X POST https://api.kravos.ai/v1/chat/stream \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Tell me about your products","externalEndUserId":"customer-42"}' \
  --no-buffer

{
  "message": "Tell me about your products",
  "conversationId": "optional",
  "endUserId": "optional",
  "externalEndUserId": "optional-stable-caller-id",
  "persist": true
}

HTTP/1.1 200 OK
content-type: text/event-stream
x-request-id: req_abc123

event: ...
data: ...

curl -X POST https://api.kravos.ai/v1/retrieve \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query":"pricing plans","topK":5,"minScore":0.7}'

{
  "query": "pricing plans",
  "topK": 5,
  "minScore": 0.7
}

{
  "data": {
    "chunks": [
      {
        "id": "chunk_abc123",
        "documentId": "doc_abc123",
        "sourceName": "Pricing",
        "text": "Our plans start at $29/mo...",
        "score": 0.94,
        "url": "https://example.com/pricing"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl 'https://api.kravos.ai/v1/sources?limit=20&status=READY' \
  -H "Authorization: Bearer spk_your_api_key"

// Query params: ?limit=20&status=READY&type=URL&cursor=clx...

{
  "data": {
    "sources": [
      {
        "id": "clx...",
        "agentId": "agent_abc123",
        "type": "URL",
        "name": "Help center",
        "status": "READY",
        "config": {
          "url": "https://help.example.com"
        },
        "lastSyncedAt": "2026-07-06T12:00:00.000Z",
        "lastError": null,
        "latestJob": null
      }
    ],
    "nextCursor": "clx..."
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl -X POST https://api.kravos.ai/v1/sources \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key" \
  -d '{"type":"URL","name":"Help center","config":{"url":"https://help.example.com"}}'

{
  "type": "URL",
  "name": "Help center",
  "config": {
    "url": "https://help.example.com"
  },
  "autoSync": true
}

{
  "data": {
    "source": {
      "id": "clx...",
      "agentId": "agent_abc123",
      "type": "URL",
      "name": "Help center",
      "status": "PENDING",
      "config": {
        "url": "https://help.example.com"
      }
    },
    "ingestionJob": {
      "id": "job_abc123",
      "status": "QUEUED"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl https://api.kravos.ai/v1/sources/SOURCE_ID -H "Authorization: Bearer spk_your_api_key"

// No request body

{
  "data": {
    "id": "clx...",
    "agentId": "agent_abc123",
    "type": "URL",
    "name": "Help center",
    "status": "READY",
    "config": {
      "url": "https://help.example.com"
    },
    "error": null,
    "latestJob": {
      "id": "job_abc123",
      "type": "INGEST",
      "status": "SUCCEEDED",
      "progress": 100,
      "chunksCreated": 42,
      "error": null
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl -X PATCH https://api.kravos.ai/v1/sources/SOURCE_ID \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated help center"}'

{
  "name": "Updated help center",
  "config": {
    "url": "https://help.example.com"
  }
}

{
  "data": {
    "id": "clx...",
    "agentId": "agent_abc123",
    "name": "Updated help center",
    "type": "URL",
    "status": "READY"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl -X DELETE https://api.kravos.ai/v1/sources/SOURCE_ID -H "Authorization: Bearer spk_your_api_key"

// No request body

{
  "data": {
    "id": "clx...",
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl -X POST https://api.kravos.ai/v1/sources/SOURCE_ID/sync \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"force":false}'

{
  "force": false
}

{
  "data": {
    "jobId": "job_abc123",
    "status": "QUEUED",
    "sourceId": "clx..."
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl https://api.kravos.ai/v1/ingestion-jobs/JOB_ID -H "Authorization: Bearer spk_your_api_key"

// No request body

{
  "data": {
    "id": "job_abc123",
    "sourceId": "clx...",
    "status": "QUEUED",
    "progress": 0,
    "chunksCreated": null,
    "error": null,
    "startedAt": null,
    "completedAt": null
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl https://api.kravos.ai/v1/conversations -H "Authorization: Bearer spk_your_api_key"

// Query params: ?limit=20&endUserId=end_user_id&cursor=clx...

{
  "data": {
    "conversations": [
      {
        "id": "conv_abc123",
        "agentId": "agent_abc123",
        "endUserId": "end_user_abc123",
        "messageCount": 4,
        "createdAt": "2026-07-06T12:00:00.000Z",
        "updatedAt": "2026-07-06T12:05:00.000Z"
      }
    ],
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl https://api.kravos.ai/v1/conversations/CONVERSATION_ID -H "Authorization: Bearer spk_your_api_key"

// No request body

{
  "data": {
    "id": "conv_abc123",
    "agentId": "agent_abc123",
    "endUserId": "end_user_abc123",
    "messages": [
      {
        "id": "msg_1",
        "role": "user",
        "content": "Hello",
        "createdAt": "2026-07-06T12:00:00.000Z"
      },
      {
        "id": "msg_2",
        "role": "assistant",
        "content": "Hi!",
        "createdAt": "2026-07-06T12:00:01.000Z"
      }
    ],
    "createdAt": "2026-07-06T12:00:00.000Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl 'https://api.kravos.ai/v1/conversations/CONVERSATION_ID/messages?limit=50' \
  -H "Authorization: Bearer spk_your_api_key"

// Query params: ?limit=50&cursor=opaque_cursor
// limit defaults to 50 and must be a positive safe integer.
// Ordering: conversation-scoped database pagination key ascending (PostgreSQL BIGINT). Follow nextCursor until it is null; there is no history cap.
// Cursors are HMAC-authenticated with the server REALTIME_TOKEN_SECRET.
// During legacy-key backfill, the endpoint returns 503 PAGINATION_NOT_READY.

{
  "data": {
    "messages": [
      {
        "id": "msg_1",
        "role": "user",
        "content": "Hello",
        "createdAt": "2026-07-06T12:00:00.000Z"
      },
      {
        "id": "msg_2",
        "role": "assistant",
        "content": "Hi!",
        "createdAt": "2026-07-06T12:00:01.000Z"
      }
    ],
    "nextCursor": "opaque_cursor_or_null",
    "hasMore": true
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

curl https://api.kravos.ai/v1/usage -H "Authorization: Bearer spk_your_api_key"

// No request body

{
  "data": {
    "period": {
      "start": "2026-07-01T00:00:00.000Z",
      "end": "2026-08-01T00:00:00.000Z"
    },
    "turns": {
      "used": 100,
      "limit": 5000,
      "overageEnabled": false
    },
    "ingestionJobs": {
      "used": 4,
      "limit": 100
    },
    "sources": {
      "active": 5,
      "limit": 50
    },
    "tokens": {
      "input": 1200000,
      "output": 400000
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Public Endpoint Index

Chat And Retrieval Notes

POST /v1/chat and POST /v1/chat/stream accept JSON only on the public API domain:

{
  "message": "What are your opening hours?",
  "conversationId": "optional",
  "endUserId": "optional",
  "persist": true
}

If neither conversationId nor endUserId is sent, the API creates an end user for the turn. persist defaults to true. The streaming route returns text/event-stream and forwards runtime SSE events.

Agent Run Traces

GET /v1/agent-runs/:runId returns one run only when it belongs to the authenticated key's tenant and agent. It requires trace_read; runs outside that scope return 404. Every successful trace read is durably audited before the response is sent.

GET /v1/agent-runs/run_123?limit=20&cursor=40
Authorization: Bearer spk_...

{
  "data": {
    "id": "run_123",
    "status": "complete",
    "conversationId": "conv_123",
    "messageId": "msg_123",
    "startedAt": "2026-07-30T12:00:00.000Z",
    "completedAt": "2026-07-30T12:00:03.000Z",
    "events": [
      {
        "id": "run_123:41",
        "runId": "run_123",
        "sequence": 41,
        "type": "tool.completed",
        "status": "complete",
        "label": "Completed a tool call",
        "timestamp": "2026-07-30T12:00:02.000Z"
      }
    ],
    "hasMore": true,
    "nextCursor": "41"
  },
  "meta": { "requestId": "req_abc123" }
}

Pass nextCursor as cursor for the next page. limit and cursor must be positive integers; invalid values return 400 VALIDATION_ERROR. Trace event payloads contain developer-visible tool and source context with credentials redacted before storage. Encrypted payloads are never exposed. Because payloads can include customer and tool data, grant trace_read only to trusted server-side integrations.

Hosted stream clients with both chat and trace_read receive operator-visible data-agent-run-event parts. A key with only chat receives end-user-redacted event parts. The chat request authenticates the key once; trace visibility is derived from that authenticated permission set.

data: {"type":"data-agent-run-event","data":{"id":"run_123:41","runId":"run_123","sequence":41,"type":"tool.completed","status":"complete","label":"Completed a tool call","timestamp":"2026-07-30T12:00:02.000Z"}}

POST /v1/retrieve accepts:

{
  "query": "pricing plans",
  "topK": 5,
  "minScore": 0.7
}

The implemented validation accepts query up to 1,000 characters, topK from 1 to 20, and minScore from 0 to 1.

Source Types

When creating sources via POST /v1/sources, use one of these documented public configurations:

The public create route accepts BULK_UPLOAD because it accepts the source enum. The ZIP extraction workflow itself is an authenticated dashboard route (/api/sources/bulk-upload), not a separate public /v1 REST endpoint.

autoSync defaults to true. Set autoSync: false when you want to create the source record first and queue ingestion later with POST /v1/sources/:id/sync.

Web App And SDK Routes

These routes were inspected because they overlap with public API concepts, but they are not the same as the public REST API:

• /api/sdk/* powers the embedded widget and suite. It accepts an agent API key or a dashboard session fallback. Routes that read existing end-user state require sessionId; init and some voice-start paths can create a session when omitted.
• /api/sources*, /api/conversations*, and /api/usage are dashboard session routes. They use next-auth/RBAC, not public API-key-only auth.
• POST /api/v1/chat and POST /api/v1/retrieve on the web app domain return 410 GONE; call the public API domain instead.
• POST /api/v1/chat/stream on the web app domain is the hosted widget stream endpoint. It can accept JSON or multipart/form-data with attachments.

File Attachments On Hosted Stream

The hosted web stream endpoint can accept images and PDFs alongside a chat message. Send POST /api/v1/chat/stream on your Kravos.ai web app domain as multipart/form-data:

curl -X POST https://your-domain.com/api/v1/chat/stream \
  -H "Authorization: Bearer spk_..." \
  -F "message=What is in this image?" \
  -F "files=@photo.png"

Supported MIME types are JPEG, PNG, WebP, GIF, and PDF. The implemented hosted route accepts up to 10 files per request, with 10 MB per image and 25 MB per PDF. Model-specific validation may still reject an attachment type.

OpenAPI And Spec Alignment

The compact OpenAPI spec exposed through platform/MCP docs is generated from packages/platform/src/read/docs/reference.ts. It lists the implemented public /v1 paths for chat, streaming chat, retrieval, sources, source detail/update/delete/sync, ingestion-job detail, conversations, agent-run traces, and usage.

The generated spec includes path parameters, success status codes, permissions, source paths, and update timestamps. It is still compact: request and response schemas are documented on this page and should be treated as the human-readable contract.

Related Docs