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
orgRequiredstringslugRequiredstring
Answer (200)
versionsarray
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
orgRequiredstringslugRequiredstring
Body
labelOptionalstring or null
Answer (200)
idstringnumberintegerImmutable publication sequence used by /v/{number} and runtime pins.semanticVersionstringAutomatically calculated consumer-impact version, such as 2.1.0.releaseTypestringOne ofinitial,major,minor,patchchangeSummaryarray of { "severity": string, "area": string, "path": string, "message": string }labelstring or nulldefinitionHashstringreadmeHashstringplanHashstringcompilerVersionstringproviderstringproviderModelstringpublishedByintegerpublishedAtstringreadmeMarkdownstringdefinitionobjectThe authored Definition:format: 3,model,state_schema, optionalcontextandquestions.definitionSourcestringdefinitionSourceFormatstringOne ofyaml,jsonplanobjectThe compiled ExecutionPlan. Its shape is owned by
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
orgRequiredstringslugRequiredstring
Answer (200)
idstringnumberintegerImmutable publication sequence used by /v/{number} and runtime pins.semanticVersionstringAutomatically calculated consumer-impact version, such as 2.1.0.releaseTypestringOne ofinitial,major,minor,patchchangeSummaryarray of { "severity": string, "area": string, "path": string, "message": string }labelstring or nulldefinitionHashstringreadmeHashstringplanHashstringcompilerVersionstringproviderstringproviderModelstringpublishedByintegerpublishedAtstringreadmeMarkdownstringdefinitionobjectThe authored Definition:format: 3,model,state_schema, optionalcontextandquestions.definitionSourcestringdefinitionSourceFormatstringOne ofyaml,jsonplanobjectThe compiled ExecutionPlan. Its shape is owned by
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
orgRequiredstringslugRequiredstringnumberRequiredinteger
Answer (200)
idstringnumberintegerImmutable publication sequence used by /v/{number} and runtime pins.semanticVersionstringAutomatically calculated consumer-impact version, such as 2.1.0.releaseTypestringOne ofinitial,major,minor,patchchangeSummaryarray of { "severity": string, "area": string, "path": string, "message": string }labelstring or nulldefinitionHashstringreadmeHashstringplanHashstringcompilerVersionstringproviderstringproviderModelstringpublishedByintegerpublishedAtstringreadmeMarkdownstringdefinitionobjectThe authored Definition:format: 3,model,state_schema, optionalcontextandquestions.definitionSourcestringdefinitionSourceFormatstringOne ofyaml,jsonplanobjectThe compiled ExecutionPlan. Its shape is owned by
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
orgRequiredstringslugRequiredstringnumberRequiredinteger
Headers
X-TypeSafe-KeyOptionalstring
Body
inputRequiredstring or object or arrayDynamic TypeSafe state: a string, object, or array, checked by state_schema.
Answer (200)
idstringversionIdstring or nullNull when the run executed the draft; see draftHash.draftHashstring or nullrolestring or nullFor served runs, which part of the deployment this was; null otherwise.One ofprimary,variant,compatible,shadowenvironmentstringsourcestringactorTypestringactorIdstringstartedAtstringlatencyMsintegerinputstring or object or arrayDynamic TypeSafe state: a string, object, or array, checked by state_schema.answersobject or nullNative TypeSafe answers, keyed by question id; a list in item order for aneachquestion.inputTokensinteger or nullInput tokens, as the provider reported them.outputTokensinteger or nullitemCountinteger or nullItems judged by per-item (each) questions; null for a Decision without them.statusstringerrorstring or nullapplicationIdstring or nullThe calling software (its key's Application); null for sandbox and test runs.referenceobject or nullWhat the call was about, in the caller's terms.reference.typestringreference.idstringcorrelationIdstring or nullThe thread of calls it belongs to.sealIdstring or nullThe seal that fixed its content in the audit chain; null until the next seal.responseOriginstring or nullWhere the provider's response came from:providerwhen TypeFuse received it from TypeSafe itself (Managed, BYOK),callerwhen 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 ofprovider,callerplanHashstringcompletedAtstringstateobjectThe state exactly as sent to the provider.providerstringproviderModelstring or nullproviderRequestIdstring or nullusageobject or nullusage.inputTokensintegerusage.outputTokensintegerproofobjectOn a single run: its content hashes and seal.proof.planHashstringproof.inputHashstring or nullproof.stateHashstring or nullproof.answersHashstring or nullproof.sealobject or nullversionNumberinteger or nullOn a single run: the number of the version it ran (versionId's), null for a draft run.servedByobject or nullOn 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.deploymentIdstringservedBy.liveAtstringWhen the deployment went live.servedBy.requestedByobject or nullThe person or deploy token that asked for it; null when neither is known any more.servedBy.approvedBystring or nullservedBy.approvedAtstring or nullservedBy.selfApprovedbooleanThe person who approved it also asked for it (the only owner or admin).notStoredstringPresent 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;inputis then empty andstateis{}.
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
orgRequiredstringslugRequiredstring
Answer (200)
modelstringThe model of the release live in production, else the latest release, else the draft.versionobject or nullThat release; null when nothing is published.version.numberintegerversion.semanticVersionstringretirementobject or nullWhen a model retires, once the provider announces a date.retirement.datestringISO date (YYYY-MM-DD) its calls stop.retirement.daysLeftintegerWhole days left; 0 once it has retired.newerobject or nullThe newest released model of the same family, when it is newer.newer.modelstringnewer.releasedstring or nullISO date the provider released it; null when not recorded.latestTrialobject or nullThe latest trial ofnewer, so a choice to stay is remembered.latestTrial.idstringlatestTrial.fromModelstringThe model the release tried was published with.latestTrial.modelstringThe model tried in its place.latestTrial.outcomestring or nullNull until someone releases the new model or stays.One ofreleased,stayedlatestTrial.releasedVersionIdstring or nullThe version a release made.latestTrial.createdAtstring or nulllatestTrial.decidedAtstring or null
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
orgRequiredstringslugRequiredstring
Query
modelOptionalstring
Answer (200)
trialsarray
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
orgRequiredstringslugRequiredstring
Headers
X-TypeSafe-KeyOptionalstring
Body
modelOptionalstringAn exact model version, as a Definition'smodelnames one; the newer model by default.
Answer (201)
idstringfromModelstringThe model the release tried was published with.modelstringThe model tried in its place.outcomestring or nullNull until someone releases the new model or stays.One ofreleased,stayedreleasedVersionIdstring or nullThe version a release made.createdAtstring or nulldecidedAtstring or nullversionobject or nullThe release tried.version.numberintegerversion.semanticVersionstringreleasedobject or nullThe version a release made.released.numberintegerreleased.semanticVersionstringbaselineobjectOne side of a trial: the Test run on one model and its evaluation.baseline.testRunIdstringbaseline.evaluationIdstring or nullbaseline.caseCountintegerbaseline.agreedCountintegerbaseline.errorCountintegerbaseline.latencyMsintegercandidateobjectOne side of a trial: the Test run on one model and its evaluation.candidate.testRunIdstringcandidate.evaluationIdstring or nullcandidate.caseCountintegercandidate.agreedCountintegercandidate.errorCountintegercandidate.latencyMsintegerchangedarrayundecidedintegerChanged cases not yet decided; releasing waits for none.
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
orgRequiredstringslugRequiredstringtrialIdRequiredstring
Answer (200)
idstringfromModelstringThe model the release tried was published with.modelstringThe model tried in its place.outcomestring or nullNull until someone releases the new model or stays.One ofreleased,stayedreleasedVersionIdstring or nullThe version a release made.createdAtstring or nulldecidedAtstring or nullversionobject or nullThe release tried.version.numberintegerversion.semanticVersionstringreleasedobject or nullThe version a release made.released.numberintegerreleased.semanticVersionstringbaselineobjectOne side of a trial: the Test run on one model and its evaluation.baseline.testRunIdstringbaseline.evaluationIdstring or nullbaseline.caseCountintegerbaseline.agreedCountintegerbaseline.errorCountintegerbaseline.latencyMsintegercandidateobjectOne side of a trial: the Test run on one model and its evaluation.candidate.testRunIdstringcandidate.evaluationIdstring or nullcandidate.caseCountintegercandidate.agreedCountintegercandidate.errorCountintegercandidate.latencyMsintegerchangedarrayundecidedintegerChanged cases not yet decided; releasing waits for none.
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
orgRequiredstringslugRequiredstringtrialIdRequiredstringcaseIdRequiredstring
Body
rightRequiredstringWhich model answered the case rightly. "candidate" makes the case expect its answers.One ofbaseline,candidate
Answer (200)
idstringfromModelstringThe model the release tried was published with.modelstringThe model tried in its place.outcomestring or nullNull until someone releases the new model or stays.One ofreleased,stayedreleasedVersionIdstring or nullThe version a release made.createdAtstring or nulldecidedAtstring or nullversionobject or nullThe release tried.version.numberintegerversion.semanticVersionstringreleasedobject or nullThe version a release made.released.numberintegerreleased.semanticVersionstringbaselineobjectOne side of a trial: the Test run on one model and its evaluation.baseline.testRunIdstringbaseline.evaluationIdstring or nullbaseline.caseCountintegerbaseline.agreedCountintegerbaseline.errorCountintegerbaseline.latencyMsintegercandidateobjectOne side of a trial: the Test run on one model and its evaluation.candidate.testRunIdstringcandidate.evaluationIdstring or nullcandidate.caseCountintegercandidate.agreedCountintegercandidate.errorCountintegercandidate.latencyMsintegerchangedarrayundecidedintegerChanged cases not yet decided; releasing waits for none.
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
orgRequiredstringslugRequiredstringtrialIdRequiredstring
Answer (201)
trialobjectA trial of another model: both sides' figures and the cases that changed.trial.idstringtrial.fromModelstringThe model the release tried was published with.trial.modelstringThe model tried in its place.trial.outcomestring or nullNull until someone releases the new model or stays.One ofreleased,stayedtrial.releasedVersionIdstring or nullThe version a release made.trial.createdAtstring or nulltrial.decidedAtstring or nulltrial.versionobject or nullThe release tried.trial.releasedobject or nullThe version a release made.trial.baselineobjectOne side of a trial: the Test run on one model and its evaluation.trial.candidateobjectOne side of a trial: the Test run on one model and its evaluation.trial.changedarraytrial.undecidedintegerChanged cases not yet decided; releasing waits for none.versionobjectversion.numberintegerversion.semanticVersionstringversion.releaseTypestringOne ofinitial,major,minor,patch,nonedraftMovedbooleanThe draft followed, because it matched the latest release; otherwise it is left as it was.
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
orgRequiredstringslugRequiredstringtrialIdRequiredstring
Answer (200)
idstringfromModelstringThe model the release tried was published with.modelstringThe model tried in its place.outcomestring or nullNull until someone releases the new model or stays.One ofreleased,stayedreleasedVersionIdstring or nullThe version a release made.createdAtstring or nulldecidedAtstring or nullversionobject or nullThe release tried.version.numberintegerversion.semanticVersionstringreleasedobject or nullThe version a release made.released.numberintegerreleased.semanticVersionstringbaselineobjectOne side of a trial: the Test run on one model and its evaluation.baseline.testRunIdstringbaseline.evaluationIdstring or nullbaseline.caseCountintegerbaseline.agreedCountintegerbaseline.errorCountintegerbaseline.latencyMsintegercandidateobjectOne side of a trial: the Test run on one model and its evaluation.candidate.testRunIdstringcandidate.evaluationIdstring or nullcandidate.caseCountintegercandidate.agreedCountintegercandidate.errorCountintegercandidate.latencyMsintegerchangedarrayundecidedintegerChanged cases not yet decided; releasing waits for none.
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>/stay" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"