Skip to content

Reference

API: Versions and models

Publish versions, run them, and try a newer model before you move to it.

Part of the API reference: requests carry a personal access token as Authorization: Bearer <token>, and bodies and answers are JSON.

Versions

GET /v1/organisations/{org}/decisions/{slug}/versions

List versions

Path

  • orgRequiredstring
  • slugRequiredstring

Answer (200)

  • versionsarray
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/versions" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/versions

Publish a version

Path

  • orgRequiredstring
  • slugRequiredstring

Body

  • labelOptionalstring or null

Answer (200)

  • idstring
  • numberinteger
    Immutable publication sequence used by /v/{number} and runtime pins.
  • semanticVersionstring
    Automatically calculated consumer-impact version, such as 2.1.0.
  • releaseTypestring
    One of initial, major, minor, patch
  • changeSummaryarray of { "severity": string, "area": string, "path": string, "message": string }
  • labelstring or null
  • definitionHashstring
  • readmeHashstring
  • planHashstring
  • compilerVersionstring
  • providerstring
  • providerModelstring
  • publishedByinteger
  • publishedAtstring
  • readmeMarkdownstring
  • definitionobject
    The authored Definition: format: 3, model, state_schema, optional context and questions.
  • definitionSourcestring
  • definitionSourceFormatstring
    One of yaml, json
  • planobject
    The compiled ExecutionPlan. Its shape is owned by
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/versions" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /v1/organisations/{org}/decisions/{slug}/versions/latest

Get the latest version

The newest version whole (the highest number); 404 NOT_FOUND before the first.

Path

  • orgRequiredstring
  • slugRequiredstring

Answer (200)

  • idstring
  • numberinteger
    Immutable publication sequence used by /v/{number} and runtime pins.
  • semanticVersionstring
    Automatically calculated consumer-impact version, such as 2.1.0.
  • releaseTypestring
    One of initial, major, minor, patch
  • changeSummaryarray of { "severity": string, "area": string, "path": string, "message": string }
  • labelstring or null
  • definitionHashstring
  • readmeHashstring
  • planHashstring
  • compilerVersionstring
  • providerstring
  • providerModelstring
  • publishedByinteger
  • publishedAtstring
  • readmeMarkdownstring
  • definitionobject
    The authored Definition: format: 3, model, state_schema, optional context and questions.
  • definitionSourcestring
  • definitionSourceFormatstring
    One of yaml, json
  • planobject
    The compiled ExecutionPlan. Its shape is owned by
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/versions/latest" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

GET /v1/organisations/{org}/decisions/{slug}/versions/{number}

Get a version

Path

  • orgRequiredstring
  • slugRequiredstring
  • numberRequiredinteger

Answer (200)

  • idstring
  • numberinteger
    Immutable publication sequence used by /v/{number} and runtime pins.
  • semanticVersionstring
    Automatically calculated consumer-impact version, such as 2.1.0.
  • releaseTypestring
    One of initial, major, minor, patch
  • changeSummaryarray of { "severity": string, "area": string, "path": string, "message": string }
  • labelstring or null
  • definitionHashstring
  • readmeHashstring
  • planHashstring
  • compilerVersionstring
  • providerstring
  • providerModelstring
  • publishedByinteger
  • publishedAtstring
  • readmeMarkdownstring
  • definitionobject
    The authored Definition: format: 3, model, state_schema, optional context and questions.
  • definitionSourcestring
  • definitionSourceFormatstring
    One of yaml, json
  • planobject
    The compiled ExecutionPlan. Its shape is owned by
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/versions/3" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/versions/{number}/run

Run a version

Path

  • orgRequiredstring
  • slugRequiredstring
  • numberRequiredinteger

Headers

  • X-TypeSafe-KeyOptionalstring

Body

  • inputRequiredstring or object or array
    Dynamic TypeSafe state: a string, object, or array, checked by state_schema.

