Tangibool for developers
On this page

API reference

Programs and AI assistants act for a person, within their scopes and the person’s role. Verdicts are holds, violated, or unknown; witnesses are replayed; results are bound to their revision, logic digest, and engine and semantics versions. Confirming meaning and expected results, approving merge requests, and creating approved baselines stay with a person in the app. Within v1, changes are additive only. Every error has a stable code; x-error-codes on an error response lists the codes the route answers under that status.

Version 1.0.0, generated from the OpenAPI 3.1 specification this server publishes. Every path below is under https://api.tangibool.com. The guide explains how to use them.

Authentication

Errors

Every error has the same body. The code is stable and part of the contract; the guide lists the codes.

  • error object required
    • code string required
    • message string required
    • details any JSON value

Meta

GET /v1/openapi.json

This specification.

Scope: None: no token is needed.

200 response

Success.

  • openapi "3.1.0" required

Errors

This route has no error of its own.

POST /v1/secret-scanning/reports

Report leaked tokens (secret-scanning partners). Each live token reported is revoked and its user is told.

Scope: None: no token is needed.

Request body

array of object

  • token string required
  • type string
  • url string
  • source string
200 response

Success.

array of object

  • token_raw string required
  • token_type string required
  • label one of true_positive, false_positive required

Errors

400
invalid-json
413
payload-too-large
415
unsupported-media-type
422
invalid-request
429
rate-limited

Account

GET /v1/me

The program’s user and the program itself.

Scope: Any valid token.

200 response

Success.

  • user object required
    • id string required
    • displayName string required
    • email string required
    • plan one of free, basic, pro, team required
  • client object or null required
    • kind one of token, app, assistant required
    • id string required
    • name string required
    • scopes array of one of models:read, models:write, analyses, exports, discussion, webhooks required

Errors

401
unauthenticated
429
rate-limited

Models

GET /v1/teams

Teams the user belongs to, oldest first by creation (an order a rename cannot change).

Scope: models:read

Parameters

NameInTypeRequiredDescription
limitqueryinteger 1 to 500NoRows on a page, at most 500; every team without it.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque.
200 response

Success.

  • teams array of object required
    • id string required
    • name string required
    • role one of viewer, commenter, editor, admin, owner required
  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope
422
invalid-request
429
rate-limited

GET /v1/teams/{teamId}

One team.

Scope: models:read

Parameters

NameInTypeRequiredDescription
teamIdpathstringYes
200 response

Success.

  • team object required
    • id string required
    • name string required
    • role one of viewer, commenter, editor, admin, owner required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

GET /v1/models

Models the user can read, newest first by creation (an order an update cannot change).

Scope: models:read

Parameters

NameInTypeRequiredDescription
limitqueryinteger 1 to 500NoRows on a page, at most 500; every model without it.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque.
200 response

Success.

  • models array of object required
    • id string required
    • title string required
    • role one of viewer, commenter, editor, admin, owner required
    • teamId string or null required
    • defaultBranch string required
    • updatedAt string required

      ISO 8601, UTC.

  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope
422
invalid-request
429
rate-limited

POST /v1/models

Create a model from plain inputs: categories, scales, and quantities; inputs with threshold, category, or scale definitions; formulas as text; source text; glossary; assumptions; and tests.

Scope: models:write

Parameters

NameInTypeRequiredDescription
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • mode one of decision, argument
  • categories array of object at most 64 items

    Categories with their values and lists (FR-26).

    • name string required 1 to 200 characters
    • values array of one of the forms below required 1 to 2000 items

      Its values in order: names (identifiers), or names with display labels.

        • name string required 1 to 200 characters
        • label string at most 200 characters
    • lists array of object at most 500 items

      Named lists of its values, which membership tests and formulas use (plan IN Paid).

      • name string required 1 to 200 characters
      • values array of string required at most 2000 items; 1 to 200 characters

        Values of the category, by name.

  • scales array of object at most 64 items

    Ordered scales with their levels (FR-27).

    • name string required 1 to 200 characters
    • levels array of string required 1 to 100 items; 1 to 200 characters

      Level labels, from the lowest to the highest.

    • outside array of string at most 8 items; 1 to 200 characters

      Values on no level, such as "Not rated": they meet no comparison.

  • quantities array of object at most 64 items

    What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

    • name string required 1 to 200 characters
    • domain one of integer, decimal, category, set, scale required

      A number, one value of a category, a set of its values, or a level of a scale.

    • category string 1 to 200 characters

      For category and set: the category, by name.

    • scale string 1 to 200 characters

      For scale: the scale, by name.

  • inputs array of object at most 64 items
    • name string required 1 to 200 characters
    • threshold object

      A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

      • quantity string required 1 to 200 characters
      • comparator one of <, <=, >, >= required
      • bound string required at most 40 characters

        A number; on a scale quantity, the label of a level.

      • domain one of integer, decimal

        When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

    • membership object

      A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

      • quantity string required 1 to 200 characters

        A category or set-valued quantity, by name.

      • test one of in, any, all, none

        in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

      • values array of string 1 to 2000 items; 1 to 200 characters

        Values of the category, by name. Send these or list.

      • list string 1 to 200 characters

        A list of the category, by name. Send this or values.

    • comparison object

      Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

      • left string required 1 to 200 characters
      • comparator one of <, <=, >, >= required
      • right string required 1 to 200 characters
    • rated object

      The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

      • quantity string required 1 to 200 characters
  • formulas array of object at most 64 items

    Outputs in decision mode; premises in argument mode.

    • name string 1 to 200 characters
    • text string required at most 20000 characters
  • conclusion string at most 20000 characters
  • assumptions array of object at most 64 items
    • text string required at most 20000 characters
    • name string 1 to 200 characters
    • description string at most 2000 characters
  • title string required 1 to 200 characters
  • teamId string or null matches ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  • contentLanguage one of en, fr, de, es
  • sourceText string at most 4000 characters
  • glossary array of object at most 200 items
    • target string required 1 to 200 characters
    • meaning string required at most 2000 characters
  • tests array of object at most 1000 items
    • name string required 1 to 200 characters
    • kind one of scenario, property
    • assignments map of string to boolean

      Input values by input ID or name.

    • quantities map of string to string or array of string

      Numbers, levels, values, or sets by quantity ID or name.

    • expected map of string to boolean

      Expected values by formula ID or name.

    • expectedLabels map of string to string

      Expected outcome label (ID or name) by outcome set (ID or name).

    • property one of the forms below
        • kind one of satisfiable, tautology, falsifiable, contradiction required
        • formulaId string required 1 to 300 characters
      • kind: equivalent

        • kind "equivalent" required
        • formulaId string required 1 to 300 characters
        • otherFormulaId string 1 to 300 characters
        • otherText string at most 20000 characters
        • kind one of validity, premises-consistent, consistency required
        • kind one of relevant, irrelevant required
        • formulaId string required 1 to 300 characters
        • varId string required 1 to 300 characters
      • kind: at-least-as-strict

        • kind "at-least-as-strict" required
        • formulaId string required 1 to 300 characters
        • otherFormulaId string required 1 to 300 characters
      • kind: monotone

        • kind "monotone" required
        • formulaId string 1 to 300 characters
        • setId string 1 to 300 characters
        • varId string 1 to 300 characters
        • quantityId string 1 to 300 characters
        • direction one of never-true-to-false, never-false-to-true, never-earlier, never-later required
    • expectHolds boolean
    • notes string at most 10000 characters
    • tags array of string at most 50 items; at most 100 characters
    • source one of user-authored, user-confirmed, ai-proposed, copied-from-formula, counterexample, feedback, imported

      Expectation source; user-confirmed is a person’s act and is refused (422 trusted-record).

  • draft boolean default false
  • message string at most 2000 characters
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

Any other field is refused.

201 response

