Skip to content

Developers

API reference

Every route of the Helm Decision API, grouped by what it serves. Each row is the contract’s own summary.

Authenticating a request

Authorization: Bearer pt_live_<16 hex>_<43 base64url>
HeaderSend your key as a bearer token. Browser sessions are refused with 401 api_key_required.
The key68 characters, shown once; a lost key is replaced, not retrieved. If you parse one, parse by offset: the secret can contain _.
ScopesTwo, fixed when the key is created. read views places, jobs and results; spend is needed for every billed route and for the 12 free routes marked spend in the Reference. Without it a key gets 403 insufficient_scope. Give an agent a read-only key; in an organization, only an admin can create a key with spend.
RevokingTakes effect within 60 seconds, or up to 15 minutes during an outage.
RotatingCreate a new key, deploy it, confirm its key_id on GET /v1/me, then revoke the old one.

The Helm Decision API

26 operations
MethodPathScopeWhat it does
GET/v1/modelsreadEvery model this key can call — yours, helm-default, the case tasks. listModels
GET/v1/models/{task}/versions/{version}readOne model version's card — what it reads, what it ignores, and its holdout. getModelCard
GET/v1/models/{model}/schemareadWhat one of your models reads — the fields a record carries and how each is read. getDecisionModelSchema
GET/v1/models/{model}/cardreadOne version's card — its forward-test scorecard, gate, audit and provenance. getDecisionModelCard
POST/v1/models/{model}/forecastsspendForecast 1–100 records with one of your models, each sealed with its reasons before it is returned. createDecisionForecasts
GET/v1/models/{model}/forecastsreadYour sealed forecasts for one model, newest first, each with its current outcome. listDecisionForecasts
POST/v1/models/{model}/outcomesspendRecord what happened, by outcome key, so forecasts can be scored. recordDecisionOutcomes
GET/v1/models/{model}/track-recordreadA version's live record over your resolved forecasts, beside its card. getDecisionTrackRecord
GET/v1/models/{model}/queuereadThe ranked queue — open items, highest chance first, one row per item. getDecisionQueue
GET/v1/models/{model}/forecasts/{id}readOne sealed decision in full — inputs, who asked, outcome and its revisions. getDecisionForecast
GET/v1/models/{model}/forecasts/{id}/receiptreadThe decision's receipt — the bytes it was sealed with, its chain to the day's head, and the day's root once sealed. getDecisionForecastReceipt
GET/v1/models/{model}/rollupreadExpected money by segment, from the model's chances and the values entered for it — never a reserve. getDecisionRollup
POST/v1/models/{model}/batchesspendScore a whole file of open cases with one of your models, as a job. createDecisionBatch
GET/v1/models/{model}/batchesreadThis model's scored files, newest first. listDecisionBatches
GET/v1/models/{model}/batches/{id}readOne scored file's state, counts and the caller's headroom under the daily cap. getDecisionBatch
DELETE/v1/models/{model}/batches/{id}spendDelete a scored file and its results here; its forecasts stay in the sealed log. deleteDecisionBatch
GET/v1/models/{model}/batches/{id}/resultsreadA scored file's rows in file order, each with its sealed answer or every reason it was refused. getDecisionBatchResults
POST/v1/models/{model}/batches/{id}/runspendStart a draft scored file, or resume one that stopped. runDecisionBatch
POST/v1/models/{model}/batches/{id}/cancelspendStop a scored file for good after the chunk in hand. cancelDecisionBatch
POST/v1/models/{model}/trainspendTrain the Baseline from the model's checks, as the model page's Train does. trainDecisionModel
POST/v1/models/{model}/retrainspendRetrain a published model now, as the model page's Retrain now does. retrainDecisionModel
GET/v1/models/{model}/trainings/{id}readOne training attempt of a model, with its runs. getDecisionTraining
POST/v1/models/{model}/training-imagesspendSend back the images of decisions that have an outcome, to train this model on its own outcomes. createDecisionTrainingImages
GET/v1/models/{model}/training-imagesreadThe images sent back to train this model, newest first, or with summary=1 what training on them still needs. listDecisionTrainingImages
DELETE/v1/models/{model}/training-images/{id}spendDelete one image sent back for training, at once; no training uses it again. deleteDecisionTrainingImage
POST/v1/systemonespendA decision request — a state and typed questions — answered by one of your models or by helm-default. createSystemOneAnswer

Webhooks

2 operations
MethodPathScopeWhat it does
GET/v1/webhook-deliveriesreadWhat was delivered to your endpoints, newest first. listWebhookDeliveries
POST/v1/webhook-deliveries/{id}/replayspendSend one settled delivery again, keeping its event id. replayWebhookDelivery

The MCP connector

1 operation
MethodPathScopeWhat it does
POST/v1/mcpreadThe MCP connector — call the free, read-only operations here as tools. callMcp

Your key and the contract

2 operations
MethodPathScopeWhat it does
GET/v1/openapi.yamlany keyThis document. getOpenapiDocument
GET/v1/meany keyWhat this key is, and what is left of its day. getMe

The contract

  • The contract is GET /v1/openapi.yaml: all of /v1 in OpenAPI, read with no key.
  • /v1 only adds fields; breaking changes ship as /v2.
  • Only /v1 is supported. Other routes can change without notice.

Next