Answer (200)

  • idstring
  • versionIdstring or null
    Null when the run executed the draft; see draftHash.
  • draftHashstring or null
  • rolestring or null
    For served runs, which part of the deployment this was; null otherwise.One of primary, variant, compatible, shadow
  • environmentstring
  • sourcestring
  • actorTypestring
  • actorIdstring
  • startedAtstring
  • latencyMsinteger
  • inputstring or object or array
    Dynamic TypeSafe state: a string, object, or array, checked by state_schema.
  • answersobject or null
    Native TypeSafe answers, keyed by question id; a list in item order for an each question.
  • inputTokensinteger or null
    Input tokens, as the provider reported them.
  • outputTokensinteger or null
  • itemCountinteger or null
    Items judged by per-item (each) questions; null for a Decision without them.
  • statusstring
  • errorstring or null
  • applicationIdstring or null
    The calling software (its key's Application); null for sandbox and test runs.
  • referenceobject or null
    What the call was about, in the caller's terms.
  • reference.typestring
  • reference.idstring
  • correlationIdstring or null
    The thread of calls it belongs to.
  • sealIdstring or null
    The seal that fixed its content in the audit chain; null until the next seal.
  • responseOriginstring or null
    Where the provider's response came from: provider when TypeFuse received it from TypeSafe itself (Managed, BYOK), caller when the caller reported it (Relay, and the removed record-only mode). Null for runs from before it was recorded. Included in the run's seal.One of provider, caller
  • planHashstring
  • completedAtstring
  • stateobject
    The state exactly as sent to the provider.
  • providerstring
  • providerModelstring or null
  • providerRequestIdstring or null
  • usageobject or null
  • usage.inputTokensinteger
  • usage.outputTokensinteger
  • proofobject
    On a single run: its content hashes and seal.
  • proof.planHashstring
  • proof.inputHashstring or null
  • proof.stateHashstring or null
  • proof.answersHashstring or null
  • proof.sealobject or null
  • versionNumberinteger or null
    On a single run: the number of the version it ran (versionId's), null for a draft run.
  • servedByobject or null
    On a single served call: the deployment that answered it, who asked for it and who approved it. Null for Sandbox, Test set and Evaluation runs.
  • servedBy.deploymentIdstring
  • servedBy.liveAtstring
    When the deployment went live.
  • servedBy.requestedByobject or null
    The person or deploy token that asked for it; null when neither is known any more.
  • servedBy.approvedBystring or null
  • servedBy.approvedAtstring or null
  • servedBy.selfApprovedboolean
    The person who approved it also asked for it (the only owner or admin).
  • notStoredstring
    Present when the run's stored input and the state sent to the model have expired under the plan's retention (or the Sandbox's): the sentence that says so. The run keeps its answers, hashes and seal; input is then empty and state is {}.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/versions/3/run" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"<input>"}'

Models

GET /v1/organisations/{org}/decisions/{slug}/model

Get the model status

Moving to a newer model: where the Decision's model stands (the release live in production, else the latest), a newer model to try and a retirement date.

Path

  • orgRequiredstring
  • slugRequiredstring

Answer (200)

  • modelstring
    The model of the release live in production, else the latest release, else the draft.
  • versionobject or null
    That release; null when nothing is published.
  • version.numberinteger
  • version.semanticVersionstring
  • retirementobject or null
    When a model retires, once the provider announces a date.
  • retirement.datestring
    ISO date (YYYY-MM-DD) its calls stop.
  • retirement.daysLeftinteger
    Whole days left; 0 once it has retired.
  • newerobject or null
    The newest released model of the same family, when it is newer.
  • newer.modelstring
  • newer.releasedstring or null
    ISO date the provider released it; null when not recorded.
  • latestTrialobject or null
    The latest trial of newer, so a choice to stay is remembered.
  • latestTrial.idstring
  • latestTrial.fromModelstring
    The model the release tried was published with.
  • latestTrial.modelstring
    The model tried in its place.
  • latestTrial.outcomestring or null
    Null until someone releases the new model or stays.One of released, stayed
  • latestTrial.releasedVersionIdstring or null
    The version a release made.
  • latestTrial.createdAtstring or null
  • latestTrial.decidedAtstring or null
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

GET /v1/organisations/{org}/decisions/{slug}/model-trials

List model trials

Newest first; model narrows to trials of one model.

Path

  • orgRequiredstring
  • slugRequiredstring

Query

  • modelOptionalstring

Answer (200)

  • trialsarray
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/model-trials

Start a model trial

Asks the Test set of the release live in production (or else the latest release) twice: as published and with only its model changed. The draft is untouched. model defaults to the newer model GET …/model names; only a newer, released model can be tried. 422 INVALID_MODEL, UNKNOWN_MODEL, NOT_NEWER, SAME_MODEL, MODEL_RETIRED, NO_CASES or INVALID_CASES; 409 NO_RELEASE. With X-TypeSafe-Key the trial runs on your own TypeSafe key.

Path

  • orgRequiredstring
  • slugRequiredstring

Headers

  • X-TypeSafe-KeyOptionalstring

Body

  • modelOptionalstring
    An exact model version, as a Definition's model names one; the newer model by default.

Answer (201)

  • idstring
  • fromModelstring
    The model the release tried was published with.
  • modelstring
    The model tried in its place.
  • outcomestring or null
    Null until someone releases the new model or stays.One of released, stayed
  • releasedVersionIdstring or null
    The version a release made.
  • createdAtstring or null
  • decidedAtstring or null
  • versionobject or null
    The release tried.
  • version.numberinteger
  • version.semanticVersionstring
  • releasedobject or null
    The version a release made.
  • released.numberinteger
  • released.semanticVersionstring
  • baselineobject
    One side of a trial: the Test run on one model and its evaluation.
  • baseline.testRunIdstring
  • baseline.evaluationIdstring or null
  • baseline.caseCountinteger
  • baseline.agreedCountinteger
  • baseline.errorCountinteger
  • baseline.latencyMsinteger
  • candidateobject
    One side of a trial: the Test run on one model and its evaluation.
  • candidate.testRunIdstring
  • candidate.evaluationIdstring or null
  • candidate.caseCountinteger
  • candidate.agreedCountinteger
  • candidate.errorCountinteger
  • candidate.latencyMsinteger
  • changedarray
  • undecidedinteger
    Changed cases not yet decided; releasing waits for none.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}

Get a model trial

Path

  • orgRequiredstring
  • slugRequiredstring
  • trialIdRequiredstring

Answer (200)

  • idstring
  • fromModelstring
    The model the release tried was published with.
  • modelstring
    The model tried in its place.
  • outcomestring or null
    Null until someone releases the new model or stays.One of released, stayed
  • releasedVersionIdstring or null
    The version a release made.
  • createdAtstring or null
  • decidedAtstring or null
  • versionobject or null
    The release tried.
  • version.numberinteger
  • version.semanticVersionstring
  • releasedobject or null
    The version a release made.
  • released.numberinteger
  • released.semanticVersionstring
  • baselineobject
    One side of a trial: the Test run on one model and its evaluation.
  • baseline.testRunIdstring
  • baseline.evaluationIdstring or null
  • baseline.caseCountinteger
  • baseline.agreedCountinteger
  • baseline.errorCountinteger
  • baseline.latencyMsinteger
  • candidateobject
    One side of a trial: the Test run on one model and its evaluation.
  • candidate.testRunIdstring
  • candidate.evaluationIdstring or null
  • candidate.caseCountinteger
  • candidate.agreedCountinteger
  • candidate.errorCountinteger
  • candidate.latencyMsinteger
  • changedarray
  • undecidedinteger
    Changed cases not yet decided; releasing waits for none.
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}/cases/{caseId}

Decide a trial case

Which model was right about a case that changed. 404 CASE_NOT_FOUND; 409 NOT_CHANGED, CASE_CHANGED (its input was edited after the trial) or ALREADY_DECIDED; 422 CASE_INVALID.

Path

  • orgRequiredstring
  • slugRequiredstring
  • trialIdRequiredstring
  • caseIdRequiredstring

Body

  • rightRequiredstring
    Which model answered the case rightly. "candidate" makes the case expect its answers.One of baseline, candidate

Answer (200)

  • idstring
  • fromModelstring
    The model the release tried was published with.
  • modelstring
    The model tried in its place.
  • outcomestring or null
    Null until someone releases the new model or stays.One of released, stayed
  • releasedVersionIdstring or null
    The version a release made.
  • createdAtstring or null
  • decidedAtstring or null
  • versionobject or null
    The release tried.
  • version.numberinteger
  • version.semanticVersionstring
  • releasedobject or null
    The version a release made.
  • released.numberinteger
  • released.semanticVersionstring
  • baselineobject
    One side of a trial: the Test run on one model and its evaluation.
  • baseline.testRunIdstring
  • baseline.evaluationIdstring or null
  • baseline.caseCountinteger
  • baseline.agreedCountinteger
  • baseline.errorCountinteger
  • baseline.latencyMsinteger
  • candidateobject
    One side of a trial: the Test run on one model and its evaluation.
  • candidate.testRunIdstring
  • candidate.evaluationIdstring or null
  • candidate.caseCountinteger
  • candidate.agreedCountinteger
  • candidate.errorCountinteger
  • candidate.latencyMsinteger
  • changedarray
  • undecidedinteger
    Changed cases not yet decided; releasing waits for none.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>/cases/<caseId>" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"right":"baseline"}'

POST /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}/release