Success.

  • model object required
    • id string required
    • title string required
    • teamId string or null required
    • ownerId string or null required
    • defaultBranch string required
    • labels array of string required
    • createdAt string required

      ISO 8601, UTC.

    • updatedAt string required

      ISO 8601, UTC.

  • role one of viewer, commenter, editor, admin, owner required
  • permissions array of string required
  • refs object required
    • branches map of string to object required
      • name string required
      • head string or null required matches ^[0-9a-f]{64}$
      • protected boolean required
    • tags map of string to object required
      • name string required
      • target string required matches ^[0-9a-f]{64}$
      • kind one of ordinary, approved-baseline required
  • created array of object required
    • kind one of variable, quantity, formula, assumption, test, category, list, scale required open: more values may be added within v1
    • name string required
    • id string required
  • diagnostics array of object required
    • formulaId string required
    • name string required
    • status string required
    • diagnostics array required
  • validation object required
    • valid boolean required
    • issues array of object required
      • severity string required
      • message string required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden
404
not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, compute-limit, invalid-change, invalid-logic, invalid-model, trusted-record
429
rate-limited
503
compute-busy

GET /v1/models/{modelId}

A model; with view=outline, the outline of a revision (rev, the default branch by default).

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
viewqueryone of outlineNo
revquerystringNo
200 response

Success.

one of the forms below

    • model object required
      • id string required
      • title string required
      • teamId string or null required
      • ownerId string or null required
      • defaultBranch string required
      • labels array of string required
      • createdAt string required

        ISO 8601, UTC.

      • updatedAt string required

        ISO 8601, UTC.

    • role one of viewer, commenter, editor, admin, owner required
    • permissions array of string required
    • refs object required
      • branches map of string to object required
        • name string required
        • head string or null required matches ^[0-9a-f]{64}$
        • protected boolean required
      • tags map of string to object required
        • name string required
        • target string required matches ^[0-9a-f]{64}$
        • kind one of ordinary, approved-baseline required
    • modelId string required
    • commit object required
      • id string required matches ^[0-9a-f]{64}$
      • parents array of string required matches ^[0-9a-f]{64}$
      • manifest string required matches ^[0-9a-f]{64}$
      • author object required
        • id string
        • name string required
      • committer object required
        • id string
        • name string required
      • authoredAt string required
      • receivedAt string required

        ISO 8601, UTC.

      • receivedBy string or null required
      • authorVerified boolean required
      • imported boolean required
      • message string required
      • kind string required
      • state string required
      • via object or null required

        The token, app, or assistant a program acted through; null for changes made in the app.

        • kind one of token, app, assistant required
        • id string required
        • name string required
    • outline object required
      • schema "tangibool.outline/1" required
      • mode one of decision, argument required
      • inputs array of object required
        • id string required
        • name string required
        • definition string or null required
      • formulas array of object required
        • id string required
        • name string required
        • role one of output, premise, conclusion required
        • text string required
      • tests object required
        • total number required
        • confirmed number required
      • source object required
        • interpretation one of not-needed, unconfirmed, confirmed, invalidated required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found, revision-not-found
422
invalid-request, empty-branch, missing-objects, compute-limit
429
rate-limited
503
compute-busy

History

GET /v1/models/{modelId}/refs

Branches and tags.

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
200 response

Success.

  • branches map of string to object required
    • name string required
    • head string or null required matches ^[0-9a-f]{64}$
    • protected boolean required
  • tags map of string to object required
    • name string required
    • target string required matches ^[0-9a-f]{64}$
    • kind one of ordinary, approved-baseline required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

GET /v1/models/{modelId}/commits

History of a branch, newest first (children before parents).

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
branchquerystringNoThe branch; the default branch when absent.
commitquerystringNoStart from this commit instead of a branch head.
offsetqueryinteger 0 to 9007199254740991NoCommits to skip; not with cursor.
limitqueryinteger 1 to 500NoCommits on a page, at most 500; 100 by default.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque. Later pages continue the history the first page started from, however the branch moves meanwhile; send the same filters.
searchquerystringNo
authorquerystringNo
changedquerystringNoComma-separated changed domains.
200 response

Success.

  • commits array of object required
    • id string required matches ^[0-9a-f]{64}$
    • parents array of string required matches ^[0-9a-f]{64}$
    • manifest string required matches ^[0-9a-f]{64}$
    • author object required
      • id string
      • name string required
    • committer object required
      • id string
      • name string required
    • authoredAt string required
    • receivedAt string required

      ISO 8601, UTC.

    • receivedBy string or null required
    • authorVerified boolean required
    • imported boolean required
    • message string required
    • kind string required
    • state string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
  • total number required
  • hasMore boolean required
  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope
404
not-found, branch-not-found, commit-not-found
422
invalid-request, invalid-filter
429
rate-limited

GET /v1/models/{modelId}/commits/{commitId}

One commit.

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
commitIdpathstringYes
200 response

Success.

  • commit object required
    • id string required matches ^[0-9a-f]{64}$
    • parents array of string required matches ^[0-9a-f]{64}$
    • manifest string required matches ^[0-9a-f]{64}$
    • author object required
      • id string
      • name string required
    • committer object required
      • id string
      • name string required
    • authoredAt string required
    • receivedAt string required

      ISO 8601, UTC.

    • receivedBy string or null required
    • authorVerified boolean required
    • imported boolean required
    • message string required
    • kind string required
    • state string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found, commit-not-found
429
rate-limited

GET /v1/models/{modelId}/snapshots/{commitId}

The native snapshot of a commit.

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
commitIdpathstringYes
200 response

Success.

  • commitId string required matches ^[0-9a-f]{64}$
  • commit object required
    • id string required matches ^[0-9a-f]{64}$
    • parents array of string required matches ^[0-9a-f]{64}$
    • manifest string required matches ^[0-9a-f]{64}$
    • author object required
      • id string
      • name string required
    • committer object required
      • id string
      • name string required
    • authoredAt string required
    • receivedAt string required

      ISO 8601, UTC.

    • receivedBy string or null required
    • authorVerified boolean required
    • imported boolean required
    • message string required
    • kind string required
    • state string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
  • snapshot object required
    • artifacts object required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found, commit-not-found
422
missing-objects
429
rate-limited

POST /v1/models/{modelId}/comparisons

Text, structure, and behaviour differences between two revisions.

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Request body
  • from string required
  • to string required
  • behaviour boolean
200 response

Success.

  • from object required
    • id string required matches ^[0-9a-f]{64}$
    • parents array of string required matches ^[0-9a-f]{64}$
    • manifest string required matches ^[0-9a-f]{64}$
    • author object required
      • id string
      • name string required
    • committer object required
      • id string
      • name string required
    • authoredAt string required
    • receivedAt string required

      ISO 8601, UTC.

    • receivedBy string or null required
    • authorVerified boolean required
    • imported boolean required
    • message string required
    • kind string required
    • state string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
  • to object required
    • id string required matches ^[0-9a-f]{64}$
    • parents array of string required matches ^[0-9a-f]{64}$
    • manifest string required matches ^[0-9a-f]{64}$
    • author object required
      • id string
      • name string required
    • committer object required
      • id string
      • name string required
    • authoredAt string required
    • receivedAt string required

      ISO 8601, UTC.

    • receivedBy string or null required
    • authorVerified boolean required
    • imported boolean required
    • message string required
    • kind string required
    • state string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
  • diff any JSON value required
  • behaviour any JSON value or null required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope
404
not-found, revision-not-found
413
payload-too-large
415
unsupported-media-type
422
invalid-request, empty-branch, missing-objects, compute-limit
429
rate-limited
503
compute-busy

Edits

POST /v1/models/{modelId}/changes

