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
- A personal access token (
tb_pat_…) made in the app, or an OAuth access token.
Errors
Every error has the same body. The code is stable and part of the contract; the guide lists the codes.
errorobject requiredcodestring requiredmessagestring requireddetailsany 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
tokenstring requiredtypestringurlstringsourcestring
200 response
Success.
array of object
token_rawstring requiredtoken_typestring requiredlabelone oftrue_positive,false_positiverequired
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.
userobject requiredidstring requireddisplayNamestring requiredemailstring requiredplanone offree,basic,pro,teamrequired
clientobject or null requiredkindone oftoken,app,assistantrequiredidstring requirednamestring requiredscopesarray of one ofmodels:read,models:write,analyses,exports,discussion,webhooksrequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer 1 to 500 | No | Rows on a page, at most 500; every team without it. |
cursor | query | string at most 1000 characters | No | The nextCursor of the previous page. Opaque. |
200 response
Success.
teamsarray of object requiredidstring requirednamestring requiredroleone ofviewer,commenter,editor,admin,ownerrequired
nextCursorstring or null requiredThe 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
teamId | path | string | Yes |
200 response
Success.
teamobject requiredidstring requirednamestring requiredroleone ofviewer,commenter,editor,admin,ownerrequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer 1 to 500 | No | Rows on a page, at most 500; every model without it. |
cursor | query | string at most 1000 characters | No | The nextCursor of the previous page. Opaque. |
200 response
Success.
modelsarray of object requiredidstring requiredtitlestring requiredroleone ofviewer,commenter,editor,admin,ownerrequiredteamIdstring or null requireddefaultBranchstring requiredupdatedAtstring requiredISO 8601, UTC.
nextCursorstring or null requiredThe 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
modeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
titlestring required 1 to 200 charactersteamIdstring or null matches^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$contentLanguageone ofen,fr,de,essourceTextstring at most 4000 charactersglossaryarray of object at most 200 itemstargetstring required 1 to 200 charactersmeaningstring required at most 2000 characters
testsarray of object at most 1000 itemsnamestring required 1 to 200 characterskindone ofscenario,propertyassignmentsmap of string to booleanInput values by input ID or name.
quantitiesmap of string to string or array of stringNumbers, levels, values, or sets by quantity ID or name.
expectedmap of string to booleanExpected values by formula ID or name.
expectedLabelsmap of string to stringExpected outcome label (ID or name) by outcome set (ID or name).
propertyone of the forms belowkindone ofsatisfiable,tautology,falsifiable,contradictionrequiredformulaIdstring required 1 to 300 characters
kind:equivalentkind"equivalent"requiredformulaIdstring required 1 to 300 charactersotherFormulaIdstring 1 to 300 charactersotherTextstring at most 20000 characters
kindone ofvalidity,premises-consistent,consistencyrequired
kindone ofrelevant,irrelevantrequiredformulaIdstring required 1 to 300 charactersvarIdstring required 1 to 300 characters
kind:at-least-as-strictkind"at-least-as-strict"requiredformulaIdstring required 1 to 300 charactersotherFormulaIdstring required 1 to 300 characters
kind:monotonekind"monotone"requiredformulaIdstring 1 to 300 characterssetIdstring 1 to 300 charactersvarIdstring 1 to 300 charactersquantityIdstring 1 to 300 charactersdirectionone ofnever-true-to-false,never-false-to-true,never-earlier,never-laterrequired
expectHoldsbooleannotesstring at most 10000 characterstagsarray of string at most 50 items; at most 100 characterssourceone ofuser-authored,user-confirmed,ai-proposed,copied-from-formula,counterexample,feedback,importedExpectation source; user-confirmed is a person’s act and is refused (422 trusted-record).
draftboolean defaultfalsemessagestring at most 2000 charactersidempotencyKeystring 1 to 200 characters; matches^[\x21-\x7e]+$
Any other field is refused.
201 response
Success.
modelobject requiredidstring requiredtitlestring requiredteamIdstring or null requiredownerIdstring or null requireddefaultBranchstring requiredlabelsarray of string requiredcreatedAtstring requiredISO 8601, UTC.
updatedAtstring requiredISO 8601, UTC.
roleone ofviewer,commenter,editor,admin,ownerrequiredpermissionsarray of string requiredrefsobject requiredbranchesmap of string to object requirednamestring requiredheadstring or null required matches^[0-9a-f]{64}$protectedboolean required
tagsmap of string to object requirednamestring requiredtargetstring required matches^[0-9a-f]{64}$kindone ofordinary,approved-baselinerequired
createdarray of object requiredkindone ofvariable,quantity,formula,assumption,test,category,list,scalerequired open: more values may be added within v1namestring requiredidstring required
diagnosticsarray of object requiredformulaIdstring requirednamestring requiredstatusstring requireddiagnosticsarray required
validationobject requiredvalidboolean requiredissuesarray of object requiredseveritystring requiredmessagestring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
view | query | one of outline | No | |
rev | query | string | No |
200 response
Success.
one of the forms below
modelobject requiredidstring requiredtitlestring requiredteamIdstring or null requiredownerIdstring or null requireddefaultBranchstring requiredlabelsarray of string requiredcreatedAtstring requiredISO 8601, UTC.
updatedAtstring requiredISO 8601, UTC.
roleone ofviewer,commenter,editor,admin,ownerrequiredpermissionsarray of string requiredrefsobject requiredbranchesmap of string to object requirednamestring requiredheadstring or null required matches^[0-9a-f]{64}$protectedboolean required
tagsmap of string to object requirednamestring requiredtargetstring required matches^[0-9a-f]{64}$kindone ofordinary,approved-baselinerequired
modelIdstring requiredcommitobject requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
outlineobject requiredschema"tangibool.outline/1"requiredmodeone ofdecision,argumentrequiredinputsarray of object requiredidstring requirednamestring requireddefinitionstring or null required
formulasarray of object requiredidstring requirednamestring requiredroleone ofoutput,premise,conclusionrequiredtextstring required
testsobject requiredtotalnumber requiredconfirmednumber required
sourceobject requiredinterpretationone ofnot-needed,unconfirmed,confirmed,invalidatedrequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes |
200 response
Success.
branchesmap of string to object requirednamestring requiredheadstring or null required matches^[0-9a-f]{64}$protectedboolean required
tagsmap of string to object requirednamestring requiredtargetstring required matches^[0-9a-f]{64}$kindone ofordinary,approved-baselinerequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
branch | query | string | No | The branch; the default branch when absent. |
commit | query | string | No | Start from this commit instead of a branch head. |
offset | query | integer 0 to 9007199254740991 | No | Commits to skip; not with cursor. |
limit | query | integer 1 to 500 | No | Commits on a page, at most 500; 100 by default. |
cursor | query | string at most 1000 characters | No | The 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. |
search | query | string | No | |
author | query | string | No | |
changed | query | string | No | Comma-separated changed domains. |
200 response
Success.
commitsarray of object requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
totalnumber requiredhasMoreboolean requirednextCursorstring or null requiredThe 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
commitId | path | string | Yes |
200 response
Success.
commitobject requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
commitId | path | string | Yes |
200 response
Success.
commitIdstring required matches^[0-9a-f]{64}$commitobject requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
snapshotobject requiredartifactsobject 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes |
Request body
fromstring requiredtostring requiredbehaviourboolean
200 response
Success.
fromobject requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
toobject requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
diffany JSON value requiredbehaviourany 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
branchstring required 1 to 100 charactersexpectedHeadstring or null required matches^[0-9a-f]{64}$messagestring at most 2000 characters; default""editsarray of one of the forms below required 1 to 500 itemsop:setFormulaTextop"setFormulaText"requiredformulaone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
textstring required at most 20000 characters
op:addFormulaop"addFormula"requirednamestring 1 to 200 characterstextstring required at most 20000 characters
op:renameFormulaop"renameFormula"requiredformulaone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
namestring required 1 to 200 characters
op:removeFormulaop"removeFormula"requiredformulaone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
op:addVariableop"addVariable"requirednamestring required 1 to 200 characters
op:renameVariableop"renameVariable"requiredvariableone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
namestring required 1 to 200 characters
op:removeVariableop"removeVariable"requiredvariableone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
replaceWithboolean or one of the forms below
op:setThresholdop"setThreshold"requiredvariableone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
quantitystring 1 to 200 charactersdomainone ofinteger,decimalcomparatorone of<,<=,>,>=boundstring at most 40 charactersclearboolean
op:setSourceTextop"setSourceText"requiredtextstring required at most 4000 characterslanguageone ofen,fr,de,es
op:setGlossaryMeaningop"setGlossaryMeaning"requiredtargetone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
meaningstring required at most 2000 characterslanguageone ofen,fr,de,es
op:addAssumptionop"addAssumption"requiredtextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
op:removeAssumptionop"removeAssumption"requiredassumptionone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
op:addTestop"addTest"requiredtestobject requirednamestring required 1 to 200 characterskindone ofscenario,propertyassignmentsmap of string to booleanInput values by input ID or name.
quantitiesmap of string to string or array of stringNumbers, levels, values, or sets by quantity ID or name.
expectedmap of string to booleanExpected values by formula ID or name.
expectedLabelsmap of string to stringExpected outcome label (ID or name) by outcome set (ID or name).
propertyone of the forms belowkindone ofsatisfiable,tautology,falsifiable,contradictionrequiredformulaIdstring required 1 to 300 characters
kind:equivalentkind"equivalent"requiredformulaIdstring required 1 to 300 charactersotherFormulaIdstring 1 to 300 charactersotherTextstring at most 20000 characters
kindone ofvalidity,premises-consistent,consistencyrequired
kindone ofrelevant,irrelevantrequiredformulaIdstring required 1 to 300 charactersvarIdstring required 1 to 300 characters
kind:at-least-as-strictkind"at-least-as-strict"requiredformulaIdstring required 1 to 300 charactersotherFormulaIdstring required 1 to 300 characters
kind:monotonekind"monotone"requiredformulaIdstring 1 to 300 characterssetIdstring 1 to 300 charactersvarIdstring 1 to 300 charactersquantityIdstring 1 to 300 charactersdirectionone ofnever-true-to-false,never-false-to-true,never-earlier,never-laterrequired
expectHoldsbooleannotesstring at most 10000 characterstagsarray of string at most 50 items; at most 100 characterssourceone ofuser-authored,user-confirmed,ai-proposed,copied-from-formula,counterexample,feedback,importedExpectation source; user-confirmed is a person’s act and is refused (422 trusted-record).
op:updateTestop"updateTest"requiredtestone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
changesobject requirednamestring 1 to 200 characterskindone ofscenario,propertyassignmentsmap of string to booleanInput values by input ID or name.
quantitiesmap of string to string or array of stringNumbers, levels, values, or sets by quantity ID or name.
expectedmap of string to booleanExpected values by formula ID or name.
expectedLabelsmap of string to stringExpected outcome label (ID or name) by outcome set (ID or name).
propertyone of the forms belowkindone ofsatisfiable,tautology,falsifiable,contradictionrequiredformulaIdstring required 1 to 300 characters
kind:equivalentkind"equivalent"requiredformulaIdstring required 1 to 300 charactersotherFormulaIdstring 1 to 300 charactersotherTextstring at most 20000 characters
kindone ofvalidity,premises-consistent,consistencyrequired
kindone ofrelevant,irrelevantrequiredformulaIdstring required 1 to 300 charactersvarIdstring required 1 to 300 characters
kind:at-least-as-strictkind"at-least-as-strict"requiredformulaIdstring required 1 to 300 charactersotherFormulaIdstring required 1 to 300 characters
kind:monotonekind"monotone"requiredformulaIdstring 1 to 300 characterssetIdstring 1 to 300 charactersvarIdstring 1 to 300 charactersquantityIdstring 1 to 300 charactersdirectionone ofnever-true-to-false,never-false-to-true,never-earlier,never-laterrequired
expectHoldsbooleannotesstring at most 10000 characterstagsarray of string at most 50 items; at most 100 characterssourceone ofuser-authored,user-confirmed,ai-proposed,copied-from-formula,counterexample,feedback,importedExpectation source; user-confirmed is a person’s act and is refused (422 trusted-record).
op:removeTestop"removeTest"requiredtestone of the forms below requiredAn object by its stable ID ({ "id" }) or by its name ({ "name" }).
idstring required 1 to 300 characters
namestring required 1 to 200 characters
op:replaceLogicop"replaceLogic"requiredlogicobject requiredA whole tangibool.logic/1 model.
schema"tangibool.logic/1"required
dryRunboolean defaultfalsedraftboolean defaultfalseidempotencyKeystring 1 to 200 characters; matches^[\x21-\x7e]+$
Any other field is refused.
200 response
Success.
dryRuntruerequiredcreatedarray of object requiredkindone ofvariable,quantity,formula,assumption,test,category,list,scalerequired open: more values may be added within v1namestring requiredidstring required
diagnosticsarray of object requiredformulaIdstring requirednamestring requiredstatusstring requireddiagnosticsarray required
validationobject requiredvalidboolean requiredissuesarray of object requiredseveritystring requiredmessagestring required
outlineobject requiredschema"tangibool.outline/1"requiredmodeone ofdecision,argumentrequiredinputsarray of object requiredidstring requirednamestring requireddefinitionstring or null required
formulasarray of object requiredidstring requirednamestring requiredroleone ofoutput,premise,conclusionrequiredtextstring required
testsobject requiredtotalnumber requiredconfirmednumber required
sourceobject requiredinterpretationone ofnot-needed,unconfirmed,confirmed,invalidatedrequired
diffany JSON value or null requiredbehaviourany JSON value or null required
201 response
Success.
headstring required matches^[0-9a-f]{64}$previousHeadstring or null required matches^[0-9a-f]{64}$commitobject requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdarray of objectkindone ofvariable,quantity,formula,assumption,test,category,list,scalerequired open: more values may be added within v1namestring requiredidstring required
diagnosticsarray of object requiredformulaIdstring requirednamestring requiredstatusstring requireddiagnosticsarray required
validationobject requiredvalidboolean requiredissuesarray of object requiredseveritystring requiredmessagestring required
dryRunfalserequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
name | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
expectedHeadstring or null required matches^[0-9a-f]{64}$messagestring at most 2000 characters; default""snapshotobject requiredartifactsmap of string to object requiredidstring required at most 300 characterskindstring required at most 40 characterscontentany JSON value required
draftboolean defaultfalseidempotencyKeystring 1 to 200 characters; matches^[\x21-\x7e]+$
Any other field is refused.
201 response
Success.
headstring required matches^[0-9a-f]{64}$previousHeadstring or null required matches^[0-9a-f]{64}$commitobject requiredidstring required matches^[0-9a-f]{64}$parentsarray of string required matches^[0-9a-f]{64}$manifeststring required matches^[0-9a-f]{64}$authorobject requiredidstringnamestring required
committerobject requiredidstringnamestring required
authoredAtstring requiredreceivedAtstring requiredISO 8601, UTC.
receivedBystring or null requiredauthorVerifiedboolean requiredimportedboolean requiredmessagestring requiredkindstring requiredstatestring requiredviaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdarray of objectkindone ofvariable,quantity,formula,assumption,test,category,list,scalerequired open: more values may be added within v1namestring requiredidstring required
diagnosticsarray of object requiredformulaIdstring requirednamestring requiredstatusstring requireddiagnosticsarray required
validationobject requiredvalidboolean requiredissuesarray of object requiredseveritystring requiredmessagestring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
namestring requiredfromstring or nulldescriptionstringidempotencyKeystring 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.
branchobject requirednamestring requiredheadstring or null required matches^[0-9a-f]{64}$protectedboolean 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
name | path | string | Yes |
200 response
Success.
deletedtruerequiredheadstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
namestring requiredtargetstring requiredkindone ofordinary,approved-baselinemessagestringidempotencyKeystring 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.
tagobject requirednamestring requiredtargetstring required matches^[0-9a-f]{64}$kindone ofordinary,approved-baselinerequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes |
Request body
sourcestring requiredtargetstring requiredresolutionsmap of string to one ofours,theirs,base,both
200 response
Success.
sourceHeadstring required matches^[0-9a-f]{64}$targetHeadstring or null required matches^[0-9a-f]{64}$fastForwardboolean requiredconflictsarray 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
targetBranchstring requiredsourceBranchstring requiredexpectedTargetHeadstring or null required matches^[0-9a-f]{64}$expectedSourceHeadstring required matches^[0-9a-f]{64}$resolutionsmap of string to one ofours,theirs,base,bothmergeRequestIdstringidempotencyKeystring 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.
mergeobject requiredheadstring required matches^[0-9a-f]{64}$fastForwardboolean 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
state | query | one of open, closed, merged, all | No | open by default. |
limit | query | integer 1 to 500 | No | Rows on a page, at most 500; 500 without it. |
cursor | query | string at most 1000 characters | No | The nextCursor of the previous page. Opaque. |
200 response
Success.
mergeRequestsarray of object requiredidstring requirednumbernumber requiredstatestring requiredsourceBranchstring requiredtargetBranchstring required
nextCursorstring or null requiredThe 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
titlestring requireddescriptionstringsourceBranchstring requiredtargetBranchstring requiredidempotencyKeystring 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.
mergeRequestobject requiredidstring requirednumbernumber requiredstatestring requiredsourceBranchstring requiredtargetBranchstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
mrId | path | string | Yes |
200 response
Success.
mergeRequestobject requiredidstring requirednumbernumber requiredstatestring requiredsourceBranchstring requiredtargetBranchstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
mrId | path | string | Yes |
200 response
Success.
mergeRequestobject requiredidstring requirednumbernumber requiredstatestring requiredsourceBranchstring requiredtargetBranchstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
mrId | path | string | Yes |
200 response
Success.
mergeRequestobject requiredidstring requirednumbernumber requiredstatestring requiredsourceBranchstring requiredtargetBranchstring 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
modelIdstringrevisionstringsnapshotany JSON valuequeryobject requiredkindstring required
crossCheckboolean
200 response
Success.
resultobject requiredTransport status is separate from the verdict: an exhausted budget is
unknownwith its reason, never an HTTP error.verdictone ofholds,violated,unknownrequired
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
textstring required at most 20000 characterscontextone of the forms belowtextobject requiredmodeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
logicobject requiredschema"tangibool.logic/1"required
languageone ofen,fr,de,es
Any other field is refused.
200 response
Success.
statusstring requireddiagnosticsarray requiredcanonicalTextstring 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
logicone of the forms below requiredtextobject requiredmodeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
logicobject requiredschema"tangibool.logic/1"required
assignmentmap of string to boolean requiredInput values by input ID or name.
languageone ofen,fr,de,es
Any other field is refused.
200 response
Success.
logicDigeststringengineVersionstringsemanticsVersionstringcompleteboolean requiredformulasmap 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
logicone of the forms below requiredtextobject requiredmodeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
logicobject requiredschema"tangibool.logic/1"required
queryobject requiredkindone ofconsistency,satisfiable,tautology,falsifiable,contradiction,equivalence,validity,premises-consistentrequiredformulastring 1 to 300 charactersThe formula, by ID or name.
otherFormulastring 1 to 300 charactersotherTextstring at most 20000 characters
Any other field is refused.
200 response
Success.
logicDigeststringengineVersionstringsemanticsVersionstringinputsarray of object requiredThe inputs by ID and name: cases name inputs by ID, and logic sent as text has no IDs of its own.
idstring requirednamestring required
resultobject requiredTransport status is separate from the verdict: an exhausted budget is
unknownwith its reason, never an HTTP error.verdictone ofholds,violated,unknownrequired
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
logicone of the forms below requiredtextobject requiredmodeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
logicobject requiredschema"tangibool.logic/1"required
astring required 1 to 300 charactersA formula by ID or name.
bstring required 1 to 300 characters
Any other field is refused.
200 response
Success.
logicDigeststringengineVersionstringsemanticsVersionstringinputsarray of object requiredThe inputs by ID and name: cases name inputs by ID, and logic sent as text has no IDs of its own.
idstring requirednamestring required
resultobject requiredrelationstring requiredaWithinBone ofholds,violated,unknownrequiredbWithinAone ofholds,violated,unknownrequired
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
logicone of the forms below requiredtextobject requiredmodeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
logicobject requiredschema"tangibool.logic/1"required
pageinteger 0 to 9007199254740991; default0pageSizeinteger 1 to 1024; default256
Any other field is refused.
200 response
Success.
logicDigeststringengineVersionstringsemanticsVersionstringrowCountnumber requiredpagesnumber requiredrowsarray of object requiredrownumber requiredinputsarray of boolean requiredvaluesarray 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
logicone of the forms below requiredtextobject requiredmodeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
logicobject requiredschema"tangibool.logic/1"required
formulastring required 1 to 300 charactersvaluebooleanassignmentmap of string to booleanInput values by input ID or name.
fixedarray of string at most 64 items; 1 to 300 characters
Any other field is refused.
200 response
Success.
logicDigeststringengineVersionstringsemanticsVersionstringnecessaryany JSON value requiredwaysToQualifyany 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
logicone of the forms below requiredtextobject requiredmodeone ofdecision,argumentcategoriesarray of object at most 64 itemsCategories with their values and lists (FR-26).
namestring required 1 to 200 charactersvaluesarray of one of the forms below required 1 to 2000 itemsIts values in order: names (identifiers), or names with display labels.
namestring required 1 to 200 characterslabelstring at most 200 characters
listsarray of object at most 500 itemsNamed lists of its values, which membership tests and formulas use (
plan IN Paid).namestring required 1 to 200 charactersvaluesarray of string required at most 2000 items; 1 to 200 charactersValues of the category, by name.
scalesarray of object at most 64 itemsOrdered scales with their levels (FR-27).
namestring required 1 to 200 characterslevelsarray of string required 1 to 100 items; 1 to 200 charactersLevel labels, from the lowest to the highest.
outsidearray of string at most 8 items; 1 to 200 charactersValues on no level, such as "Not rated": they meet no comparison.
quantitiesarray of object at most 64 itemsWhat inputs are defined on, and what formulas test by name (
plan IN Paid). A threshold on a quantity not listed here creates a number.namestring required 1 to 200 charactersdomainone ofinteger,decimal,category,set,scalerequiredA number, one value of a category, a set of its values, or a level of a scale.
categorystring 1 to 200 charactersFor
categoryandset: the category, by name.scalestring 1 to 200 charactersFor
scale: the scale, by name.
inputsarray of object at most 64 itemsnamestring required 1 to 200 charactersthresholdobjectA quantity compared with a number, or with a level of its scale (FR-25, FR-27).
quantitystring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredboundstring required at most 40 charactersA number; on a scale quantity, the label of a level.
domainone ofinteger,decimalWhen the threshold creates its quantity: whole numbers or decimals (by default, as the bound is written).
membershipobjectA membership test (FR-26):
plan IN Paid,country IN {DE, FR},activities HAS ANY Excluded.quantitystring required 1 to 200 charactersA category or set-valued quantity, by name.
testone ofin,any,all,noneinon a category quantity (the default there);any(the default there),all, ornoneon a set-valued one.valuesarray of string 1 to 2000 items; 1 to 200 charactersValues of the category, by name. Send these or
list.liststring 1 to 200 charactersA list of the category, by name. Send this or
values.
comparisonobjectTwo quantities on one scale compared, such as
product_risk <= client_risk(FR-27); an outside value on either side makes it FALSE.leftstring required 1 to 200 characterscomparatorone of<,<=,>,>=requiredrightstring required 1 to 200 characters
ratedobjectThe rated test of a scale quantity: TRUE when its value is a level rather than an outside value (FR-27).
quantitystring required 1 to 200 characters
formulasarray of object at most 64 itemsOutputs in decision mode; premises in argument mode.
namestring 1 to 200 characterstextstring required at most 20000 characters
conclusionstring at most 20000 charactersassumptionsarray of object at most 64 itemstextstring required at most 20000 charactersnamestring 1 to 200 charactersdescriptionstring at most 2000 characters
logicobject requiredschema"tangibool.logic/1"required
targetone ofpython,postgresql,smt-librequired
Any other field is refused.
200 response
Success.
logicDigeststringengineVersionstringsemanticsVersionstringtargetone ofpython,postgresql,smt-librequiredcodestring requiredprovenancestring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Prefer | header | string | No | wait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time. |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
modelIdstring requiredrevisionstring requiredA branch, a tag, or a commit ID.
optionsobjectThe options of a test-run job.
testIdsarray of string at most 1000 items; at most 200 charactersbudgetMsinteger 100 to 60000perQueryBudgetMsinteger 10 to 10000
idempotencyKeystring 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.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring or null required
202 response
Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Prefer | header | string | No | wait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time. |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
modelIdstring requiredrevisionstring requiredA branch, a tag, or a commit ID.
optionsobjectThe options of a coverage-run job.
includeExploratorybooleanbudgetMsinteger 100 to 60000perQueryBudgetMsinteger 10 to 10000
idempotencyKeystring 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.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring or null required
202 response
Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Prefer | header | string | No | wait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time. |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
modelIdstring requiredrevisionstring requiredA branch, a tag, or a commit ID.
optionsobjectThe options of a mutation-run job.
seedinteger 0 to 2147483647maxMutantsinteger 1 to 500operatorsarray of one ofand-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-order1 to 22 itemsindependentOnlybooleanbudgetMsinteger 100 to 30000perQueryBudgetMsinteger 10 to 10000
idempotencyKeystring 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.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring or null required
202 response
Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Prefer | header | string | No | wait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time. |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
modelIdstring requiredrevisionstring requiredA branch, a tag, or a commit ID.
optionsobject requiredThe options of a export job.
itemsarray of object required 1 to 500 itemstargetone ofmodel-report,source,glossary,formulas,explanation,truth-table,tests,test-report,diagram,formula-card,kmap,strictness-map,venn,mapping-diagram,notes,discussion,snapshotrequiredformatone ofmd,txt,py,json,sql,tex,smt2,png,jpg,jpeg,csv,svg,xmlrequiredoptionsobjectformulaIdstring at most 200 charactersnoteIdsarray of string at most 1000 items; at most 300 charactersrowsPerPageinteger 4 to 256intermediateColumnsbooleanfragmentbooleanincludeGetModelbooleanincludePropertyTestsbooleanruleIdsarray of string 2 to 12 items; at most 200 characterslistIdsarray of string 2 to 3 items; at most 200 charactersquantityIdstring at most 200 charactersmappingIdstring at most 200 characters
themeone oflight,darkdefault"light"scale1or2or4default2widthinteger 16 to 8192backgroundstring matches^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$jpegQualityinteger 1 to 100; default90transparentboolean defaultfalsecleanImageboolean defaultfalseasciiOperatorsboolean defaultfalsenotationone ofwords,programming,mathematical,algebralevelone ofbeginner,intermediate,advanceddefault"intermediate"archiveboolean defaulttrue
idempotencyKeystring 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.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring or null required
202 response
Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Prefer | header | string | No | wait=<seconds> (RFC 7240), at most 25: wait for the job and answer 200 with the finished operation when it ends in time. |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
modelIdstring requiredrevisionstring requiredA branch, a tag, or a commit ID.
optionsobjectThe options of a history-export job.
branchesarray of string 1 to 1000 items; 1 to 100 charactersitemsarray of object at most 50 items; default[]targetone ofhistory,history-summary,history-graph,visual-diffrequiredformatone ofmd,txt,py,json,sql,tex,smt2,png,jpg,jpeg,csv,svg,xmlrequiredoptionsobjecthistoryLimitinteger 1 to 100000compareCommitstring matches^[0-9a-f]{64}$rowsPerPageinteger 4 to 256fragmentboolean
themeone oflight,darkdefault"light"scale1or2or4default2widthinteger 16 to 8192backgroundstring matches^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$jpegQualityinteger 1 to 100; default90transparentboolean defaultfalsecleanImageboolean defaultfalseasciiOperatorsboolean defaultfalsenotationone ofwords,programming,mathematical,algebralevelone ofbeginner,intermediate,advanceddefault"intermediate"
idempotencyKeystring 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.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring or null required
202 response
Accepted: the job runs in the background. Read it at GET /v1/operations/{operationId}.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
200 response
Success.
operationobject requiredidstring requiredkindstring requiredstatusone ofqueued,running,succeeded,failed,cancelled,timed-outrequired open: more values may be added within v1modelIdstring requiredrequestedByobject or null requiredidstringnamestring required
viaobject or null requiredThe token, app, or assistant a program acted through; null for changes made in the app.
kindone oftoken,app,assistantrequiredidstring requirednamestring required
createdAtstring requiredISO 8601, UTC.
finishedAtstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
operationId | path | string | Yes |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
state | query | one of open, resolved, all | No | all by default. |
include | query | string | No | messages adds the messages and events of the threads on the page. |
limit | query | integer 1 to 1000 | No | Rows on a page, at most 1000; every thread without it. |
cursor | query | string at most 1000 characters | No | The nextCursor of the previous page. Opaque. |
200 response
Success.
threadsarray of object requiredidstring requiredtitlestring requiredstateone ofopen,resolvedrequired
nextCursorstring or null requiredThe 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
titlestringbodystring requiredanchorany JSON valuelabelstringidempotencyKeystring 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.
threadobject requiredidstring requiredtitlestring requiredstateone ofopen,resolvedrequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
threadId | path | string | Yes |
200 response
Success.
threadobject requiredidstring requiredtitlestring requiredstateone ofopen,resolvedrequired
Errors
- 401
unauthenticated- 403
insufficient-scope- 404
not-found- 429
rate-limited
POST /v1/threads/{threadId}/messages
Reply in a thread.
Scope: discussion
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
threadId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
bodystring requiredidempotencyKeystring 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.
messageobject requiredidstring requiredbodystring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
limit | query | integer 1 to 500 | No | Rows on a page, at most 500; every subscription without it. |
cursor | query | string at most 1000 characters | No | The nextCursor of the previous page. Opaque. |
200 response
Success.
webhooksarray of object requiredidstring requiredurlstring requiredeventsarray of string requiredpausedboolean required
nextCursorstring or null requiredThe 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
modelId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
urlstring requiredeventsarray of string requiredidempotencyKeystring 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.
webhookobject requiredidstring requiredurlstring requiredeventsarray of string requiredpausedboolean required
secretstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
teamId | path | string | Yes | |
limit | query | integer 1 to 500 | No | Rows on a page, at most 500; every subscription without it. |
cursor | query | string at most 1000 characters | No | The nextCursor of the previous page. Opaque. |
200 response
Success.
webhooksarray of object requiredidstring requiredurlstring requiredeventsarray of string requiredpausedboolean required
nextCursorstring or null requiredThe 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
teamId | path | string | Yes | |
Idempotency-Key | header | string 1 to 200 characters; matches ^[\x21-\x7e]+$ | No | Makes 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
urlstring requiredeventsarray of string requiredidempotencyKeystring 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.
webhookobject requiredidstring requiredurlstring requiredeventsarray of string requiredpausedboolean required
secretstring 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string | Yes |
200 response
Success.
deletedtruerequired
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
webhookId | path | string | Yes | |
limit | query | integer 1 to 500 | No | Rows on a page, at most 500; 200 without it. |
cursor | query | string at most 1000 characters | No | The nextCursor of the previous page. Opaque. |
200 response
Success.
deliveriesarray of object requiredidstring requiredeventstring requiredstatusstring required
nextCursorstring or null requiredThe 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