Release the trial's model

Publishes the latest release with only its model changed (a minor release). 409 ALREADY_DECIDED, TRIAL_OUTDATED (a later release changed the Decision), ALREADY_ON_MODEL or NO_RELEASE; 422 CASES_UNDECIDED, MODEL_RETIRED, SOURCE_UNCHANGEABLE or COMPILE_FAILED.

Path

  • orgRequiredstring
  • slugRequiredstring
  • trialIdRequiredstring

Answer (201)

  • trialobject
    A trial of another model: both sides' figures and the cases that changed.
  • trial.idstring
  • trial.fromModelstring
    The model the release tried was published with.
  • trial.modelstring
    The model tried in its place.
  • trial.outcomestring or null
    Null until someone releases the new model or stays.One of released, stayed
  • trial.releasedVersionIdstring or null
    The version a release made.
  • trial.createdAtstring or null
  • trial.decidedAtstring or null
  • trial.versionobject or null
    The release tried.
  • trial.releasedobject or null
    The version a release made.
  • trial.baselineobject
    One side of a trial: the Test run on one model and its evaluation.
  • trial.candidateobject
    One side of a trial: the Test run on one model and its evaluation.
  • trial.changedarray
  • trial.undecidedinteger
    Changed cases not yet decided; releasing waits for none.
  • versionobject
  • version.numberinteger
  • version.semanticVersionstring
  • version.releaseTypestring
    One of initial, major, minor, patch, none
  • draftMovedboolean
    The draft followed, because it matched the latest release; otherwise it is left as it was.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>/release" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}/stay