Apply an ordered change set to a branch against its expected head; dryRun stores nothing.

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • branch string required 1 to 100 characters
  • expectedHead string or null required matches ^[0-9a-f]{64}$
  • message string at most 2000 characters; default ""
  • edits array of one of the forms below required 1 to 500 items
    • op: setFormulaText

      • op "setFormulaText" required
      • formula one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
      • text string required at most 20000 characters
    • op: addFormula

      • op "addFormula" required
      • name string 1 to 200 characters
      • text string required at most 20000 characters
    • op: renameFormula

      • op "renameFormula" required
      • formula one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
      • name string required 1 to 200 characters
    • op: removeFormula

      • op "removeFormula" required
      • formula one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
    • op: addVariable

      • op "addVariable" required
      • name string required 1 to 200 characters
    • op: renameVariable

      • op "renameVariable" required
      • variable one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
      • name string required 1 to 200 characters
    • op: removeVariable

      • op "removeVariable" required
      • variable one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
      • replaceWith boolean or one of the forms below
    • op: setThreshold

      • op "setThreshold" required
      • variable one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
      • quantity string 1 to 200 characters
      • domain one of integer, decimal
      • comparator one of <, <=, >, >=
      • bound string at most 40 characters
      • clear boolean
    • op: setSourceText

      • op "setSourceText" required
      • text string required at most 4000 characters
      • language one of en, fr, de, es
    • op: setGlossaryMeaning

      • op "setGlossaryMeaning" required
      • target one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
      • meaning string required at most 2000 characters
      • language one of en, fr, de, es
    • op: addAssumption

      • op "addAssumption" required
      • text string required at most 20000 characters
      • name string 1 to 200 characters
      • description string at most 2000 characters
    • op: removeAssumption

      • op "removeAssumption" required
      • assumption one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
    • op: addTest

      • op "addTest" required
      • test object required
        • name string required 1 to 200 characters
        • kind one of scenario, property
        • assignments map of string to boolean

          Input values by input ID or name.

        • quantities map of string to string or array of string

          Numbers, levels, values, or sets by quantity ID or name.

        • expected map of string to boolean

          Expected values by formula ID or name.

        • expectedLabels map of string to string

          Expected outcome label (ID or name) by outcome set (ID or name).

        • property one of the forms below
            • kind one of satisfiable, tautology, falsifiable, contradiction required
            • formulaId string required 1 to 300 characters
          • kind: equivalent

            • kind "equivalent" required
            • formulaId string required 1 to 300 characters
            • otherFormulaId string 1 to 300 characters
            • otherText string at most 20000 characters
            • kind one of validity, premises-consistent, consistency required
            • kind one of relevant, irrelevant required
            • formulaId string required 1 to 300 characters
            • varId string required 1 to 300 characters
          • kind: at-least-as-strict

            • kind "at-least-as-strict" required
            • formulaId string required 1 to 300 characters
            • otherFormulaId string required 1 to 300 characters
          • kind: monotone

            • kind "monotone" required
            • formulaId string 1 to 300 characters
            • setId string 1 to 300 characters
            • varId string 1 to 300 characters
            • quantityId string 1 to 300 characters
            • direction one of never-true-to-false, never-false-to-true, never-earlier, never-later required
        • expectHolds boolean
        • notes string at most 10000 characters
        • tags array of string at most 50 items; at most 100 characters
        • source one of user-authored, user-confirmed, ai-proposed, copied-from-formula, counterexample, feedback, imported

          Expectation source; user-confirmed is a person’s act and is refused (422 trusted-record).

    • op: updateTest

      • op "updateTest" required
      • test one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
      • changes object required
        • name string 1 to 200 characters
        • kind one of scenario, property
        • assignments map of string to boolean

          Input values by input ID or name.

        • quantities map of string to string or array of string

          Numbers, levels, values, or sets by quantity ID or name.

        • expected map of string to boolean

          Expected values by formula ID or name.

        • expectedLabels map of string to string

          Expected outcome label (ID or name) by outcome set (ID or name).

        • property one of the forms below
            • kind one of satisfiable, tautology, falsifiable, contradiction required
            • formulaId string required 1 to 300 characters
          • kind: equivalent

            • kind "equivalent" required
            • formulaId string required 1 to 300 characters
            • otherFormulaId string 1 to 300 characters
            • otherText string at most 20000 characters
            • kind one of validity, premises-consistent, consistency required
            • kind one of relevant, irrelevant required
            • formulaId string required 1 to 300 characters
            • varId string required 1 to 300 characters
          • kind: at-least-as-strict

            • kind "at-least-as-strict" required
            • formulaId string required 1 to 300 characters
            • otherFormulaId string required 1 to 300 characters
          • kind: monotone

            • kind "monotone" required
            • formulaId string 1 to 300 characters
            • setId string 1 to 300 characters
            • varId string 1 to 300 characters
            • quantityId string 1 to 300 characters
            • direction one of never-true-to-false, never-false-to-true, never-earlier, never-later required
        • expectHolds boolean
        • notes string at most 10000 characters
        • tags array of string at most 50 items; at most 100 characters
        • source one of user-authored, user-confirmed, ai-proposed, copied-from-formula, counterexample, feedback, imported

          Expectation source; user-confirmed is a person’s act and is refused (422 trusted-record).

    • op: removeTest

      • op "removeTest" required
      • test one of the forms below required

        An object by its stable ID ({ "id" }) or by its name ({ "name" }).

          • id string required 1 to 300 characters
          • name string required 1 to 200 characters
    • op: replaceLogic

      • op "replaceLogic" required
      • logic object required

        A whole tangibool.logic/1 model.

        • schema "tangibool.logic/1" required
  • dryRun boolean default false
  • draft boolean default false
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

Any other field is refused.

200 response

Success.

  • dryRun true required
  • created array of object required
    • kind one of variable, quantity, formula, assumption, test, category, list, scale required open: more values may be added within v1
    • name string required
    • id string required
  • diagnostics array of object required
    • formulaId string required
    • name string required
    • status string required
    • diagnostics array required
  • validation object required
    • valid boolean required
    • issues array of object required
      • severity string required
      • message string required
  • outline object required
    • schema "tangibool.outline/1" required
    • mode one of decision, argument required
    • inputs array of object required
      • id string required
      • name string required
      • definition string or null required
    • formulas array of object required
      • id string required
      • name string required
      • role one of output, premise, conclusion required
      • text string required
    • tests object required
      • total number required
      • confirmed number required
    • source object required
      • interpretation one of not-needed, unconfirmed, confirmed, invalidated required
  • diff any JSON value or null required
  • behaviour any JSON value or null required
201 response

Success.

  • head string required matches ^[0-9a-f]{64}$
  • previousHead string or null required matches ^[0-9a-f]{64}$
  • commit object required
    • id string required matches ^[0-9a-f]{64}$
    • parents array of string required matches ^[0-9a-f]{64}$
    • manifest string required matches ^[0-9a-f]{64}$
    • author object required
      • id string
      • name string required
    • committer object required
      • id string
      • name string required
    • authoredAt string required
    • receivedAt string required

      ISO 8601, UTC.

    • receivedBy string or null required
    • authorVerified boolean required
    • imported boolean required
    • message string required
    • kind string required
    • state string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
  • created array of object
    • kind one of variable, quantity, formula, assumption, test, category, list, scale required open: more values may be added within v1
    • name string required
    • id string required
  • diagnostics array of object required
    • formulaId string required
    • name string required
    • status string required
    • diagnostics array required
  • validation object required
    • valid boolean required
    • issues array of object required
      • severity string required
      • message string required
  • dryRun false required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden, branch-protected, proposal-branches-only
404
not-found, branch-not-found
409
request-in-progress, head-mismatch
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, invalid-change, invalid-logic, invalid-model, trusted-record, checks-failed, missing-objects, compute-limit
429
rate-limited
503
compute-busy

PUT /v1/models/{modelId}/branches/{name}/snapshot

Write a whole native snapshot to a branch; the server builds the revision.

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
namepathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • expectedHead string or null required matches ^[0-9a-f]{64}$
  • message string at most 2000 characters; default ""
  • snapshot object required
    • artifacts map of string to object required
      • id string required at most 300 characters
      • kind string required at most 40 characters
      • content any JSON value required
  • draft boolean default false
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

Any other field is refused.

201 response

Success.

  • head string required matches ^[0-9a-f]{64}$
  • previousHead string or null required matches ^[0-9a-f]{64}$
  • commit object required
    • id string required matches ^[0-9a-f]{64}$
    • parents array of string required matches ^[0-9a-f]{64}$
    • manifest string required matches ^[0-9a-f]{64}$
    • author object required
      • id string
      • name string required
    • committer object required
      • id string
      • name string required
    • authoredAt string required
    • receivedAt string required

      ISO 8601, UTC.

    • receivedBy string or null required
    • authorVerified boolean required
    • imported boolean required
    • message string required
    • kind string required
    • state string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
  • created array of object
    • kind one of variable, quantity, formula, assumption, test, category, list, scale required open: more values may be added within v1
    • name string required
    • id string required
  • diagnostics array of object required
    • formulaId string required
    • name string required
    • status string required
    • diagnostics array required
  • validation object required
    • valid boolean required
    • issues array of object required
      • severity string required
      • message string required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden, branch-protected, proposal-branches-only
