API reference.

Every route, parameter and object, straight from our OpenAPI document.

Base address: https://api.kalkas.ai

Download the OpenAPI document

The reference is written in English; the rest of the site is in your language.

On every request.

Both are optional headers.

Parameters
  • Kalkas-Versionheader2026-10-03 · optional

    The API version as a date. Absent: the latest. Unknown: 400 unsupported_version.

  • Idempotency-Keyheaderstring · optional

    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.

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.

Parameters
  • limitqueryinteger · optional

    Page size, 1 to 100.

  • starting_afterquerystring · optional

    The next_cursor of the previous page.

  • topicquerystring · optional

    Only this decisions topic.

  • statusqueryopen | resolved · optional

    open: not yet resolved. resolved: settled, void or ambiguous.

  • subjectquerystring · optional

    Only questions about this entity key.

Answers
  • 200DecisionList

    OK

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.

Parameters
  • idpathstring · required
  • expand[]queryanalysis · optional

    analysis adds every forecaster's latest forecast.

Answers
  • 200Decision

    OK

GET/v1/events

List events

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

Parameters
  • limitqueryinteger · optional

    Page size, 1 to 100.

  • afterquerystring · optional

    The cursor of the last event read (or next_cursor of the previous page). Absent: from the start.

  • typesquerystring · optional

    Comma-separated event types.

  • topicsquerystring · optional

    Comma-separated decisions topics.

Answers
  • 200EventList

    OK

GET/v1/record

Get the record

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

Parameters
  • topicquerystring · optional

    Only this decisions topic.

Answers
  • 200Record or RecordList

    OK

GET/v1/topics

List topics

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

Parameters
  • limitqueryinteger · optional

    Page size, 1 to 100.

  • starting_afterquerystring · optional

    The next_cursor of the previous page.

Answers
  • 200TopicList

    OK

Objects.

What the routes answer with.

Decision

Fields
  • analysislist of Forecast · optional

    Present only with expand[]=analysis.

  • attributionlist of string · required

    Text to show with the decision, from the data licences behind it.

  • committed_atstring (date-time) · required
  • digeststring · required

    Content digest of the decision fact.

  • domainstring · required
  • edgenumber or null · required
  • fair_oddsnumber or null · required

    1 / probability.

  • headlineobject or null · required
  • idstring · required

    The question's ledger key. URL-encode it in a path.

  • kalkas_paper_actionobject · required
  • kalkas_paper_action.actedboolean · required

    Whether Kalkas acted on its own paper book. Information only: there is no stake.

  • marketobject · required
  • market.probabilitynumber or null · required

    The de-vigged market probability at the time. No venue is named.

  • objectalways "decision" · required
  • probabilitynumber or null · required

    Kalkas's committed probability that the question resolves yes.

  • questionobject · required
  • question.classstring · required
  • question.deadlinestring (date-time) · required
  • question.groupstring or null · required
  • question.resolution_rulestring · required
  • question.subjectobject · required
  • question.subject.entitystring · required
  • question.subject.namestring or null · required
  • question.termsany · required

    The question's structured terms (a symbol, a start, a band), or null.

  • resolutionobject or null · required
  • scoreobject or null · required
  • seqstring · required

    The decision's position in decision lists.

  • standingunresolved | resolved | void | ambiguous · required
  • topicstring · required
  • versioninteger · required

    How many decisions Kalkas has committed on the question that this caller sees.

DecisionList

The decisions, newest first.

Fields
  • datalist of Decision · required
  • has_moreboolean · required
  • next_cursorstring or null · required

    Pass as the cursor parameter to continue. Opaque.

  • objectalways "list" · required

Error

Fields
  • errorobject · required
  • error.codestring · required

    The specific cause, stable within an API version.

  • error.messagestring · required

    For people. Not stable.

  • error.paramstring or null · required

    The parameter or header at fault, when one is.

  • error.request_idstring · required

    The Request-Id of the response; quote it in a report.

  • error.typeinvalid_request_error | authentication_error | permission_error | rate_limit_error | api_error · required

    The class of error: what the caller should do about it.

Event

Fields
  • createdstring (date-time) · required
  • cursorstring · required

    Pass as after to resume after this event.

  • dataobject · required
  • data.objectDecision · required
  • idstring · required

    Stable: the same event has the same id however often it is read.

  • objectalways "event" · required
  • topicstring · required
  • typedecision.created | decision.updated | decision.resolved · required

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.

Fields
  • datalist of Event · required
  • has_moreboolean · required
  • next_cursorstring or null · required

    Pass as the cursor parameter to continue. Opaque.

  • objectalways "list" · required

Forecast

One forecaster's latest forecast on a question.

Fields
  • forecaster_kindstring · required
  • forecaster_versionstring · required
  • known_atstring (date-time) · required
  • market_probabilitynumber or null · required
  • probabilitynumber · required

Record

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

Fields
  • as_ofstring (date-time) · required
  • attributionlist of string · required
  • calibrationlist of Reliability · required
  • closing_line_valueobject · required
  • closing_line_value.computableboolean · required
  • closing_line_value.meannumber or null · required
  • closing_line_value.ninteger · required
  • domainstring · required
  • objectalways "record" · required
  • resolved_questionsinteger · required
  • scoreslist of ScoreRow · required
  • topicstring · required
  • trialsinteger · required
  • void_questionsinteger · required

RecordList

One record per held decisions topic.

Fields
  • datalist of Record · required
  • has_moreboolean · required
  • next_cursorstring or null · required

    Pass as the cursor parameter to continue. Opaque.

  • objectalways "list" · required

Reliability

Fields
  • binslist of object · required
  • bins[].highnumber · required
  • bins[].hitsinteger · required
  • bins[].lownumber · required
  • bins[].lowernumber · required
  • bins[].mean_pnumber · required
  • bins[].ninteger · required
  • bins[].observednumber · required
  • bins[].uppernumber · required
  • classstring · required
  • forecasterstring · required
  • forecaster_kindstring · required
  • ninteger · required

ScoreRow

Fields
  • briernumber · required
  • calibration_flagstring or null · required
  • calibration_slopenumber or null · required
  • classstring · required
  • ecenumber · required
  • edge_vs_marketnumber or null · required
  • forecasterstring · required
  • forecaster_kindstring · required
  • hit_ratenumber · required
  • log_lossnumber · required
  • mean_pnumber · required
  • ninteger · required

Topic

Fields
  • domainstring · required
  • heldboolean · required

    Whether the caller holds a grant for the topic.

  • idstring · required
  • kinddecisions | analysis · required
  • objectalways "topic" · required
  • titlestring · required

TopicList

Every topic Kalkas offers, by id.

Fields
  • datalist of Topic · required
  • has_moreboolean · required
  • next_cursorstring or null · required

    Pass as the cursor parameter to continue. Opaque.

  • objectalways "list" · required

Errors.

Every route can answer these, in the shape of the Error object.

  • 400

    A malformed request: see error.code and error.param.

  • 403

    The caller holds no grant for the topic (permission_error).

  • 404

    Nothing at this id or path.

  • 405

    The route does not take this method; Allow names the one it does.

  • 409

    The request conflicts with an earlier one.

  • 503

    The ledger could not be read; retry after the Retry-After seconds.

How errors work →