Stay on the current model

Stays on the current model; kept, so the Summary stops asking. 409 ALREADY_DECIDED.

Path

  • orgRequiredstring
  • slugRequiredstring
  • trialIdRequiredstring

Answer (200)

  • idstring
  • fromModelstring
    The model the release tried was published with.
  • modelstring
    The model tried in its place.
  • outcomestring or null
    Null until someone releases the new model or stays.One of released, stayed
  • releasedVersionIdstring or null
    The version a release made.
  • createdAtstring or null
  • decidedAtstring or null
  • versionobject or null
    The release tried.
  • version.numberinteger
  • version.semanticVersionstring
  • releasedobject or null
    The version a release made.
  • released.numberinteger
  • released.semanticVersionstring
  • baselineobject
    One side of a trial: the Test run on one model and its evaluation.
  • baseline.testRunIdstring
  • baseline.evaluationIdstring or null
  • baseline.caseCountinteger
  • baseline.agreedCountinteger
  • baseline.errorCountinteger
  • baseline.latencyMsinteger
  • candidateobject
    One side of a trial: the Test run on one model and its evaluation.
  • candidate.testRunIdstring
  • candidate.evaluationIdstring or null
  • candidate.caseCountinteger
  • candidate.agreedCountinteger
  • candidate.errorCountinteger
  • candidate.latencyMsinteger
  • changedarray
  • undecidedinteger
    Changed cases not yet decided; releasing waits for none.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>/stay" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"