404
not-found, branch-not-found
409
request-in-progress, head-mismatch
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, invalid-change, invalid-logic, invalid-model, trusted-record, checks-failed, missing-objects, compute-limit
429
rate-limited
503
compute-busy

Branches and tags

POST /v1/models/{modelId}/branches

Create a branch.

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • name string required
  • from string or null
  • description string
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

201 response

Success.

  • branch object required
    • name string required
    • head string or null required matches ^[0-9a-f]{64}$
    • protected boolean required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden
404
not-found, revision-not-found
409
request-in-progress, branch-exists
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, empty-branch, missing-objects, invalid-ref-name
429
rate-limited

DELETE /v1/models/{modelId}/branches/{name}

Delete a branch (its commits stay reachable).

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
namepathstringYes
200 response

Success.

  • deleted true required
  • head string or null required matches ^[0-9a-f]{64}$

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found, branch-not-found
409
default-branch
429
rate-limited

POST /v1/models/{modelId}/tags

Create an ordinary tag. Approved baselines stay with a person (403 person-required).

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • name string required
  • target string required
  • kind one of ordinary, approved-baseline
  • message string
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

201 response

Success.

  • tag object required
    • name string required
    • target string required matches ^[0-9a-f]{64}$
    • kind one of ordinary, approved-baseline required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden, person-required
404
not-found, revision-not-found
409
request-in-progress, tag-exists
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, empty-branch, missing-objects, invalid-ref-name
429
rate-limited

Merges

POST /v1/models/{modelId}/merges/preview

Preview the merge of two branches with resolutions.

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Request body
  • source string required
  • target string required
  • resolutions map of string to one of ours, theirs, base, both
200 response

Success.

  • sourceHead string required matches ^[0-9a-f]{64}$
  • targetHead string or null required matches ^[0-9a-f]{64}$
  • fastForward boolean required
  • conflicts array required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope
404
not-found, branch-not-found, commit-not-found
413
payload-too-large
415
unsupported-media-type
422
invalid-request, compute-limit, empty-branch, missing-objects
429
rate-limited
503
compute-busy

POST /v1/models/{modelId}/merges

Merge a branch; for a program the server builds the merge commit.

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • targetBranch string required
  • sourceBranch string required
  • expectedTargetHead string or null required matches ^[0-9a-f]{64}$
  • expectedSourceHead string required matches ^[0-9a-f]{64}$
  • resolutions map of string to one of ours, theirs, base, both
  • mergeRequestId string
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

200 response

Success.

  • merge object required
    • head string required matches ^[0-9a-f]{64}$
    • fastForward boolean required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden, branch-protected, approval-required
404
not-found, branch-not-found, commit-not-found, merge-request-not-found
409
request-in-progress, stale-merge, nothing-to-merge, not-fast-forward, fast-forward-disabled, merge-request-closed, head-mismatch
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, compute-limit, same-branch, unresolved-conflicts, merge-request-mismatch, invalid-merge-commit, checks-failed, missing-objects
429
rate-limited
503
compute-busy

GET /v1/models/{modelId}/merge-requests

Merge requests, the newest first.

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
statequeryone of open, closed, merged, allNoopen by default.
limitqueryinteger 1 to 500NoRows on a page, at most 500; 500 without it.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque.
200 response

Success.

  • mergeRequests array of object required
    • id string required
    • number number required
    • state string required
    • sourceBranch string required
    • targetBranch string required
  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
422
invalid-request
429
rate-limited

POST /v1/models/{modelId}/merge-requests

Open a merge request (approval stays in the app).

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • title string required
  • description string
  • sourceBranch string required
  • targetBranch string required
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

201 response

Success.

  • mergeRequest object required
    • id string required
    • number number required
    • state string required
    • sourceBranch string required
    • targetBranch string required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden
404
not-found, branch-not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, same-branch
429
rate-limited

GET /v1/models/{modelId}/merge-requests/{mrId}

One merge request.

Scope: models:read

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
mrIdpathstringYes
200 response

Success.

  • mergeRequest object required
    • id string required
    • number number required
    • state string required
    • sourceBranch string required
    • targetBranch string required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found, merge-request-not-found
429
rate-limited

POST /v1/models/{modelId}/merge-requests/{mrId}/close

Close a merge request.

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
mrIdpathstringYes
200 response

Success.

  • mergeRequest object required
    • id string required
    • number number required
    • state string required
    • sourceBranch string required
    • targetBranch string required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found, merge-request-not-found
409
merge-request-merged, no-change
429
rate-limited

POST /v1/models/{modelId}/merge-requests/{mrId}/reopen

Reopen a merge request.

Scope: models:write

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
mrIdpathstringYes
200 response

Success.

  • mergeRequest object required
    • id string required
    • number number required
    • state string required
    • sourceBranch string required
    • targetBranch string required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found, merge-request-not-found
409
merge-request-merged, no-change
429
rate-limited

Analyses

POST /v1/analyses

One exact check of a stored revision (or of a snapshot sent with the request).

Scope: analyses

Request body
  • modelId string
  • revision string
  • snapshot any JSON value
  • query object required
    • kind string required
  • crossCheck boolean
200 response

Success.

  • result object required

    Transport status is separate from the verdict: an exhausted budget is unknown with its reason, never an HTTP error.

    • verdict one of holds, violated, unknown required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden, consent-required
404
revision-not-found, not-found
413
payload-too-large
415
unsupported-media-type
422
invalid-request, empty-branch, missing-objects, compute-limit, invalid-model
429
rate-limited, compute-quota
503
compute-busy

POST /v1/logic/parse

Diagnostics with positions and repairs, the canonical text, and the literal reading.

Scope: analyses

Request body
  • text string required at most 20000 characters
  • context one of the forms below
      • text object required
        • mode one of decision, argument
        • categories array of object at most 64 items

          Categories with their values and lists (FR-26).

          • name string required 1 to 200 characters
          • values array of one of the forms below required 1 to 2000 items

            Its values in order: names (identifiers), or names with display labels.

              • name string required 1 to 200 characters
              • label string at most 200 characters
          • lists array of object at most 500 items

            Named lists of its values, which membership tests and formulas use (plan IN Paid).

            • name string required 1 to 200 characters
            • values array of string required at most 2000 items; 1 to 200 characters

              Values of the category, by name.

        • scales array of object at most 64 items

          Ordered scales with their levels (FR-27).

          • name string required 1 to 200 characters
          • levels array of string required 1 to 100 items; 1 to 200 characters

            Level labels, from the lowest to the highest.

          • outside array of string at most 8 items; 1 to 200 characters

            Values on no level, such as "Not rated": they meet no comparison.

        • quantities array of object at most 64 items

          What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

          • name string required 1 to 200 characters
          • domain one of integer, decimal, category, set, scale required

            A number, one value of a category, a set of its values, or a level of a scale.

          • category string 1 to 200 characters

            For category and set: the category, by name.

          • scale string 1 to 200 characters

            For scale: the scale, by name.

        • inputs array of object at most 64 items
          • name string required 1 to 200 characters
          • threshold object

            A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

            • quantity string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • bound string required at most 40 characters

              A number; on a scale quantity, the label of a level.

            • domain one of integer, decimal

              When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

          • membership object

            A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

            • quantity string required 1 to 200 characters

              A category or set-valued quantity, by name.

            • test one of in, any, all, none

              in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

            • values array of string 1 to 2000 items; 1 to 200 characters

              Values of the category, by name. Send these or list.

            • list string 1 to 200 characters

              A list of the category, by name. Send this or values.

          • comparison object

            Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

            • left string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • right string required 1 to 200 characters
          • rated object

            The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

            • quantity string required 1 to 200 characters
        • formulas array of object at most 64 items

          Outputs in decision mode; premises in argument mode.

          • name string 1 to 200 characters
          • text string required at most 20000 characters
        • conclusion string at most 20000 characters
        • assumptions array of object at most 64 items
          • text string required at most 20000 characters
          • name string 1 to 200 characters
          • description string at most 2000 characters
      • logic object required
        • schema "tangibool.logic/1" required
  • language one of en, fr, de, es

