Skip to content

Reference

API: Runs and audit

Recorded calls, the Change history and exports of both.

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

Runs

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

List runs

target narrows to draft runs or runs of published versions; environment narrows further.

Path

  • orgRequiredstring
  • slugRequiredstring

Query

  • targetOptionalstring
    One of draft, version, all
  • environmentOptionalstring
  • referenceOptionalstring
  • limitOptionalinteger
  • offsetOptionalinteger

Answer (200)

  • runsarray
    One page, newest first. ?environment= takes "all", "production", "draft" (the Sandbox, where draft runs are filed) or a comma-separated list.
  • totalinteger
    Every run the filter matches, across all pages.
  • byEnvironmentarray of { "environment": string, "runs": integer, "failed": integer }
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/runs" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

GET /v1/organisations/{org}/decisions/{slug}/runs/{runId}

Get a run

Path

  • orgRequiredstring
  • slugRequiredstring
  • runIdRequiredstring

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 "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/runs/<runId>" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

Audit and exports

GET /v1/organisations/{org}/audit

Read the audit trail

The audit trail, newest first. Filters: type, subjectType, subjectId, actor (user id), decision (slug), before (event id), limit.

Path

  • orgRequiredstring

Query

  • typeOptionalstring
  • subjectTypeOptionalstring
  • subjectIdOptionalstring
  • actorOptionalinteger
  • decisionOptionalstring
  • beforeOptionalstring
  • limitOptionalinteger

Answer (200)

  • eventsarray
  • nextBeforestring or null
    Pass as before for the next page; null at the end.
  • typesarray of string
    Event types seen in this organisation.
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/audit" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

GET /v1/organisations/{org}/exports

List exports

The organisation's exports, newest first; with decision (a slug), only those narrowed to that Decision. Owners, admins and viewers.

Path

  • orgRequiredstring

Query

  • decisionOptionalstring

Answer (200)

  • exportsarray
    Newest first, the latest fifty.
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/exports" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/exports

Start an export

Exports from Audit. Owners, admins and viewers. A small export is built while the request waits (201, status ready, with a downloadUrl); a larger one is queued (202) and the person is notified when it is ready. 413 EXPORT_TOO_LARGE past 50,000 rows (5,000 with inputs and outputs). Each is recorded as an ExportCreated audit event.

Path

  • orgRequiredstring

Body

  • kindRequiredstring
    One of calls, changes, evidence
  • formatRequiredstring
    csv or json for calls and changes; zip for an evidence pack.One of csv, json, zip
  • fromOptionalstring or integer
    ISO 8601 or unix milliseconds, inclusive.
  • toOptionalstring or integer
    ISO 8601 or unix milliseconds, exclusive.
  • decisionOptionalstring
    A Decision's slug; required for an evidence pack.
  • environmentsOptionalarray of string
    Environment slugs; "sandbox" (or "draft") for Sandbox runs.
  • includePayloadsOptionalboolean
    Calls and evidence packs: include each call's input and the state sent to the model, where still stored.

Answer (201)

  • idstring
  • kindstring
    One of calls, changes, evidence
  • formatstring
    One of csv, json, zip
  • statusstring
    queued and running while it is built; ready to download; failed; expired once its file is deleted.One of queued, running, ready, failed, expired
  • whatstring
    What it holds, in words.
  • filtersobject
    What an export was narrowed to.
  • filters.fromstring or null
    ISO 8601, inclusive; null for no start.
  • filters.tostring or null
    ISO 8601, exclusive; null for no end.
  • filters.decisionstring or null
    A Decision's slug.
  • filters.environmentsarray of string or null
    Environment slugs ("sandbox" for the Sandbox); null for every environment.
  • filters.includePayloadsboolean
    Calls only: each call's input and the state sent to the model, where still stored.
  • rowsinteger or null
    Calls or changes in the file; for an evidence pack, the calls in its period.
  • sizeBytesinteger or null
  • filenamestring or null
  • errorstring or null
  • backgroundboolean
    Built after the response; the person is notified when it is ready.
  • requestedByobject
  • requestedBy.idinteger
  • requestedBy.namestring
  • createdAtstring
  • completedAtstring or null
  • expiresAtstring or null
    When the file is deleted: seven days after it is ready.
  • downloadUrlstring or null
    A signed link that downloads the file without signing in, valid until downloadExpiresAt (at most an hour).
  • downloadExpiresAtstring or null
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/exports" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"calls","format":"csv"}'

