API reference

Kalkas API

Every endpoint, parameter and object of the REST API, rendered from its OpenAPI document. The API is read-only: it serves information and never acts in anyone’s account.

Version: 2026-10-03
Base URL: https://api.kalkas.ai

OpenAPI document Terms of use for the API

Kalkas sells information: calibrated probabilities, fair odds, the de-vigged market probability, edges and the scored record. It never places a bet or an order, and no object here carries a stake, a price, a venue or a link. Every read goes through one projection that applies the caller's grants, the data licences and the time the caller first sees a call; a free caller sees a call after its question has closed.

Pick the API version with the Kalkas-Version header (a date); without it the latest answers. Every response carries Request-Id. Errors are one shape with a type and a code. Lists take limit and an opaque cursor. A request that changes something takes an Idempotency-Key; reads ignore it.

Endpoints

`GET /v1/topics`

List topics

Every topic Kalkas offers, with whether the caller holds it.

Parameter	In	Type	Required	Description
`Kalkas-Version`	header	2026-10-03	no	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	no	1 to 255 visible ASCII characters. A request that changes something with the same key and request returns the first response for 24 hours; the same key with another request is 409 idempotency_key_reused. Reads ignore it.
`limit`	query	integer	no	Page size, 1 to 100.
`starting_after`	query	string	no	The next_cursor of the previous page.

Responses

200 OK (TopicList)
400 A malformed request: see error.code and error.param. (Error)
403 The caller holds no grant for the topic (permission_error). (Error)
404 Nothing at this id or path. (Error)
405 The route does not take this method; Allow names the one it does. (Error)
409 The request conflicts with an earlier one. (Error)
503 The ledger could not be read; retry after the Retry-After seconds. (Error)

`GET /v1/decisions`

List decisions

The decisions Kalkas has committed, newest question first. A caller sees a decision once its tier first sees it: in a market with first sight on, a free caller after the question closes; in a market with it off, everyone once it is committed.

Parameter	In	Type	Required	Description
`Kalkas-Version`	header	2026-10-03	no	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	no	1 to 255 visible ASCII characters. A request that changes something with the same key and request returns the first response for 24 hours; the same key with another request is 409 idempotency_key_reused. Reads ignore it.
`limit`	query	integer	no	Page size, 1 to 100.
`starting_after`	query	string	no	The next_cursor of the previous page.
`topic`	query	string	no	Only this decisions topic.
`status`	query	open \| resolved	no	open: not yet resolved. resolved: settled, void or ambiguous.
`subject`	query	string	no	Only questions about this entity key.

Responses

200 OK (DecisionList)
400 A malformed request: see error.code and error.param. (Error)
403 The caller holds no grant for the topic (permission_error). (Error)
404 Nothing at this id or path. (Error)
405 The route does not take this method; Allow names the one it does. (Error)
409 The request conflicts with an earlier one. (Error)
503 The ledger could not be read; retry after the Retry-After seconds. (Error)

`GET /v1/decisions/{id}`

Get one decision

One decision by its question key (URL-encode it). 404 when the question has no decision this caller sees.

Parameter	In	Type	Required	Description
`Kalkas-Version`	header	2026-10-03	no	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	no	1 to 255 visible ASCII characters. A request that changes something with the same key and request returns the first response for 24 hours; the same key with another request is 409 idempotency_key_reused. Reads ignore it.
`id`	path	string	yes
`expand[]`	query	analysis	no	analysis adds every forecaster's latest forecast.

Responses

200 OK (Decision)
400 A malformed request: see error.code and error.param. (Error)
403 The caller holds no grant for the topic (permission_error). (Error)
404 Nothing at this id or path. (Error)
405 The route does not take this method; Allow names the one it does. (Error)
409 The request conflicts with an earlier one. (Error)
503 The ledger could not be read; retry after the Retry-After seconds. (Error)

`GET /v1/record`

Get the record

The evaluator's aggregates for one decisions topic, or for every held topic.

Parameter	In	Type	Required	Description
`Kalkas-Version`	header	2026-10-03	no	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	no	1 to 255 visible ASCII characters. A request that changes something with the same key and request returns the first response for 24 hours; the same key with another request is 409 idempotency_key_reused. Reads ignore it.
`topic`	query	string	no	Only this decisions topic.

Responses

200 OK (Record | RecordList)
400 A malformed request: see error.code and error.param. (Error)
403 The caller holds no grant for the topic (permission_error). (Error)
404 Nothing at this id or path. (Error)
405 The route does not take this method; Allow names the one it does. (Error)
409 The request conflicts with an earlier one. (Error)
503 The ledger could not be read; retry after the Retry-After seconds. (Error)

`GET /v1/events`

List events

The decision event log, oldest first, for replay: decision.created, decision.updated and decision.resolved. Resume with after.

Parameter	In	Type	Required	Description
`Kalkas-Version`	header	2026-10-03	no	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	no	1 to 255 visible ASCII characters. A request that changes something with the same key and request returns the first response for 24 hours; the same key with another request is 409 idempotency_key_reused. Reads ignore it.
`limit`	query	integer	no	Page size, 1 to 100.
`after`	query	string	no	The cursor of the last event read (or next_cursor of the previous page). Absent: from the start.
`types`	query	string	no	Comma-separated event types.
`topics`	query	string	no	Comma-separated decisions topics.