Any other field is refused.

200 response

Success.

  • status string required
  • diagnostics array required
  • canonicalText string or null required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, consent-required
413
payload-too-large
415
unsupported-media-type
422
invalid-request, invalid-model, invalid-change, unknown-formula, unknown-input, compute-limit
429
rate-limited, compute-quota
503
compute-busy

POST /v1/logic/evaluate

Outputs and the evaluation trace of one case.

Scope: analyses

Request body
  • logic one of the forms below required
      • text object required
        • mode one of decision, argument
        • categories array of object at most 64 items

          Categories with their values and lists (FR-26).

          • name string required 1 to 200 characters
          • values array of one of the forms below required 1 to 2000 items

            Its values in order: names (identifiers), or names with display labels.

              • name string required 1 to 200 characters
              • label string at most 200 characters
          • lists array of object at most 500 items

            Named lists of its values, which membership tests and formulas use (plan IN Paid).

            • name string required 1 to 200 characters
            • values array of string required at most 2000 items; 1 to 200 characters

              Values of the category, by name.

        • scales array of object at most 64 items

          Ordered scales with their levels (FR-27).

          • name string required 1 to 200 characters
          • levels array of string required 1 to 100 items; 1 to 200 characters

            Level labels, from the lowest to the highest.

          • outside array of string at most 8 items; 1 to 200 characters

            Values on no level, such as "Not rated": they meet no comparison.

        • quantities array of object at most 64 items

          What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

          • name string required 1 to 200 characters
          • domain one of integer, decimal, category, set, scale required

            A number, one value of a category, a set of its values, or a level of a scale.

          • category string 1 to 200 characters

            For category and set: the category, by name.

          • scale string 1 to 200 characters

            For scale: the scale, by name.

        • inputs array of object at most 64 items
          • name string required 1 to 200 characters
          • threshold object

            A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

            • quantity string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • bound string required at most 40 characters

              A number; on a scale quantity, the label of a level.

            • domain one of integer, decimal

              When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

          • membership object

            A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

            • quantity string required 1 to 200 characters

              A category or set-valued quantity, by name.

            • test one of in, any, all, none

              in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

            • values array of string 1 to 2000 items; 1 to 200 characters

              Values of the category, by name. Send these or list.

            • list string 1 to 200 characters

              A list of the category, by name. Send this or values.

          • comparison object

            Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

            • left string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • right string required 1 to 200 characters
          • rated object

            The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

            • quantity string required 1 to 200 characters
        • formulas array of object at most 64 items

          Outputs in decision mode; premises in argument mode.

          • name string 1 to 200 characters
          • text string required at most 20000 characters
        • conclusion string at most 20000 characters
        • assumptions array of object at most 64 items
          • text string required at most 20000 characters
          • name string 1 to 200 characters
          • description string at most 2000 characters
      • logic object required
        • schema "tangibool.logic/1" required
  • assignment map of string to boolean required

    Input values by input ID or name.

  • language one of en, fr, de, es

Any other field is refused.

200 response

Success.

  • logicDigest string
  • engineVersion string
  • semanticsVersion string
  • complete boolean required
  • formulas map of string to boolean required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, consent-required
413
payload-too-large
415
unsupported-media-type
422
invalid-request, invalid-model, invalid-change, unknown-formula, unknown-input, compute-limit
429
rate-limited, compute-quota
503
compute-busy

POST /v1/logic/check

One exact property of logic sent as text.

Scope: analyses

Request body
  • logic one of the forms below required
      • text object required
        • mode one of decision, argument
        • categories array of object at most 64 items

          Categories with their values and lists (FR-26).

          • name string required 1 to 200 characters
          • values array of one of the forms below required 1 to 2000 items

            Its values in order: names (identifiers), or names with display labels.

              • name string required 1 to 200 characters
              • label string at most 200 characters
          • lists array of object at most 500 items

            Named lists of its values, which membership tests and formulas use (plan IN Paid).

            • name string required 1 to 200 characters
            • values array of string required at most 2000 items; 1 to 200 characters

              Values of the category, by name.

        • scales array of object at most 64 items

          Ordered scales with their levels (FR-27).

          • name string required 1 to 200 characters
          • levels array of string required 1 to 100 items; 1 to 200 characters

            Level labels, from the lowest to the highest.

          • outside array of string at most 8 items; 1 to 200 characters

            Values on no level, such as "Not rated": they meet no comparison.

        • quantities array of object at most 64 items

          What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

          • name string required 1 to 200 characters
          • domain one of integer, decimal, category, set, scale required

            A number, one value of a category, a set of its values, or a level of a scale.

          • category string 1 to 200 characters

            For category and set: the category, by name.

          • scale string 1 to 200 characters

            For scale: the scale, by name.

        • inputs array of object at most 64 items
          • name string required 1 to 200 characters
          • threshold object

            A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

            • quantity string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • bound string required at most 40 characters

              A number; on a scale quantity, the label of a level.

            • domain one of integer, decimal

              When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

          • membership object

            A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

            • quantity string required 1 to 200 characters

              A category or set-valued quantity, by name.

            • test one of in, any, all, none

              in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

            • values array of string 1 to 2000 items; 1 to 200 characters

              Values of the category, by name. Send these or list.

            • list string 1 to 200 characters

              A list of the category, by name. Send this or values.

          • comparison object

            Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

            • left string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • right string required 1 to 200 characters
          • rated object

            The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

            • quantity string required 1 to 200 characters
        • formulas array of object at most 64 items

          Outputs in decision mode; premises in argument mode.

          • name string 1 to 200 characters
          • text string required at most 20000 characters
        • conclusion string at most 20000 characters
        • assumptions array of object at most 64 items
          • text string required at most 20000 characters
          • name string 1 to 200 characters
          • description string at most 2000 characters
      • logic object required
        • schema "tangibool.logic/1" required
  • query object required
    • kind one of consistency, satisfiable, tautology, falsifiable, contradiction, equivalence, validity, premises-consistent required
    • formula string 1 to 300 characters

      The formula, by ID or name.

    • otherFormula string 1 to 300 characters
    • otherText string at most 20000 characters

Any other field is refused.

200 response

Success.

  • logicDigest string
  • engineVersion string
  • semanticsVersion string
  • inputs array of object required

    The inputs by ID and name: cases name inputs by ID, and logic sent as text has no IDs of its own.

    • id string required
    • name string required
  • result object required

    Transport status is separate from the verdict: an exhausted budget is unknown with its reason, never an HTTP error.

    • verdict one of holds, violated, unknown required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, consent-required
413
payload-too-large
415
unsupported-media-type
422
invalid-request, invalid-model, invalid-change, unknown-formula, unknown-input, compute-limit
429
rate-limited, compute-quota
503
compute-busy

POST /v1/logic/compare

Equivalent, at least as strict, looser, or incomparable, with a replayed case for each direction that fails.

Scope: analyses

Request body
  • logic one of the forms below required
      • text object required
        • mode one of decision, argument
        • categories array of object at most 64 items

          Categories with their values and lists (FR-26).

          • name string required 1 to 200 characters
          • values array of one of the forms below required 1 to 2000 items

            Its values in order: names (identifiers), or names with display labels.

              • name string required 1 to 200 characters
              • label string at most 200 characters
          • lists array of object at most 500 items

            Named lists of its values, which membership tests and formulas use (plan IN Paid).

            • name string required 1 to 200 characters
            • values array of string required at most 2000 items; 1 to 200 characters

              Values of the category, by name.

        • scales array of object at most 64 items

          Ordered scales with their levels (FR-27).

          • name string required 1 to 200 characters
          • levels array of string required 1 to 100 items; 1 to 200 characters

            Level labels, from the lowest to the highest.

          • outside array of string at most 8 items; 1 to 200 characters

            Values on no level, such as "Not rated": they meet no comparison.

        • quantities array of object at most 64 items

          What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

          • name string required 1 to 200 characters
          • domain one of integer, decimal, category, set, scale required

            A number, one value of a category, a set of its values, or a level of a scale.

          • category string 1 to 200 characters

            For category and set: the category, by name.

          • scale string 1 to 200 characters

            For scale: the scale, by name.

        • inputs array of object at most 64 items
          • name string required 1 to 200 characters
          • threshold object

            A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

            • quantity string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • bound string required at most 40 characters

              A number; on a scale quantity, the label of a level.

            • domain one of integer, decimal

              When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

          • membership object

            A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

            • quantity string required 1 to 200 characters

              A category or set-valued quantity, by name.

            • test one of in, any, all, none

              in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

            • values array of string 1 to 2000 items; 1 to 200 characters

              Values of the category, by name. Send these or list.

            • list string 1 to 200 characters

              A list of the category, by name. Send this or values.

          • comparison object

            Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

            • left string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • right string required 1 to 200 characters
          • rated object

            The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

            • quantity string required 1 to 200 characters
        • formulas array of object at most 64 items

          Outputs in decision mode; premises in argument mode.

          • name string 1 to 200 characters
          • text string required at most 20000 characters
        • conclusion string at most 20000 characters
        • assumptions array of object at most 64 items
          • text string required at most 20000 characters
          • name string 1 to 200 characters
          • description string at most 2000 characters
      • logic object required
        • schema "tangibool.logic/1" required
  • a string required 1 to 300 characters

    A formula by ID or name.

  • b string required 1 to 300 characters