GET /v1/organisations/{org}/exports/{id}

Get an export

Path

  • orgRequiredstring
  • idRequiredstring

Answer (200)

  • idstring
  • kindstring
    One of calls, changes, evidence
  • formatstring
    One of csv, json, zip
  • statusstring
    queued and running while it is built; ready to download; failed; expired once its file is deleted.One of queued, running, ready, failed, expired
  • whatstring
    What it holds, in words.
  • filtersobject
    What an export was narrowed to.
  • filters.fromstring or null
    ISO 8601, inclusive; null for no start.
  • filters.tostring or null
    ISO 8601, exclusive; null for no end.
  • filters.decisionstring or null
    A Decision's slug.
  • filters.environmentsarray of string or null
    Environment slugs ("sandbox" for the Sandbox); null for every environment.
  • filters.includePayloadsboolean
    Calls only: each call's input and the state sent to the model, where still stored.
  • rowsinteger or null
    Calls or changes in the file; for an evidence pack, the calls in its period.
  • sizeBytesinteger or null
  • filenamestring or null
  • errorstring or null
  • backgroundboolean
    Built after the response; the person is notified when it is ready.
  • requestedByobject
  • requestedBy.idinteger
  • requestedBy.namestring
  • createdAtstring
  • completedAtstring or null
  • expiresAtstring or null
    When the file is deleted: seven days after it is ready.
  • downloadUrlstring or null
    A signed link that downloads the file without signing in, valid until downloadExpiresAt (at most an hour).
  • downloadExpiresAtstring or null
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/exports/<id>" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

GET /v1/organisations/{org}/exports/{id}/download

Download an export

The file itself (CSV, JSON or zip). 409 EXPORT_NOT_READY while it is built; 410 EXPORT_EXPIRED after seven days.

Path

  • orgRequiredstring
  • idRequiredstring

Answer (200)

It answers with no body.

Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/exports/<id>/download" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

GET /v1/organisations/{org}/exports/{id}/evidence

Download an evidence pack

An evidence pack as the app shows it: the facts its PDF is typeset from, and its files. 404 for other exports.

Path

  • orgRequiredstring
  • idRequiredstring

Answer (200)

  • exportobject
    A file exported from Audit: the Decision log ("calls") or the Change history ("changes") as CSV or JSON, or a Decision's evidence pack ("evidence", a zip with a PDF summary).
  • export.idstring
  • export.kindstring
    One of calls, changes, evidence
  • export.formatstring
    One of csv, json, zip
  • export.statusstring
    queued and running while it is built; ready to download; failed; expired once its file is deleted.One of queued, running, ready, failed, expired
  • export.whatstring
    What it holds, in words.
  • export.filtersobject
    What an export was narrowed to.
  • export.rowsinteger or null
    Calls or changes in the file; for an evidence pack, the calls in its period.
  • export.sizeBytesinteger or null
  • export.filenamestring or null
  • export.errorstring or null
  • export.backgroundboolean
    Built after the response; the person is notified when it is ready.
  • export.requestedByobject
  • export.createdAtstring
  • export.completedAtstring or null
  • export.expiresAtstring or null
    When the file is deleted: seven days after it is ready.
  • export.downloadUrlstring or null
    A signed link that downloads the file without signing in, valid until downloadExpiresAt (at most an hour).
  • export.downloadExpiresAtstring or null
  • summaryobject or null
    Null until the pack is ready, after it expires, or for a pack made before packs could be viewed.
  • summary.organisationobject
  • summary.decisionobject
    An evidence pack's Decision.
  • summary.periodobject
  • summary.generatedAtstring
  • summary.generatedBystring
  • summary.definitionobject
    What the Decision decides, as published in the newest release the pack covers.
  • summary.livearray
  • summary.evaluationsarray
  • summary.approvalsarray
  • summary.callsobject
  • summary.proofobject
  • summary.filesarray
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/exports/<id>/evidence" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"