Responses

200 OK (EventList)
400 A malformed request: see error.code and error.param. (Error)
403 The caller holds no grant for the topic (permission_error). (Error)
404 Nothing at this id or path. (Error)
405 The route does not take this method; Allow names the one it does. (Error)
409 The request conflicts with an earlier one. (Error)
503 The ledger could not be read; retry after the Retry-After seconds. (Error)

`GET /v1/openapi.json`

This document

Parameter	In	Type	Required	Description
`Kalkas-Version`	header	2026-10-03	no	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	no	1 to 255 visible ASCII characters. A request that changes something with the same key and request returns the first response for 24 hours; the same key with another request is 409 idempotency_key_reused. Reads ignore it.

Responses

200 OpenAPI 3.1 (object)
400 A malformed request: see error.code and error.param. (Error)
403 The caller holds no grant for the topic (permission_error). (Error)
404 Nothing at this id or path. (Error)
405 The route does not take this method; Allow names the one it does. (Error)
409 The request conflicts with an earlier one. (Error)
503 The ledger could not be read; retry after the Retry-After seconds. (Error)

Objects

`Error`

Field	Type	Required	Description
`error`	object	yes

`Topic`

Field	Type	Required	Description
`object`	object	yes
`id`	string	yes
`domain`	string	yes
`kind`	decisions \| analysis	yes
`title`	string	yes
`held`	boolean	yes	Whether the caller holds a grant for the topic.

`TopicList`

Every topic Kalkas offers, by id.

Field	Type	Required	Description
`object`	object	yes
`data`	array of Topic	yes
`has_more`	boolean	yes
`next_cursor`	string \| null	yes	Pass as the cursor parameter to continue. Opaque.

`Forecast`

One forecaster's latest forecast on a question.

Field	Type	Required
`forecaster_kind`	string	yes
`forecaster_version`	string	yes
`probability`	number	yes
`market_probability`	number \| null	yes
`known_at`	string (date-time)	yes

`Decision`

Field	Type	Required	Description
`object`	object	yes
`id`	string	yes	The question's ledger key. URL-encode it in a path.
`topic`	string	yes
`domain`	string	yes
`question`	object	yes
`probability`	number \| null	yes	Kalkas's committed probability that the question resolves yes.
`fair_odds`	number \| null	yes	1 / probability.
`market`	object	yes
`edge`	number \| null	yes
`headline`	object \| null	yes
`kalkas_paper_action`	object	yes
`committed_at`	string (date-time)	yes
`digest`	string	yes	Content digest of the decision fact.
`standing`	unresolved \| resolved \| void \| ambiguous	yes
`resolution`	object \| null	yes
`score`	object \| null	yes
`attribution`	array of string	yes	Text to show with the decision, from the data licences behind it.
`version`	integer	yes	How many decisions Kalkas has committed on the question that this caller sees.
`seq`	string	yes	The decision's position in decision lists.
`analysis`	array of Forecast	no	Present only with expand[]=analysis.

`DecisionList`

The decisions, newest first.

Field	Type	Required	Description
`object`	object	yes
`data`	array of Decision	yes
`has_more`	boolean	yes
`next_cursor`	string \| null	yes	Pass as the cursor parameter to continue. Opaque.

`ScoreRow`

Field	Type	Required
`class`	string	yes
`forecaster`	string	yes
`forecaster_kind`	string	yes
`n`	integer	yes
`edge_vs_market`	number \| null	yes
`log_loss`	number	yes
`brier`	number	yes
`mean_p`	number	yes
`hit_rate`	number	yes
`calibration_slope`	number \| null	yes
`ece`	number	yes
`calibration_flag`	string \| null	yes

`Reliability`

Field	Type	Required
`class`	string	yes
`forecaster`	string	yes
`forecaster_kind`	string	yes
`n`	integer	yes
`bins`	array of object	yes

`Record`

Aggregates of the evaluator over resolved questions: no per-call rows, no stake or profit.

Field	Type	Required
`object`	object	yes
`topic`	string	yes
`domain`	string	yes
`as_of`	string (date-time)	yes
`resolved_questions`	integer	yes
`void_questions`	integer	yes
`trials`	integer	yes
`scores`	array of ScoreRow	yes
`calibration`	array of Reliability	yes
`closing_line_value`	object	yes
`attribution`	array of string	yes

`RecordList`

One record per held decisions topic.

Field	Type	Required	Description
`object`	object	yes
`data`	array of Record	yes
`has_more`	boolean	yes
`next_cursor`	string \| null	yes	Pass as the cursor parameter to continue. Opaque.

`Event`

Field	Type	Required	Description
`object`	object	yes
`id`	string	yes	Stable: the same event has the same id however often it is read.
`type`	decision.created \| decision.updated \| decision.resolved	yes
`topic`	string	yes
`created`	string (date-time)	yes
`cursor`	string	yes	Pass as after to resume after this event.
`data`	object	yes

`EventList`

Events in ledger order. A page ends at an event not yet due for the caller; the same cursor returns it once it is.

Field	Type	Required	Description
`object`	object	yes
`data`	array of Event	yes
`has_more`	boolean	yes
`next_cursor`	string \| null	yes	Pass as the cursor parameter to continue. Opaque.