Any other field is refused.

200 response

Success.

  • logicDigest string
  • engineVersion string
  • semanticsVersion string
  • inputs array of object required

    The inputs by ID and name: cases name inputs by ID, and logic sent as text has no IDs of its own.

    • id string required
    • name string required
  • result object required
    • relation string required
    • aWithinB one of holds, violated, unknown required
    • bWithinA one of holds, violated, unknown required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, consent-required
413
payload-too-large
415
unsupported-media-type
422
invalid-request, invalid-model, invalid-change, unknown-formula, unknown-input, compute-limit
429
rate-limited, compute-quota
503
compute-busy

POST /v1/logic/truth-table

One page of the truth table: row 0 is all FALSE and the first input is the most significant bit.

Scope: analyses

Request body
  • logic one of the forms below required
      • text object required
        • mode one of decision, argument
        • categories array of object at most 64 items

          Categories with their values and lists (FR-26).

          • name string required 1 to 200 characters
          • values array of one of the forms below required 1 to 2000 items

            Its values in order: names (identifiers), or names with display labels.

              • name string required 1 to 200 characters
              • label string at most 200 characters
          • lists array of object at most 500 items

            Named lists of its values, which membership tests and formulas use (plan IN Paid).

            • name string required 1 to 200 characters
            • values array of string required at most 2000 items; 1 to 200 characters

              Values of the category, by name.

        • scales array of object at most 64 items

          Ordered scales with their levels (FR-27).

          • name string required 1 to 200 characters
          • levels array of string required 1 to 100 items; 1 to 200 characters

            Level labels, from the lowest to the highest.

          • outside array of string at most 8 items; 1 to 200 characters

            Values on no level, such as "Not rated": they meet no comparison.

        • quantities array of object at most 64 items

          What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

          • name string required 1 to 200 characters
          • domain one of integer, decimal, category, set, scale required

            A number, one value of a category, a set of its values, or a level of a scale.

          • category string 1 to 200 characters

            For category and set: the category, by name.

          • scale string 1 to 200 characters

            For scale: the scale, by name.

        • inputs array of object at most 64 items
          • name string required 1 to 200 characters
          • threshold object

            A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

            • quantity string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • bound string required at most 40 characters

              A number; on a scale quantity, the label of a level.

            • domain one of integer, decimal

              When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

          • membership object

            A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

            • quantity string required 1 to 200 characters

              A category or set-valued quantity, by name.

            • test one of in, any, all, none

              in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

            • values array of string 1 to 2000 items; 1 to 200 characters

              Values of the category, by name. Send these or list.

            • list string 1 to 200 characters

              A list of the category, by name. Send this or values.

          • comparison object

            Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

            • left string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • right string required 1 to 200 characters
          • rated object

            The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

            • quantity string required 1 to 200 characters
        • formulas array of object at most 64 items

          Outputs in decision mode; premises in argument mode.

          • name string 1 to 200 characters
          • text string required at most 20000 characters
        • conclusion string at most 20000 characters
        • assumptions array of object at most 64 items
          • text string required at most 20000 characters
          • name string 1 to 200 characters
          • description string at most 2000 characters
      • logic object required
        • schema "tangibool.logic/1" required
  • page integer 0 to 9007199254740991; default 0
  • pageSize integer 1 to 1024; default 256

Any other field is refused.

200 response

Success.

  • logicDigest string
  • engineVersion string
  • semanticsVersion string
  • rowCount number required
  • pages number required
  • rows array of object required
    • row number required
    • inputs array of boolean required
    • values array of boolean required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, consent-required
413
payload-too-large
415
unsupported-media-type
422
invalid-request, invalid-model, invalid-change, unknown-formula, unknown-input, compute-limit, limit-exceeded
429
rate-limited, compute-quota
503
compute-busy

POST /v1/logic/reasons

Why a case got its result: necessary conditions, ways to qualify, a reason, and the smallest changes.

Scope: analyses

Request body
  • logic one of the forms below required
      • text object required
        • mode one of decision, argument
        • categories array of object at most 64 items

          Categories with their values and lists (FR-26).

          • name string required 1 to 200 characters
          • values array of one of the forms below required 1 to 2000 items

            Its values in order: names (identifiers), or names with display labels.

              • name string required 1 to 200 characters
              • label string at most 200 characters
          • lists array of object at most 500 items

            Named lists of its values, which membership tests and formulas use (plan IN Paid).

            • name string required 1 to 200 characters
            • values array of string required at most 2000 items; 1 to 200 characters

              Values of the category, by name.

        • scales array of object at most 64 items

          Ordered scales with their levels (FR-27).

          • name string required 1 to 200 characters
          • levels array of string required 1 to 100 items; 1 to 200 characters

            Level labels, from the lowest to the highest.

          • outside array of string at most 8 items; 1 to 200 characters

            Values on no level, such as "Not rated": they meet no comparison.

        • quantities array of object at most 64 items

          What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

          • name string required 1 to 200 characters
          • domain one of integer, decimal, category, set, scale required

            A number, one value of a category, a set of its values, or a level of a scale.

          • category string 1 to 200 characters

            For category and set: the category, by name.

          • scale string 1 to 200 characters

            For scale: the scale, by name.

        • inputs array of object at most 64 items
          • name string required 1 to 200 characters
          • threshold object

            A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

            • quantity string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • bound string required at most 40 characters

              A number; on a scale quantity, the label of a level.

            • domain one of integer, decimal

              When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

          • membership object

            A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

            • quantity string required 1 to 200 characters

              A category or set-valued quantity, by name.

            • test one of in, any, all, none

              in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

            • values array of string 1 to 2000 items; 1 to 200 characters

              Values of the category, by name. Send these or list.

            • list string 1 to 200 characters

              A list of the category, by name. Send this or values.

          • comparison object

            Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

            • left string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • right string required 1 to 200 characters
          • rated object

            The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

            • quantity string required 1 to 200 characters
        • formulas array of object at most 64 items

          Outputs in decision mode; premises in argument mode.

          • name string 1 to 200 characters
          • text string required at most 20000 characters
        • conclusion string at most 20000 characters
        • assumptions array of object at most 64 items
          • text string required at most 20000 characters
          • name string 1 to 200 characters
          • description string at most 2000 characters
      • logic object required
        • schema "tangibool.logic/1" required
  • formula string required 1 to 300 characters
  • value boolean
  • assignment map of string to boolean

    Input values by input ID or name.

  • fixed array of string at most 64 items; 1 to 300 characters

Any other field is refused.

200 response

Success.

  • logicDigest string
  • engineVersion string
  • semanticsVersion string
  • necessary any JSON value required
  • waysToQualify any JSON value required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, consent-required
413
payload-too-large
415
unsupported-media-type
422
invalid-request, invalid-model, invalid-change, unknown-formula, unknown-input, compute-limit
429
rate-limited, compute-quota
503
compute-busy

POST /v1/logic/code

Python, PostgreSQL, or SMT-LIB generated from logic sent with a request.

Scope: analyses

