Reference
API: Datasets and Comparisons
Upload or replay Datasets and compare two releases over them.
Part of the API reference: requests carry a personal access token as Authorization: Bearer <token>, and bodies and answers are JSON.
Datasets
GET /v1/organisations/{org}/decisions/{slug}/datasets
List Datasets
Path
orgRequiredstringslugRequiredstring
Answer (200)
datasetsarray
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/datasets" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"POST /v1/organisations/{org}/decisions/{slug}/datasets
Upload a Dataset
JSON { name, rows }, or JSONL as application/x-ndjson with ?name=.
Path
orgRequiredstringslugRequiredstring
Body
nameRequiredstringrowsRequiredarrayOne input (a JSON object) a row.
Answer (201)
idstringnamestringsourcestring"upload": rows sent by a person or agent; "replay": a snapshot of recorded production calls.One ofupload,replayreplayFilterobject or nullHow a replay Dataset chose its recorded runs.replayFilter.environmentstringreplayFilter.versionNumberinteger or nullreplayFilter.sincestring or nullISO times bounding when the recorded calls were answered.replayFilter.untilstring or nullreplayFilter.limitintegerrowCountintegerskippedNotStoredintegerFor a replay: matching recorded calls left out because their input is no longer stored.uniqueInputCountintegerbytesintegercreatedByintegercreatedByNamestringcreatedAtstringrefusedarray of { "line": integer, "message": string }Rows that were not JSON objects (or were too large), by line; the rest were kept.
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/datasets" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Refunds","rows":[]}'POST /v1/organisations/{org}/decisions/{slug}/datasets/replay
Replay production calls as a Dataset
Snapshots recorded production calls. Owners and admins (and full-scope tokens) only.
Path
orgRequiredstringslugRequiredstring
Body
environmentOptionalstringThe environment whose recorded calls to snapshot; default "production".versionNumberOptionalintegerOnly calls answered by this version.sinceOptionalstringISO time; ordaysfor the last N days.untilOptionalstringdaysOptionalintegerlimitOptionalintegerAt most this many of the most recent calls.nameOptionalstring
Answer (201)
idstringnamestringsourcestring"upload": rows sent by a person or agent; "replay": a snapshot of recorded production calls.One ofupload,replayreplayFilterobject or nullHow a replay Dataset chose its recorded runs.replayFilter.environmentstringreplayFilter.versionNumberinteger or nullreplayFilter.sincestring or nullISO times bounding when the recorded calls were answered.replayFilter.untilstring or nullreplayFilter.limitintegerrowCountintegerskippedNotStoredintegerFor a replay: matching recorded calls left out because their input is no longer stored.uniqueInputCountintegerbytesintegercreatedByintegercreatedByNamestringcreatedAtstring
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/datasets/replay" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'GET /v1/organisations/{org}/decisions/{slug}/datasets/{datasetId}
Get a Dataset
Path
orgRequiredstringslugRequiredstringdatasetIdRequiredstring
Answer (200)
idstringnamestringsourcestring"upload": rows sent by a person or agent; "replay": a snapshot of recorded production calls.One ofupload,replayreplayFilterobject or nullHow a replay Dataset chose its recorded runs.replayFilter.environmentstringreplayFilter.versionNumberinteger or nullreplayFilter.sincestring or nullISO times bounding when the recorded calls were answered.replayFilter.untilstring or nullreplayFilter.limitintegerrowCountintegerskippedNotStoredintegerFor a replay: matching recorded calls left out because their input is no longer stored.uniqueInputCountintegerbytesintegercreatedByintegercreatedByNamestringcreatedAtstringpreviewarrayThe first 50 rows.
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/datasets/<datasetId>" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"DELETE /v1/organisations/{org}/decisions/{slug}/datasets/{datasetId}
Delete a Dataset
Soft delete: Dataset runs and Comparisons keep their evidence.
Path
orgRequiredstringslugRequiredstringdatasetIdRequiredstring
Answer (204)
It answers with no body.
curl -X DELETE "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/datasets/<datasetId>" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"Comparisons
GET /v1/organisations/{org}/decisions/{slug}/comparisons
List Comparisons
Path
orgRequiredstringslugRequiredstring
Answer (200)
comparisonsarray
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/comparisons" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"POST /v1/organisations/{org}/decisions/{slug}/comparisons
Start a Comparison
Starts the Comparison, running the rows it needs in the background; maxCalls is optional (without it, every chosen row runs). With X-TypeSafe-Key its rows run on your own TypeSafe key, sealed while they wait and never stored.
Path
orgRequiredstringslugRequiredstring
Headers
X-TypeSafe-KeyOptionalstring
Body
datasetIdRequiredstringaRequiredobjectOne side of a Comparison: exactly one ofversion(a published version by number),draft(the draft as it is now, frozen when started),environment(the release live there when started) orrecorded(production's recorded answers; replay Datasets only).a.versionOptionalintegera.draftOptionalbooleana.environmentOptionalstringa.recordedOptionalbooleanbRequiredobjectOne side of a Comparison: exactly one ofversion(a published version by number),draft(the draft as it is now, frozen when started),environment(the release live there when started) orrecorded(production's recorded answers; replay Datasets only).b.versionOptionalintegerb.draftOptionalbooleanb.environmentOptionalstringb.recordedOptionalbooleansampleOptionalintegerseedOptionalintegerbatchSizeOptionalintegerfreshOptionalbooleanmaxCallsOptionalintegerThe most model calls both sides together may make; rows beyond it are not run. Without it, every chosen row runs.
Answer (202)
comparisonobjectcomparison.idstringcomparison.datasetIdstringcomparison.datasetNamestring or nullcomparison.datasetSourcestring or nullOne ofupload,replaycomparison.statusstringOne ofrunning,completed,cancelledcomparison.aobjectcomparison.bobjectcomparison.maxCallsintegercomparison.progressobjectRows finished across both sides, of the rows both will run.comparison.headlineobject or nullThe headline numbers; null until analysed.comparison.summaryobject or nullThe full analysis; null until analysed, and left out of lists.comparison.projectionobject or nullEach side's cost per call at the Decision's last 30 days of production traffic; null when there was none, before the analysis, and in lists.comparison.costWordingobject or nullThe cost headline in words, as the app shows it:saidcompares the cost per call (such as "48% less per call") andprojectedputs it at production's recent traffic. Null before the analysis and in lists; either line is null when there is nothing to say.comparison.replayobject or nullFor a Dataset replayed from production: the recorded calls it matched and how many could not be replayed, because their input was no longer stored or (once analysed) no longer fits the input a side accepts. Null for uploaded Datasets.comparison.createdByintegercomparison.createdByNamestringcomparison.createdAtstringcomparison.completedAtstring or nullestimateobjectestimate.datasetIdstringestimate.rowsintegerestimate.skippedNotStoredintegerThe Dataset's recorded calls left out of its replay snapshot because their input is no longer stored.estimate.uniqueInputsintegerestimate.sampleinteger or nullestimate.seedintegerestimate.batchSizeintegerestimate.aobjectestimate.bobjectestimate.callsWithoutCapintegerCalls without a cap.estimate.maxCallsinteger or nullestimate.callsintegerCalls within maxCalls (or without a cap when none was given).estimate.rowsCoveredintegerestimate.inputTokensintegerestimate.minutesintegerestimate.allowedbooleanestimate.refusalobject or null
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/comparisons" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"datasetId":"<datasetId>","a":{},"b":{}}'POST /v1/organisations/{org}/decisions/{slug}/comparisons/estimate
Estimate a Comparison
What a Comparison would cost and whether it may start. Calls no model.
Path
orgRequiredstringslugRequiredstring
Headers
X-TypeSafe-KeyOptionalstring
Body
datasetIdRequiredstringaRequiredobjectOne side of a Comparison: exactly one ofversion(a published version by number),draft(the draft as it is now, frozen when started),environment(the release live there when started) orrecorded(production's recorded answers; replay Datasets only).a.versionOptionalintegera.draftOptionalbooleana.environmentOptionalstringa.recordedOptionalbooleanbRequiredobjectOne side of a Comparison: exactly one ofversion(a published version by number),draft(the draft as it is now, frozen when started),environment(the release live there when started) orrecorded(production's recorded answers; replay Datasets only).b.versionOptionalintegerb.draftOptionalbooleanb.environmentOptionalstringb.recordedOptionalbooleansampleOptionalintegerA seeded random sample of this many rows; the same seed draws the same rows.seedOptionalintegerbatchSizeOptionalintegerfreshOptionalbooleanRun both sides even when a Dataset run for the same plan and rows exists (a noise floor).maxCallsOptionalintegerWhen given, the estimate covers only the rows this many calls reach.
Answer (200)
datasetIdstringrowsintegerskippedNotStoredintegerThe Dataset's recorded calls left out of its replay snapshot because their input is no longer stored.uniqueInputsintegersampleinteger or nullseedintegerbatchSizeintegeraobjecta.labelstringa.modestring"recorded": answers read from production; "reuse": an existing Dataset run; "run": new calls.One ofrecorded,reuse,runa.reuseRunIdstring or nulla.callsintegerCalls this side makes for every selected row.bobjectb.labelstringb.modestring"recorded": answers read from production; "reuse": an existing Dataset run; "run": new calls.One ofrecorded,reuse,runb.reuseRunIdstring or nullb.callsintegerCalls this side makes for every selected row.callsWithoutCapintegerCalls without a cap.maxCallsinteger or nullcallsintegerCalls within maxCalls (or without a cap when none was given).rowsCoveredintegerinputTokensintegerminutesintegerallowedbooleanrefusalobject or nullrefusal.codestringrefusal.messagestring
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/comparisons/estimate" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"datasetId":"<datasetId>","a":{},"b":{}}'GET /v1/organisations/{org}/decisions/{slug}/comparisons/{comparisonId}
Get a Comparison
Path
orgRequiredstringslugRequiredstringcomparisonIdRequiredstring
Answer (200)
idstringdatasetIdstringdatasetNamestring or nulldatasetSourcestring or nullOne ofupload,replaystatusstringOne ofrunning,completed,cancelledaobjecta.labelstringa.reusedbooleanAn existing Dataset run answered this side; it made no new calls for this Comparison.a.runobjectOne target executed (or read) over a Dataset: the evidence.bobjectb.labelstringb.reusedbooleanAn existing Dataset run answered this side; it made no new calls for this Comparison.b.runobjectOne target executed (or read) over a Dataset: the evidence.maxCallsintegerprogressobjectRows finished across both sides, of the rows both will run.progress.doneintegerprogress.totalintegerheadlineobject or nullThe headline numbers; null until analysed.headline.rowsintegerheadline.comparedintegerheadline.differingRowsintegerheadline.questionsComparedstringSee ComparisonSummary; absent on Comparisons analysed before it existed and not read since.One ofsame,changed,differentsummaryobject or nullThe full analysis; null until analysed, and left out of lists.summary.rowsintegersummary.comparedintegerRows both sides answered: the distributions and differences count these.summary.notAcceptedobjectsummary.errorsobjectsummary.skippedobjectsummary.differingRowsintegersummary.perQuestionobjectsummary.onlyInobjectQuestions only one side asks: a contract change, not compared.summary.retypedarray of stringQuestions both sides ask by name whose answers are of a different kind: not compared.summary.questionsComparedstringWhether the answers could be compared:samequestions,changed(some compared, some only on one side or retyped) ordifferent(nothing in common: answers not compared, anddifferingRowsis 0).One ofsame,changed,differentsummary.differingarray of { "row": integer, "questions": array of string }Differing rows by Dataset row, with the questions that differ; at most 2,000.summary.differingTruncatedbooleansummary.sidesobjectsummary.differenceobjectCost, tokens and latency of each side and the change from A to B, over the rows both sides answered only, so a call limit or an error on one side doesn't skew them.projectionobject or nullEach side's cost per call at the Decision's last 30 days of production traffic; null when there was none, before the analysis, and in lists.projection.environmentsarray of stringThe environments counted.projection.daysintegerprojection.callsintegerCalls those environments answered in the lastdaysdays (shadow calls excluded).projection.anumber or nullSide A's cost per call timescalls; null when A has no recorded cost.projection.bnumber or nullcostWordingobject or nullThe cost headline in words, as the app shows it:saidcompares the cost per call (such as "48% less per call") andprojectedputs it at production's recent traffic. Null before the analysis and in lists; either line is null when there is nothing to say.costWording.saidstring or nullcostWording.projectedstring or nullreplayobject or nullFor a Dataset replayed from production: the recorded calls it matched and how many could not be replayed, because their input was no longer stored or (once analysed) no longer fits the input a side accepts. Null for uploaded Datasets.replay.recordedCallsintegerRecorded calls the replay matched, stored or not.replay.notStoredintegerOf those, calls whose input was no longer stored, so they were left out of the Dataset.replay.notAcceptedintegerRows the Comparison ran whose input a side did not accept (the larger side's count).replay.messagestring or nullThe two above in one sentence; null when every call was replayed.createdByintegercreatedByNamestringcreatedAtstringcompletedAtstring or null
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/comparisons/<comparisonId>" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"POST /v1/organisations/{org}/decisions/{slug}/comparisons/{comparisonId}/cancel
Cancel a Comparison
Path
orgRequiredstringslugRequiredstringcomparisonIdRequiredstring
Answer (200)
idstringdatasetIdstringdatasetNamestring or nulldatasetSourcestring or nullOne ofupload,replaystatusstringOne ofrunning,completed,cancelledaobjecta.labelstringa.reusedbooleanAn existing Dataset run answered this side; it made no new calls for this Comparison.a.runobjectOne target executed (or read) over a Dataset: the evidence.bobjectb.labelstringb.reusedbooleanAn existing Dataset run answered this side; it made no new calls for this Comparison.b.runobjectOne target executed (or read) over a Dataset: the evidence.maxCallsintegerprogressobjectRows finished across both sides, of the rows both will run.progress.doneintegerprogress.totalintegerheadlineobject or nullThe headline numbers; null until analysed.headline.rowsintegerheadline.comparedintegerheadline.differingRowsintegerheadline.questionsComparedstringSee ComparisonSummary; absent on Comparisons analysed before it existed and not read since.One ofsame,changed,differentsummaryobject or nullThe full analysis; null until analysed, and left out of lists.summary.rowsintegersummary.comparedintegerRows both sides answered: the distributions and differences count these.summary.notAcceptedobjectsummary.errorsobjectsummary.skippedobjectsummary.differingRowsintegersummary.perQuestionobjectsummary.onlyInobjectQuestions only one side asks: a contract change, not compared.summary.retypedarray of stringQuestions both sides ask by name whose answers are of a different kind: not compared.summary.questionsComparedstringWhether the answers could be compared:samequestions,changed(some compared, some only on one side or retyped) ordifferent(nothing in common: answers not compared, anddifferingRowsis 0).One ofsame,changed,differentsummary.differingarray of { "row": integer, "questions": array of string }Differing rows by Dataset row, with the questions that differ; at most 2,000.summary.differingTruncatedbooleansummary.sidesobjectsummary.differenceobjectCost, tokens and latency of each side and the change from A to B, over the rows both sides answered only, so a call limit or an error on one side doesn't skew them.projectionobject or nullEach side's cost per call at the Decision's last 30 days of production traffic; null when there was none, before the analysis, and in lists.projection.environmentsarray of stringThe environments counted.projection.daysintegerprojection.callsintegerCalls those environments answered in the lastdaysdays (shadow calls excluded).projection.anumber or nullSide A's cost per call timescalls; null when A has no recorded cost.projection.bnumber or nullcostWordingobject or nullThe cost headline in words, as the app shows it:saidcompares the cost per call (such as "48% less per call") andprojectedputs it at production's recent traffic. Null before the analysis and in lists; either line is null when there is nothing to say.costWording.saidstring or nullcostWording.projectedstring or nullreplayobject or nullFor a Dataset replayed from production: the recorded calls it matched and how many could not be replayed, because their input was no longer stored or (once analysed) no longer fits the input a side accepts. Null for uploaded Datasets.replay.recordedCallsintegerRecorded calls the replay matched, stored or not.replay.notStoredintegerOf those, calls whose input was no longer stored, so they were left out of the Dataset.replay.notAcceptedintegerRows the Comparison ran whose input a side did not accept (the larger side's count).replay.messagestring or nullThe two above in one sentence; null when every call was replayed.createdByintegercreatedByNamestringcreatedAtstringcompletedAtstring or null
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/comparisons/<comparisonId>/cancel" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"GET /v1/organisations/{org}/decisions/{slug}/comparisons/{comparisonId}/rows
List a Comparison's rows
Path
orgRequiredstringslugRequiredstringcomparisonIdRequiredstring
Query
filterOptionalstringOne ofdiffers,all,errors,not_acceptedquestionOptionalstringfromOptionalstringtoOptionalstringcursorOptionalintegerlimitOptionalinteger
Answer (200)
rowsarraynextCursorinteger or nullPass ascursorfor the next page; null when there are no more rows.
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/comparisons/<comparisonId>/rows" \
-H "Authorization: Bearer $TYPEFUSE_TOKEN"