Build with Kalkas.

The implemented REST contract, not an offer of public API access. Use your deployment’s API origin; the public hostname and keys are not available yet.

Make your first call.

The implemented REST service speaks JSON. Set KALKAS_API_ORIGIN to your deployed service origin.

This one asks for the topics Kalkas covers, each marked with whether you hold it.

curl $KALKAS_API_ORIGIN/v1/topics

API access

Keys are not available. The implemented service answers as the free viewer; it does not issue keys or unlock plans.

Pin a version.

Send Kalkas-Version with a date and you get that version's shape every time. Leave it out and you get the latest.

A date we do not answer is a 400. A breaking change ships as a new date, so what you built against does not move under you.

Kalkas-Version: 2026-10-03

Retry without worry.

Reads are always safe to repeat. For a request that changes something, send an Idempotency-Key of 1 to 255 visible characters.

Repeat the same request with the same key within 24 hours and you get the first answer back. Reuse the key for a different request and you get a 409, idempotency_key_reused.

Idempotency-Key: 0192f1c4-7a3e-7b21-9c55-3f0d2e8a1b4c

Page with cursors.

A list takes limit, from 1 to 100 with 20 by default, and answers has_more and next_cursor. Pass next_cursor back as starting_after.

Cursors are opaque: hand them back, never build them. The event log takes the cursor as after.

curl -G $KALKAS_API_ORIGIN/v1/decisions \
  -d limit=50 -d starting_after=$CURSOR

Errors look the same everywhere.

Every error has a type, a code, a message, the param at fault and a request_id. Quote the request_id, also sent as the Request-Id header, if you write to us.

  • 400 404 409

    invalid_request_error: fix the request.

  • 401

    authentication_error: the key is missing or wrong.

  • 403

    permission_error: you do not hold that topic.

  • 429

    rate_limit_error: wait the Retry-After seconds.

  • 500 503

    api_error: try again after the Retry-After seconds.

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_version",
    "message": "...",
    "param": "Kalkas-Version",
    "request_id": "..."
  }
}

SSE status

SSE is planned, not available. There is no implemented stream or Last-Event-ID resume contract. Read /v1/events with its opaque after cursor instead.

MCP status

MCP is planned, not available. No MCP endpoint, tools, resources or subscription protocol is offered.

Webhooks

Signed webhooks are planned, not available. No endpoint registration, signing key or delivery service is offered.

Want every route and field?