Request body
  • logic one of the forms below required
      • text object required
        • mode one of decision, argument
        • categories array of object at most 64 items

          Categories with their values and lists (FR-26).

          • name string required 1 to 200 characters
          • values array of one of the forms below required 1 to 2000 items

            Its values in order: names (identifiers), or names with display labels.

              • name string required 1 to 200 characters
              • label string at most 200 characters
          • lists array of object at most 500 items

            Named lists of its values, which membership tests and formulas use (plan IN Paid).

            • name string required 1 to 200 characters
            • values array of string required at most 2000 items; 1 to 200 characters

              Values of the category, by name.

        • scales array of object at most 64 items

          Ordered scales with their levels (FR-27).

          • name string required 1 to 200 characters
          • levels array of string required 1 to 100 items; 1 to 200 characters

            Level labels, from the lowest to the highest.

          • outside array of string at most 8 items; 1 to 200 characters

            Values on no level, such as "Not rated": they meet no comparison.

        • quantities array of object at most 64 items

          What inputs are defined on, and what formulas test by name (plan IN Paid). A threshold on a quantity not listed here creates a number.

          • name string required 1 to 200 characters
          • domain one of integer, decimal, category, set, scale required

            A number, one value of a category, a set of its values, or a level of a scale.

          • category string 1 to 200 characters

            For category and set: the category, by name.

          • scale string 1 to 200 characters

            For scale: the scale, by name.

        • inputs array of object at most 64 items
          • name string required 1 to 200 characters
          • threshold object

            A quantity compared with a number, or with a level of its scale (FR-25, FR-27).

            • quantity string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • bound string required at most 40 characters

              A number; on a scale quantity, the label of a level.

            • domain one of integer, decimal

              When the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).

          • membership object

            A membership test (FR-26): plan IN Paid, country IN {DE, FR}, activities HAS ANY Excluded.

            • quantity string required 1 to 200 characters

              A category or set-valued quantity, by name.

            • test one of in, any, all, none

              in on a category quantity (the default there); any (the default there), all, or none on a set-valued one.

            • values array of string 1 to 2000 items; 1 to 200 characters

              Values of the category, by name. Send these or list.

            • list string 1 to 200 characters

              A list of the category, by name. Send this or values.

          • comparison object

            Two quantities on one scale compared, such as product_risk <= client_risk (FR-27); an outside value on either side makes it FALSE.

            • left string required 1 to 200 characters
            • comparator one of <, <=, >, >= required
            • right string required 1 to 200 characters
          • rated object

            The rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).

            • quantity string required 1 to 200 characters
        • formulas array of object at most 64 items

          Outputs in decision mode; premises in argument mode.

          • name string 1 to 200 characters
          • text string required at most 20000 characters
        • conclusion string at most 20000 characters
        • assumptions array of object at most 64 items
          • text string required at most 20000 characters
          • name string 1 to 200 characters
          • description string at most 2000 characters
      • logic object required
        • schema "tangibool.logic/1" required
  • target one of python, postgresql, smt-lib required

Any other field is refused.

200 response

Success.

  • logicDigest string
  • engineVersion string
  • semanticsVersion string
  • target one of python, postgresql, smt-lib required
  • code string required
  • provenance string required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, consent-required
413
payload-too-large
415
unsupported-media-type
422
invalid-request, invalid-model, invalid-change, unknown-formula, unknown-input, compute-limit
429
rate-limited, compute-quota
503
compute-busy

Jobs

POST /v1/test-runs

Run the saved tests of a revision.

Scope: analyses

Parameters

NameInTypeRequiredDescription
PreferheaderstringNowait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time.
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • modelId string required
  • revision string required

    A branch, a tag, or a commit ID.

  • options object

    The options of a test-run job.

    • testIds array of string at most 1000 items; at most 200 characters
    • budgetMs integer 100 to 60000
    • perQueryBudgetMs integer 10 to 10000
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

Any other field is refused.

200 response

The job ended within the time asked for with Prefer: wait.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required
202 response

Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden
404
not-found, revision-not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, empty-branch, missing-objects, invalid-model, unsupported-content
429
rate-limited, too-many-operations, compute-quota
503
jobs-busy

GET /v1/test-runs/{operationId}

A test run.

Scope: analyses

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

DELETE /v1/test-runs/{operationId}

Cancel a test run.

Scope: analyses

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
429
rate-limited

POST /v1/coverage-runs

Coverage of a revision’s tests.

Scope: analyses

Parameters

NameInTypeRequiredDescription
PreferheaderstringNowait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time.
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • modelId string required
  • revision string required

    A branch, a tag, or a commit ID.

  • options object

    The options of a coverage-run job.

    • includeExploratory boolean
    • budgetMs integer 100 to 60000
    • perQueryBudgetMs integer 10 to 10000
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

Any other field is refused.

200 response

The job ended within the time asked for with Prefer: wait.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required
202 response

Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden
404
not-found, revision-not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, empty-branch, missing-objects, invalid-model, unsupported-content
429
rate-limited, too-many-operations, compute-quota
503
jobs-busy

GET /v1/coverage-runs/{operationId}

A coverage run.

Scope: analyses

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

DELETE /v1/coverage-runs/{operationId}

Cancel a coverage run.

Scope: analyses

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
429
rate-limited

POST /v1/mutation-runs

Mutation testing of a revision.

Scope: analyses

Parameters

NameInTypeRequiredDescription
PreferheaderstringNowait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time.
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • modelId string required
  • revision string required

    A branch, a tag, or a commit ID.

  • options object

    The options of a mutation-run job.

    • seed integer 0 to 2147483647
    • maxMutants integer 1 to 500
    • operators array of one of and-or-swap, xor-or-swap, xor-xnor-swap, implication-reversal, negation-removal, operand-removal, negation-insertion, constant-replacement, input-substitution, threshold-comparator, threshold-bound, count-bound, count-kind, list-member, list-substitution, scale-comparison, points-cutoff, points-weight, points-row-removal, outcome-swap, row-removal, row-order 1 to 22 items
    • independentOnly boolean
    • budgetMs integer 100 to 30000
    • perQueryBudgetMs integer 10 to 10000
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

Any other field is refused.

200 response

The job ended within the time asked for with Prefer: wait.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required
202 response

Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden
404
not-found, revision-not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, empty-branch, missing-objects, invalid-model, unsupported-content
429
rate-limited, too-many-operations, compute-quota
503
jobs-busy

GET /v1/mutation-runs/{operationId}

A mutation run.

Scope: analyses

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

DELETE /v1/mutation-runs/{operationId}

Cancel a mutation run.

Scope: analyses

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
429
rate-limited

GET /v1/operations/{operationId}

Status and result of any job.

Scope: analyses or exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

DELETE /v1/operations/{operationId}

Cancel any job.

Scope: analyses or exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
429
rate-limited

Exports

POST /v1/exports

Export a revision (snapshot export).

Scope: exports

Parameters

NameInTypeRequiredDescription
PreferheaderstringNowait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time.
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • modelId string required
  • revision string required

    A branch, a tag, or a commit ID.

  • options object required

    The options of a export job.

    • items array of object required 1 to 500 items
      • target one of model-report, source, glossary, formulas, explanation, truth-table, tests, test-report, diagram, formula-card, kmap, strictness-map, venn, mapping-diagram, notes, discussion, snapshot required
      • format one of md, txt, py, json, sql, tex, smt2, png, jpg, jpeg, csv, svg, xml required
      • options object
        • formulaId string at most 200 characters
        • noteIds array of string at most 1000 items; at most 300 characters
        • rowsPerPage integer 4 to 256
        • intermediateColumns boolean
        • fragment boolean
        • includeGetModel boolean
        • includePropertyTests boolean
        • ruleIds array of string 2 to 12 items; at most 200 characters
        • listIds array of string 2 to 3 items; at most 200 characters
        • quantityId string at most 200 characters
        • mappingId string at most 200 characters
    • theme one of light, dark default "light"
    • scale 1 or 2 or 4 default 2
    • width integer 16 to 8192
    • background string matches ^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$
    • jpegQuality integer 1 to 100; default 90
    • transparent boolean default false
    • cleanImage boolean default false
    • asciiOperators boolean default false
    • notation one of words, programming, mathematical, algebra
    • level one of beginner, intermediate, advanced default "intermediate"
    • archive boolean default true
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

