API 參考

Kalkas API

REST API 的所有端點、參數及物件，直接由其 OpenAPI 文件生成。API 只供讀取：它提供資訊，從不在任何人的帳戶內行事。

版本: 2026-10-03
基本網址: https://api.kalkas.ai

參考內容與 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.

端點

`GET /v1/topics`

List topics

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

參數	位置	類型	必填	說明
`Kalkas-Version`	header	2026-10-03	否	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	否	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	否	Page size, 1 to 100.
`starting_after`	query	string	否	The next_cursor of the previous page.

回應

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.

參數	位置	類型	必填	說明
`Kalkas-Version`	header	2026-10-03	否	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	否	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	否	Page size, 1 to 100.
`starting_after`	query	string	否	The next_cursor of the previous page.
`topic`	query	string	否	Only this decisions topic.
`status`	query	open \| resolved	否	open: not yet resolved. resolved: settled, void or ambiguous.
`subject`	query	string	否	Only questions about this entity key.

回應

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.

參數	位置	類型	必填	說明
`Kalkas-Version`	header	2026-10-03	否	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	否	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	是
`expand[]`	query	analysis	否	analysis adds every forecaster's latest forecast.

回應

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.

參數	位置	類型	必填	說明
`Kalkas-Version`	header	2026-10-03	否	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	否	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	否	Only this decisions topic.

回應

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.

參數	位置	類型	必填	說明
`Kalkas-Version`	header	2026-10-03	否	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	否	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	否	Page size, 1 to 100.
`after`	query	string	否	The cursor of the last event read (or next_cursor of the previous page). Absent: from the start.
`types`	query	string	否	Comma-separated event types.
`topics`	query	string	否	Comma-separated decisions topics.

回應

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

參數	位置	類型	必填	說明
`Kalkas-Version`	header	2026-10-03	否	The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.
`Idempotency-Key`	header	string	否	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.

回應

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)

物件

`Error`

欄位	類型	必填	說明
`error`	object	是

`Topic`

欄位	類型	必填	說明
`object`	object	是
`id`	string	是
`domain`	string	是
`kind`	decisions \| analysis	是
`title`	string	是
`held`	boolean	是	Whether the caller holds a grant for the topic.

`TopicList`

Every topic Kalkas offers, by id.

欄位	類型	必填	說明
`object`	object	是
`data`	array of Topic	是
`has_more`	boolean	是
`next_cursor`	string \| null	是	Pass as the cursor parameter to continue. Opaque.

`Forecast`

One forecaster's latest forecast on a question.

欄位	類型	必填
`forecaster_kind`	string	是
`forecaster_version`	string	是
`probability`	number	是
`market_probability`	number \| null	是
`known_at`	string (date-time)	是

`Decision`

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

`DecisionList`

The decisions, newest first.

欄位	類型	必填	說明
`object`	object	是
`data`	array of Decision	是
`has_more`	boolean	是
`next_cursor`	string \| null	是	Pass as the cursor parameter to continue. Opaque.

`ScoreRow`

欄位	類型	必填
`class`	string	是
`forecaster`	string	是
`forecaster_kind`	string	是
`n`	integer	是
`edge_vs_market`	number \| null	是
`log_loss`	number	是
`brier`	number	是
`mean_p`	number	是
`hit_rate`	number	是
`calibration_slope`	number \| null	是
`ece`	number	是
`calibration_flag`	string \| null	是

`Reliability`

欄位	類型	必填
`class`	string	是
`forecaster`	string	是
`forecaster_kind`	string	是
`n`	integer	是
`bins`	array of object	是

`Record`

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

欄位	類型	必填
`object`	object	是
`topic`	string	是
`domain`	string	是
`as_of`	string (date-time)	是
`resolved_questions`	integer	是
`void_questions`	integer	是
`trials`	integer	是
`scores`	array of ScoreRow	是
`calibration`	array of Reliability	是
`closing_line_value`	object	是
`attribution`	array of string	是

`RecordList`

One record per held decisions topic.

欄位	類型	必填	說明
`object`	object	是
`data`	array of Record	是
`has_more`	boolean	是
`next_cursor`	string \| null	是	Pass as the cursor parameter to continue. Opaque.

`Event`

欄位	類型	必填	說明
`object`	object	是
`id`	string	是	Stable: the same event has the same id however often it is read.
`type`	decision.created \| decision.updated \| decision.resolved	是
`topic`	string	是
`created`	string (date-time)	是
`cursor`	string	是	Pass as after to resume after this event.
`data`	object	是

`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.

欄位	類型	必填	說明
`object`	object	是
`data`	array of Event	是
`has_more`	boolean	是
`next_cursor`	string \| null	是	Pass as the cursor parameter to continue. Opaque.