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.

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.

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

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",
  "persist": true
}

{
  "data": {
    "reply": "We are open 9am-6pm Monday to Friday.",
    "conversationId": "conv_abc123",
    "citations": [],
    "media": [],
    "realtimeToken": "optional",
    "realtimeUrl": "wss://..."
  },
  "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","endUserId":"customer-42"}' \
  --no-buffer

{
  "message": "Tell me about your products",
  "conversationId": "optional",
  "endUserId": "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
    }
  },
  "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