Any other field is refused.

200 response

The job ended within the time asked for with Prefer: wait.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required
202 response

Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden
404
not-found, revision-not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, empty-branch, missing-objects, invalid-model, unsupported-content
429
rate-limited, too-many-operations, compute-quota
503
jobs-busy

GET /v1/exports/{operationId}

An export.

Scope: exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

DELETE /v1/exports/{operationId}

Cancel an export.

Scope: exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
429
rate-limited

GET /v1/exports/{operationId}/download

Download an export package.

Scope: exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

A file: application/zip

Errors

401
unauthenticated
403
insufficient-scope
404
not-found, no-download
422
not-ready
429
rate-limited

POST /v1/history-exports

Export the full history.

Scope: exports

Parameters

NameInTypeRequiredDescription
PreferheaderstringNowait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time.
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • modelId string required
  • revision string required

    A branch, a tag, or a commit ID.

  • options object

    The options of a history-export job.

    • branches array of string 1 to 1000 items; 1 to 100 characters
    • items array of object at most 50 items; default []
      • target one of history, history-summary, history-graph, visual-diff required
      • format one of md, txt, py, json, sql, tex, smt2, png, jpg, jpeg, csv, svg, xml required
      • options object
        • historyLimit integer 1 to 100000
        • compareCommit string matches ^[0-9a-f]{64}$
        • rowsPerPage integer 4 to 256
        • fragment boolean
    • theme one of light, dark default "light"
    • scale 1 or 2 or 4 default 2
    • width integer 16 to 8192
    • background string matches ^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$
    • jpegQuality integer 1 to 100; default 90
    • transparent boolean default false
    • cleanImage boolean default false
    • asciiOperators boolean default false
    • notation one of words, programming, mathematical, algebra
    • level one of beginner, intermediate, advanced default "intermediate"
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

Any other field is refused.

200 response

The job ended within the time asked for with Prefer: wait.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required
202 response

Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

400
invalid-json
401
unauthenticated
402
plan-limit
403
insufficient-scope, forbidden
404
not-found, revision-not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, empty-branch, missing-objects, invalid-model, unsupported-content
429
rate-limited, too-many-operations, compute-quota
503
jobs-busy

GET /v1/history-exports/{operationId}

A history export.

Scope: exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

DELETE /v1/history-exports/{operationId}

Cancel a history export.

Scope: exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

  • operation object required
    • id string required
    • kind string required
    • status one of queued, running, succeeded, failed, cancelled, timed-out required open: more values may be added within v1
    • modelId string required
    • requestedBy object or null required
      • id string
      • name string required
    • via object or null required

      The token, app, or assistant a program acted through; null for changes made in the app.

      • kind one of token, app, assistant required
      • id string required
      • name string required
    • createdAt string required

      ISO 8601, UTC.

    • finishedAt string or null required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
429
rate-limited

GET /v1/history-exports/{operationId}/download

Download a history package.

Scope: exports

Parameters

NameInTypeRequiredDescription
operationIdpathstringYes
200 response

Success.

A file: application/zip

Errors

401
unauthenticated
403
insufficient-scope
404
not-found, no-download
422
not-ready
429
rate-limited

Discussion

GET /v1/models/{modelId}/threads

Discussion threads of a model, the newest first.

Scope: discussion

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
statequeryone of open, resolved, allNoall by default.
includequerystringNomessages adds the messages and events of the threads on the page.
limitqueryinteger 1 to 1000NoRows on a page, at most 1000; every thread without it.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque.
200 response

Success.

  • threads array of object required
    • id string required
    • title string required
    • state one of open, resolved required
  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
422
invalid-request
429
rate-limited

POST /v1/models/{modelId}/threads

Start a thread.

Scope: discussion

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • title string
  • body string required
  • anchor any JSON value
  • label string
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

201 response

Success.

  • thread object required
    • id string required
    • title string required
    • state one of open, resolved required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, limit-exceeded, anchor-too-large, unsupported-content
429
rate-limited

GET /v1/threads/{threadId}

A thread with its messages.

Scope: discussion

Parameters

NameInTypeRequiredDescription
threadIdpathstringYes
200 response

Success.

  • thread object required
    • id string required
    • title string required
    • state one of open, resolved required

Errors

401
unauthenticated
403
insufficient-scope
404
not-found
429
rate-limited

POST /v1/threads/{threadId}/messages

Reply in a thread.

Scope: discussion

Parameters

NameInTypeRequiredDescription
threadIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • body string required
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

201 response

Success.

  • message object required
    • id string required
    • body string required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
409
request-in-progress
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, limit-exceeded, invalid-parent, unsupported-content
429
rate-limited

Webhooks

GET /v1/models/{modelId}/webhooks

Webhook subscriptions of a model, the oldest first.

Scope: webhooks

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
limitqueryinteger 1 to 500NoRows on a page, at most 500; every subscription without it.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque.
200 response

Success.

  • webhooks array of object required
    • id string required
    • url string required
    • events array of string required
    • paused boolean required
  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
422
invalid-request
429
rate-limited

POST /v1/models/{modelId}/webhooks

Subscribe to a model’s events; the signing secret is shown once, and again only to a retry with the same idempotency key.

Scope: webhooks

Parameters

NameInTypeRequiredDescription
modelIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • url string required
  • events array of string required
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

201 response

Success.

  • webhook object required
    • id string required
    • url string required
    • events array of string required
    • paused boolean required
  • secret string required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
409
request-in-progress, too-many-webhooks
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, invalid-webhook-url
429
rate-limited

GET /v1/teams/{teamId}/webhooks

Webhook subscriptions of a team, the oldest first.

Scope: webhooks

Parameters

NameInTypeRequiredDescription
teamIdpathstringYes
limitqueryinteger 1 to 500NoRows on a page, at most 500; every subscription without it.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque.
200 response

Success.

  • webhooks array of object required
    • id string required
    • url string required
    • events array of string required
    • paused boolean required
  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
422
invalid-request
429
rate-limited

POST /v1/teams/{teamId}/webhooks

Subscribe to a team’s events; the signing secret is shown once, and again only to a retry with the same idempotency key.

Scope: webhooks

Parameters

NameInTypeRequiredDescription
teamIdpathstringYes
Idempotency-Keyheaderstring 1 to 200 characters; matches ^[\x21-\x7e]+$NoMakes the create safe to retry. For 24 hours, a retry of the same request with the same key gets the first answer again, with Idempotent-Replayed: true (for a thread or a message: what it created as it is now, for as long as the message exists). The same key with another request is 422 idempotency-key-reused, and a retry while the first is still running 409 request-in-progress; a failed attempt leaves no record. Keys are per user, and per model or team on their routes. The body field idempotencyKey is the same key; when both are sent they must agree.
Request body
  • url string required
  • events array of string required
  • idempotencyKey string 1 to 200 characters; matches ^[\x21-\x7e]+$

    The Idempotency-Key header as a body field; when both are sent they must agree.

201 response

Success.

  • webhook object required
    • id string required
    • url string required
    • events array of string required
    • paused boolean required
  • secret string required

Errors

400
invalid-json
401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
409
request-in-progress, too-many-webhooks
413
payload-too-large
415
unsupported-media-type
422
invalid-request, idempotency-key-reused, idempotency-key-mismatch, invalid-webhook-url
429
rate-limited

DELETE /v1/webhooks/{webhookId}

Delete a webhook subscription.

Scope: webhooks

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYes
200 response

Success.

  • deleted true required

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
429
rate-limited

GET /v1/webhooks/{webhookId}/deliveries

Deliveries of the last 7 days, the newest first.

Scope: webhooks

Parameters

NameInTypeRequiredDescription
webhookIdpathstringYes
limitqueryinteger 1 to 500NoRows on a page, at most 500; 200 without it.
cursorquerystring at most 1000 charactersNoThe nextCursor of the previous page. Opaque.
200 response

Success.

  • deliveries array of object required
    • id string required
    • event string required
    • status string required
  • nextCursor string or null required

    The cursor of the next page, in the same order; null on the last page.

Errors

401
unauthenticated
403
insufficient-scope, forbidden
404
not-found
422
invalid-request
429
rate-limited