On this page
Tangibool public API
The public API lets programs work with Tangibool models for a person: scripts and continuous-integration jobs with a personal access token, and apps and AI assistants that the person connects through OAuth. It is version 1 of a documented contract. The routes the web app calls on app.tangibool.com/v1 are internal and change with the app; they are not part of this contract.
| What | Where |
|---|---|
| API for programs | https://api.tangibool.com/v1 |
| MCP server for AI assistants | https://api.tangibool.com/mcp |
| This guide and the API reference (no token needed) | https://api.tangibool.com/docs and https://api.tangibool.com/docs/reference |
| OpenAPI 3.1 specification (no token needed) | GET https://api.tangibool.com/v1/openapi.json |
| OAuth authorization server | https://app.tangibool.com, metadata at /.well-known/oauth-authorization-server |
| TypeScript SDK | @tangibool/sdk on npm |
| Headless runner | @tangibool/cli on npm |
The API reference, generated from the specification, describes every route, request, and response; this guide explains how to use them. The examples use bash and curl, and any HTTP client works the same way. They read the API's address from TANGIBOOL_API_URL and your token from TANGIBOOL_TOKEN, as the headless runner does. Every example here runs against a real server in Tangibool's continuous integration.
1. Basics
One server, its own host. The API host is served by the same server as the app and runs the app's own services. Permissions, plan limits, tenant isolation, audit, and retention are the app's, and so are the results. The server tells the hosts apart by name: the API host ignores cookies, and the app host ignores bearer tokens (401, or 403 csrf-failed for a write).
Requests are JSON (Content-Type: application/json). A body may have up to 1 MiB; up to 30 MiB for POST /v1/models, change sets, whole snapshots, and merge previews; up to 8 MiB for analyses (POST /v1/analyses and POST /v1/logic/…). Over the limit: 413 payload-too-large.
IDs and times. Models, teams, threads, operations, and webhooks have UUIDs. Commits and other stored objects have 64-character hex content IDs. Inputs, formulas, assumptions, and tests have the engine's stable IDs, which stay the same when they are renamed; change-set edits and analyses of logic sent with a request also accept names. Times are ISO 8601, in UTC.
Revisions. Where a route takes a revision, give a branch, a tag, or a commit ID.
Request IDs. Every response carries X-Request-Id. Quote it when you report a problem.
Browsers. The API host answers CORS requests from any origin, without credentials, and lets pages read RateLimit, RateLimit-Policy, Retry-After, X-Request-Id, Location, and WWW-Authenticate. A page still needs a token like any other program. Keep personal access tokens in a secret store or a CI secret, never in code.
2. Authentication
Every request to /v1 needs Authorization: Bearer <token>, with a personal access token or an OAuth access token, except GET /v1/openapi.json and POST /v1/secret-scanning/reports. Without a token the answer is 401 unauthenticated with:
WWW-Authenticate: Bearer realm="tangibool", resource_metadata="https://api.tangibool.com/.well-known/oauth-protected-resource"
An unknown, expired, or revoked token gets the same answer with error="invalid_token".
2.1 Personal access tokens
For your own scripts, CI jobs, and developer tools.
- Made in the app. Create, list, and revoke tokens in the app, in a signed-in session (account settings, Personal access tokens). The API cannot manage tokens:
/v1/me/tokenson the API host answers403 session-required. - Shown once. A token looks like
tb_pat_followed by 49 letters and digits (the last six are a checksum). Tangibool stores only its SHA-256 and lists it by its first characters (tb_pat_and four more). - Scopes and limits. Give each token only the scopes its program needs (section 3), and optionally limit it to named teams (up to 50) or models (up to 200). The
analysesscope sends logic to the server, so the app asks for your consent to server analysis when you give it. - Expiry. Every token expires: after 90 days by default, at most after 365. You are emailed when a token is created and a week before it expires. An expired token stays listed as expired for 30 days, then disappears. A user has at most 50 active tokens (
409 too-many-tokens). - Revocation takes effect on the token's next request, on every server. Resetting your password, an administrator disabling your account, and deleting your account revoke all your tokens. Changing your password does not.
- Leaks. Secret scanners recognise the
tb_pat_format. A leaked token reported toPOST /v1/secret-scanning/reports(the format of GitHub's secret-scanning partner program; no token needed) is revoked at once, and its owner is emailed with the place it was found. The answer says onlytrue_positiveorfalse_positivefor each reported token.
2.2 OAuth for apps and assistants
Apps and AI assistants connect through OAuth 2.1, so the person never copies a token.
| Endpoint | URL |
|---|---|
| Authorization server metadata (RFC 8414) | https://app.tangibool.com/.well-known/oauth-authorization-server |
| Authorization | https://app.tangibool.com/oauth/authorize |
| Token | https://app.tangibool.com/oauth/token |
| Dynamic client registration | https://app.tangibool.com/oauth/register |
| Revocation | https://app.tangibool.com/oauth/revoke |
| Protected-resource metadata (RFC 9728) | https://api.tangibool.com/.well-known/oauth-protected-resource (the API; also …/oauth-protected-resource/v1) and https://api.tangibool.com/.well-known/oauth-protected-resource/mcp (the MCP server) |
- Flow. Authorization code with PKCE (
S256) only; there is no implicit or password grant. The redirect URI must match a registered one exactly. Ask for the scopes of section 3 inscope. - Resource. Name the resource in the
resourceparameter (RFC 8707):https://api.tangibool.com/v1for the API (the default) orhttps://api.tangibool.com/mcpfor the MCP server. A token issued for one is refused by the other. - Clients. Identify your app with a client ID metadata document: the client ID is an https URL that serves JSON whose
client_idis that same URL, withredirect_uris(the first 10 are used) and optionallyclient_nameandclient_uri. Tangibool fetches it from a public address, without following redirects, within 5 seconds and 64 KiB, and keeps it for an hour. Such clients use PKCE with no client secret. Dynamic client registration is the fallback. - Consent. The person approves in the app, signed in. They see your app's name and redirect domain, whether Tangibool has reviewed it ("verified"; any other app is shown as unverified), the resource, and each scope you asked for. They may grant fewer scopes and limit the grant to teams or models. A declined request returns
access_deniedto your redirect URI. - Lifetimes. An authorization code lasts 60 seconds and works once. An access token lasts 1 hour (
expires_in: 3600). Refresh tokens rotate on every use: use the new one each time, because reusing an old one revokes the whole grant. A refresh token ends after 30 days unused, and at most a year after the person approved. - Connected apps. The person sees your app in account settings with its scopes and last use. Disconnecting it revokes every token of the grant at once; so do resetting the password, the account being disabled, and deleting the account.
2.3 Who is calling
GET /v1/me (no scope needed) returns the user (id, displayName, email, plan) and the program as client: its kind (token or app), id, name, scopes, the limits teamIds and modelIds, and, for a personal access token, expiresAt.
curl -sS --fail-with-body "$TANGIBOOL_API_URL/v1/me" -H "Authorization: Bearer $TANGIBOOL_TOKEN"
3. Scopes and what a program may do
Scopes
| Scope | Routes |
|---|---|
models:read | GET /v1/teams, GET /v1/teams/{teamId}, GET /v1/models, GET /v1/models/{modelId} (with ?view=outline, the outline of a revision), GET /v1/models/{modelId}/refs, GET /v1/models/{modelId}/commits, GET /v1/models/{modelId}/commits/{commitId}, GET /v1/models/{modelId}/snapshots/{commitId}, POST /v1/models/{modelId}/comparisons, POST /v1/models/{modelId}/merges/preview, GET /v1/models/{modelId}/merge-requests, GET /v1/models/{modelId}/merge-requests/{mrId} |
models:write | POST /v1/models, POST /v1/models/{modelId}/changes, PUT /v1/models/{modelId}/branches/{name}/snapshot, POST /v1/models/{modelId}/branches, DELETE /v1/models/{modelId}/branches/{name}, POST /v1/models/{modelId}/tags (ordinary tags), POST /v1/models/{modelId}/merges, POST /v1/models/{modelId}/merge-requests, POST /v1/models/{modelId}/merge-requests/{mrId}/close, POST /v1/models/{modelId}/merge-requests/{mrId}/reopen |
analyses | POST /v1/analyses; POST /v1/logic/parse, /evaluate, /check, /compare, /truth-table, /reasons, /code; POST /v1/test-runs, POST /v1/coverage-runs, POST /v1/mutation-runs, with GET and DELETE on /v1/test-runs/{operationId} and the like |
exports | POST /v1/exports, POST /v1/history-exports, with GET and DELETE on /v1/exports/{operationId} and /v1/history-exports/{operationId}, and GET /v1/exports/{operationId}/download, GET /v1/history-exports/{operationId}/download |
analyses or exports | GET /v1/operations/{operationId} and DELETE /v1/operations/{operationId}: the job's kind decides which |
discussion | GET /v1/models/{modelId}/threads, POST /v1/models/{modelId}/threads, GET /v1/threads/{threadId}, POST /v1/threads/{threadId}/messages. Private notes are not available |
webhooks | GET /v1/models/{modelId}/webhooks, POST /v1/models/{modelId}/webhooks, GET /v1/teams/{teamId}/webhooks, POST /v1/teams/{teamId}/webhooks, DELETE /v1/webhooks/{webhookId}, GET /v1/webhooks/{webhookId}/deliveries |
A request succeeds only when the route is one of these, the program holds its scope (403 insufficient-scope, with details.required), and the person's role on the model allows the action (403 forbidden). A scope never adds to the role: a viewer's token cannot write, whatever its scopes. Any other path under /v1 on the API host answers 404, except the actions that stay in the app (403, below).
Limits. A token or app limited to named teams or models sees nothing else. Other models and teams answer 404, exactly as models the person cannot read do, and lists leave them out.
What stays in the app
Some actions are never available to a program, whatever its scopes and the person's role, the owner included:
- Session-only actions answer
403 session-required: signing in, passwords, sessions, tokens, connected apps, account export and deletion, billing, team and model membership, invitations, snapshot links, ownership transfer, model and team deletion, branch protection, model settings, the audit log, and every administrator route. - Acts that stay with a person answer
403 person-required: approving a merge request (or withdrawing an approval) and creating an approved-baseline tag. - Trusted records. Confirming the interpretation and confirming a test's expected result are a person's acts in the app. A program's write may keep the interpretation confirmation, test confirmations, AI draft and review records, and evidence receipts byte for byte, or remove them, but never create or change them: such a write is refused with
422 trusted-record(details.recordsnames each one) and changes nothing. - Tests a program adds carry the expectation source the client gives:
user-authoredby default (the person's own expectation), neveruser-confirmed. Updating a test drops any person's confirmation of it. Tests added through the MCP server are alwaysai-proposedand unconfirmed.
A logic change still invalidates an existing confirmation through its digests, so after a program changes the logic, the person confirms the interpretation again in the app.
Provenance. Every commit, job, webhook subscription, and audit event a program makes records via: { "kind": "token" | "app" | "assistant", "id", "name" }. The author of a revision is the person the program acts for.
4. Conventions
Errors
Every error has the same body:
{ "error": { "code": "head-mismatch", "message": "main has moved since your last sync. …", "details": { "branch": "main", "currentHead": "…", "expectedHead": "…" } } }
The code is stable and part of the contract; the message is for people, in English, and may change. The API reference lists what each route answers. The codes a program meets most:
| Status | Codes |
|---|---|
| 400 | invalid-json |
| 415 | unsupported-media-type: send the body as application/json |
| 401 | unauthenticated |
| 402 | plan-limit: the plan of the account the model counts toward has no room (cloud models, storage, server jobs at once). Do not retry it automatically |
| 403 | insufficient-scope, session-required, person-required, forbidden (the role does not allow it), branch-protected, approval-required, consent-required |
| 404 | not-found: missing, not visible to the person, outside the token's limit, or not part of the public API. Inside a model you can read, a branch, revision, commit, or merge request that does not exist is branch-not-found, revision-not-found, commit-not-found, or merge-request-not-found |
| 409 | head-mismatch, request-in-progress, tag-exists, too-many-webhooks |
| 413 | payload-too-large |
| 422 | invalid-request (details.issues: [{ path, message }]), invalid-change, invalid-logic, invalid-model, trusted-record, unknown-formula, unknown-input, unresolved-conflicts, invalid-webhook-url, idempotency-key-reused, idempotency-key-mismatch, not-ready, compute-limit |
| 429 | rate-limited, compute-quota, with Retry-After; too-many-operations (too many of your jobs are queued or running: wait for one to end) |
| 503 | compute-busy, jobs-busy, with Retry-After |
A check's verdict is never an HTTP error: holds, violated, and unknown all come with 200. An unknown verdict (shown in the app as "Not determined") says why, for example an exhausted budget.
Rate limits and quotas
Limits count per user, across all of the user's tokens and apps, so more tokens never mean more capacity. The plan is the user's own, or Team when one of their teams has the Team plan.
| Plan | Requests per minute | Analyses of logic sent with a request, per minute | Server compute per day (analyses and jobs) |
|---|---|---|---|
| Free | 60 | 10 | 5 minutes |
| Basic | 120 | 30 | 30 minutes |
| Pro | 300 | 60 | 2 hours |
| Team | 600 | 120 | 2 hours per editor seat, pooled |
- Responses carry
RateLimit-Policy: "requests";q=<limit>;w=60andRateLimit: "requests";r=<requests left>;t=<seconds>. Over the limit:429 rate-limitedwithRetry-Afteranddetails.retryAfterSeconds. - Some routes also have their own budget per user:
POST /v1/models60 an hour, starting a job 30 a minute,POST /v1/analyses60 a minute, comparisons and merge previews 30 a minute. Over one of them the answer is429 rate-limitedtoo. - Server compute counts toward the account the model counts toward (its owner's, or its team's), and toward the user's own account for logic sent with a request, by that account's own plan: the Free row for a team without the Team plan, and for logic sent with a request the plan of the person (a team's Team plan does not count there). When the day's allowance is spent, programs get
429 compute-quotauntil midnight UTC. - The plan limits of the app still apply, for example server jobs at once (
402 plan-limit), and so do the engine's limits on model size. A change set holds at most 500 edits, and a truth-table page at most 1,024 rows.
Idempotency keys
Send Idempotency-Key: <key> (or idempotencyKey in the body; if both are sent they must agree) to make a create safe to retry. A key is 1 to 200 printable ASCII characters without spaces, and is kept per user (and per model, on a model's routes). The first successful response is stored and replayed for a retry of the same request, with Idempotent-Replayed: true; the same key with a different request is 422 idempotency-key-reused, and a retry while the first is still running is 409 request-in-progress. A failed attempt leaves no record, so retrying it runs it again. Keys are kept for 24 hours (for threads and messages, as long as the message exists).
These routes take a key: POST /v1/models, POST /v1/models/{modelId}/changes (not dry runs), PUT /v1/models/{modelId}/branches/{name}/snapshot, POST /v1/models/{modelId}/merges, the five job routes (POST /v1/test-runs, /v1/coverage-runs, /v1/mutation-runs, /v1/exports, /v1/history-exports), POST /v1/models/{modelId}/threads, POST /v1/threads/{threadId}/messages, POST /v1/models/{modelId}/branches, POST /v1/models/{modelId}/tags, POST /v1/models/{modelId}/merge-requests, and the two webhook routes. A replayed answer carries Idempotent-Replayed: true. A replayed webhook subscription repeats its signing secret, so the server keeps that answer, secret included, for the 24 hours.
Long work: operations and Prefer: wait
Test, coverage, and mutation runs and exports are jobs. Starting one answers 202 with an operation; read it at GET /v1/operations/{operationId} (or the route of its kind) until its status is no longer queued or running. It ends succeeded, failed, cancelled, or timed-out. DELETE cancels it. A run's result is bound to the revision it ran on (binding: the commit, the logic digest, and the engine version among them), and an export's to its model, commit, and revision.
To skip the polling for short jobs, send Prefer: wait=<seconds> (RFC 7240), at most 25 seconds. The server answers 200 with the finished operation when the job ends in time, and 202 otherwise; Preference-Applied: wait=<seconds> gives the wait it applied.
Lists
Every list takes limit and cursor and answers nextCursor, null on the last page (GET /v1/models/{modelId}/refs is not a list: it answers every branch and tag at once). Pass nextCursor back as cursor for the next page; a cursor is opaque, belongs to its list, and a foreign or altered one is 422 invalid-request. The order is stable: rows added or removed between pages do not move the boundary, and no update or rename moves a row past it.
- Models are listed newest first by creation, and teams oldest first by creation.
- Merge requests (
state:openby default,closed,merged, orall), threads, and webhook deliveries are listed newest first, and webhooks oldest first. - Commits follow the history from the head the first page started at, however the branch moves afterwards. They also keep
offset,total, andhasMore; sendoffsetorcursor, not both.
Without limit, a list answers as before: models, teams, threads, and webhooks in full, merge requests the newest 500, deliveries the newest 200, and commits 100.
Versions and compatibility
- The major version is in the path:
/v1. Withinv1, changes are additive only: new routes, new optional request fields, new response fields, new values of enumerations documented as open, and new error codes within documented families. Ignore fields you do not know. - The specification's
info.version(now1.0.0) names the release; the SDK's version follows it. Each release is compared with the last released specification, and a breaking change fails that check: a removed operation or response, a removed or retyped response field, a new value in a closed response enumeration, a newly required request field, a request value no longer accepted, or a newly required scope. - A breaking change needs
/v2. The previous version then keeps working for at least 12 months after its successor ships, announced withDeprecationandSunsetheaders and by email to the owners of tokens and apps that used it in the previous 90 days. There is nov2yet.
5. Walkthrough: building on Tangibool
A model kept as rule text in your repository, checked on every change in CI. The steps are one shell session: later steps use what earlier ones set.
1. Make a token. In the app, under account settings, Personal access tokens, create a token with models:read, models:write, and analyses (add exports for step 6, and webhooks for section 7), limited to your team. Keep it as a CI secret.
export TANGIBOOL_API_URL=https://api.tangibool.com
export TANGIBOOL_TOKEN='tb_pat_…'
The API answers JSON. This helper prints one field of it (field a.b.0), using Python's standard library; jq does the same if you have it.
field() {
python3 -c 'import json, sys
value = json.load(sys.stdin)
for key in sys.argv[1].split("."):
value = value[int(key)] if key.isdigit() else value[key]
sys.stdout.write(str(value))' "$1"
}
2. Create a model from rule text. POST /v1/models takes a title, a teamId (a token limited to teams must name one of them; a personal model is refused with 403 forbidden), mode (decision by default, or argument), contentLanguage, categories (with their values and lists), scales (with their levels), quantities, inputs (plain, or defined by a threshold, a membership test, a comparison on a scale, or a rated test), formulas as text (outputs, or premises with a conclusion in argument mode), sourceText, glossary meanings, assumptions as text, and tests. The server parses everything with the engine and creates the model and its first revision on main.
TEAM=$(curl -sS --fail-with-body "$TANGIBOOL_API_URL/v1/teams" -H "Authorization: Bearer $TANGIBOOL_TOKEN" | field teams.0.id)
created=$(curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/models" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: create-entry-rule" \
-d '{
"title": "Entry rule",
"teamId": "'"$TEAM"'",
"inputs": [
{ "name": "member" },
{ "name": "banned" },
{ "name": "adult", "threshold": { "quantity": "age", "comparator": ">=", "bound": "18" } }
],
"formulas": [{ "name": "allow", "text": "adult AND member AND NOT banned" }],
"sourceText": "Adult members may enter unless they are banned.",
"tests": [
{ "name": "banned adult member", "assignments": { "member": true, "banned": true }, "quantities": { "age": "30" }, "expected": { "allow": false } }
]
}')
MODEL=$(field model.id <<< "$created")
HEAD=$(field refs.branches.main.head <<< "$created")
The 201 answer has the model (model.id), its refs (refs.branches.main.head is the first commit), created (the ID the server gave each new input, quantity, formula, and test), and the diagnostics and validation of the result. A formula that does not parse is refused (422 invalid-logic, with its diagnostics) unless you send "draft": true to store a draft revision. Points tables and outcome sets have no plain form here: add them afterwards with a replaceLogic edit.
To read a revision back compactly, use the outline: GET /v1/models/{modelId}?view=outline&rev=main gives the inputs with their definitions, the formulas as text, the assumptions, the outcome sets, the glossary, the source text with its interpretation state, and a summary of the tests, each with its stable ID.
3. Preview a change. POST /v1/models/{modelId}/changes takes the branch, the expectedHead (the commit the branch must still be at; null for an empty branch), a message, and an ordered list of edits. With "dryRun": true it stores nothing and answers 200 with the IDs it would create, the diagnostics, the validation, the logic digest, the resulting outline, the structure differences (diff), and the behaviour comparison with the head (behaviour). This change lets invited guests in, so the saved test also says whether its case is invited: a test that gives no value for an input its formula uses cannot be decided, and the run in step 5 would report it.
curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/models/$MODEL/changes" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-d '{
"branch": "main",
"expectedHead": "'"$HEAD"'",
"dryRun": true,
"edits": [
{ "op": "setFormulaText", "formula": { "name": "allow" }, "text": "adult AND (member OR invited) AND NOT banned" },
{ "op": "updateTest", "test": { "name": "banned adult member" }, "changes": { "assignments": { "member": true, "banned": true, "invited": false } } }
]
}'
The edits, applied in order with the engine's own edit functions; all apply, or none:
| Edit | Fields | Effect |
|---|---|---|
setFormulaText | formula, text | Replaces a formula's text; a new name in it becomes an input |
addFormula | text, name? | Adds an output (decision mode) or a premise (argument mode) |
renameFormula, removeFormula | formula, (name) | Renaming keeps the formula's ID |
addVariable | name | Adds an input |
renameVariable | variable, name | Keeps the input's ID, so saved tests still match it |
removeVariable | variable, replaceWith? | An input a formula still uses needs replaceWith: true, false, or another input |
setThreshold | variable, quantity, comparator (<, <=, >, >=), bound, domain? (integer, decimal); or clear: true | Defines (or clears) a threshold input; a quantity that does not exist yet is created |
setSourceText | text, language? | The source rule text |
setGlossaryMeaning | target, meaning, language? | The meaning of an input or formula |
addAssumption, removeAssumption | text, name?, description?; assumption | Stated assumptions, written as formulas |
addTest, updateTest, removeTest | test; test, changes; test | Saved tests (section 3 for their sources) |
replaceLogic | logic (tangibool.logic/1) | The whole logic, validated as an imported model is, for what the other edits do not name |
formula, variable, assumption, test, and target are { "id": … } or { "name": … }. A name is resolved against the model as the earlier edits left it; an unknown or ambiguous name fails the change set with 422 invalid-change, whose details.edit gives the edit's position (from 0) and operation. A test gives assignments (input to true or false), quantities (quantity to a number as a string, or a level, value, or list of values), expected (formula to true or false), and optionally kind, expectedLabels, property, expectHolds, notes, tags, and source, with every key an ID or a name.
4. Commit it. Send the same request without dryRun, with a message and an idempotency key. The server builds the revision with the engine, validates it, applies branch protection and the plan limits, and moves the branch only if it is still at expectedHead.
curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/models/$MODEL/changes" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: invited-guests-1" \
-d '{
"branch": "main",
"expectedHead": "'"$HEAD"'",
"message": "Invited guests may enter",
"edits": [
{ "op": "setFormulaText", "formula": { "name": "allow" }, "text": "adult AND (member OR invited) AND NOT banned" },
{ "op": "updateTest", "test": { "name": "banned adult member" }, "changes": { "assignments": { "member": true, "banned": true, "invited": false } } }
]
}'
The 201 answer has the new head, the previousHead, the commit, and created. If the branch has moved, the answer is 409 head-mismatch with details.currentHead, and nothing changes: read the new head, check the change again, and resend. A branch that requires review refuses direct changes (403 branch-protected): write to another branch and open a merge request, which a person approves in the app. A branch that requires checks runs them first. For clients that keep native packages, PUT /v1/models/{modelId}/branches/{name}/snapshot takes a whole snapshot with expectedHead instead; the server builds and checks the revision the same way.
To merge a branch, preview with POST /v1/models/{modelId}/merges/preview, then call POST /v1/models/{modelId}/merges with both expected heads and a resolution for every conflict (422 unresolved-conflicts otherwise). When the branches have diverged, the server builds the merge commit. Into a branch that requires review, a merge goes only through a merge request with a current approval by a person (403 approval-required).
5. Run the saved tests in CI. Start a test run of a revision and wait for it. Its result has the exitCode (0 when every applicable test passed, 1 when a test failed, 2 for invalid input or an inconclusive run), the report, and junitXml. The last line fails the CI job unless the code is 0.
# finished OPERATION prints the operation once its job has ended.
finished() {
local op=$1
while [ "$(field operation.status <<< "$op")" = queued ] || [ "$(field operation.status <<< "$op")" = running ]; do
sleep 2
op=$(curl -sS --fail-with-body "$TANGIBOOL_API_URL/v1/operations/$(field operation.id <<< "$op")" -H "Authorization: Bearer $TANGIBOOL_TOKEN")
done
printf '%s' "$op"
}
op=$(curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/test-runs" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-H "Prefer: wait=25" \
-d '{ "modelId": "'"$MODEL"'", "revision": "main" }')
op=$(finished "$op")
field operation.result.junitXml <<< "$op" > tangibool.xml
test "$(field operation.result.exitCode <<< "$op")" = 0
Or install the headless runner and let it read the cloud revision with the same token: it runs the tests on the CI machine with the same engine, writes JUnit XML, and exits with the same codes.
npm install --global @tangibool/cli
tangibool test --model "$MODEL" --junit reports/tangibool.xml
6. Export a tagged revision. Tag the revision, start an export of the tag, and download the package. This needs the exports scope, and the role that may export in the app.
curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/models/$MODEL/tags" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-d '{ "name": "v1", "target": "main" }'
op=$(curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/exports" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-H "Prefer: wait=25" \
-d '{ "modelId": "'"$MODEL"'", "revision": "v1", "options": { "items": [{ "target": "formulas", "format": "py" }] } }')
op=$(finished "$op")
curl -sS --fail-with-body -o entry-rule-v1.zip "$TANGIBOOL_API_URL/v1/exports/$(field operation.id <<< "$op")/download" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN"
Each item of options.items is a target and a format, as in the app's export dialog; the reference lists them. The pictures (strictness-map, venn, mapping-diagram) name what they draw in the item's options (ruleIds, listIds, quantityId, mappingId), or draw their defaults without them. A download before the export has succeeded is 422 not-ready. POST /v1/history-exports makes a full-history package in the same way; it needs the right to export history.
7. See and stop it. Every commit the token made records via with the token's name, and so do jobs and audit events; History in the app shows it too. Revoking the token in the app stops it on its next request.
curl -sS --fail-with-body "$TANGIBOOL_API_URL/v1/models/$MODEL/commits?branch=main&limit=1" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" | field commits.0.via.name
The same journey from a Python script
Any language works: the server does the parsing, building, and checking. This script uses only Python's standard library. It creates a model from formulas written as text, previews a change with a dry run that stores nothing, commits it, and prints what it did. It reads the same two variables, and works with a token limited to a team or with one that is not.
import json
import os
import urllib.error
import urllib.request
import uuid
API = os.environ.get("TANGIBOOL_API_URL", "https://api.tangibool.com")
TOKEN = os.environ["TANGIBOOL_TOKEN"]
def call(method, path, body=None, idempotency_key=None):
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
if idempotency_key:
headers["Idempotency-Key"] = idempotency_key
data = None if body is None else json.dumps(body).encode()
request = urllib.request.Request(API + path, data=data, headers=headers, method=method)
try:
with urllib.request.urlopen(request) as response:
return json.load(response)
except urllib.error.HTTPError as error:
raise SystemExit(f"{method} {path} answered {error.code}: {error.read().decode()}")
teams = call("GET", "/v1/teams")["teams"]
# Create the model from formulas written as text. The server parses them with the engine.
created = call(
"POST",
"/v1/models",
{
"title": "Entry rule from Python",
"teamId": teams[0]["id"] if teams else None,
"inputs": [{"name": "member"}, {"name": "banned"}],
"formulas": [{"name": "allow", "text": "member AND NOT banned"}],
"tests": [{"name": "banned member stays out", "assignments": {"member": True, "banned": True}, "expected": {"allow": False}}],
},
idempotency_key=str(uuid.uuid4()),
)
model = created["model"]["id"]
first_head = created["refs"]["branches"]["main"]["head"]
edits = [
{"op": "setFormulaText", "formula": {"name": "allow"}, "text": "(member OR invited) AND NOT banned"},
{"op": "updateTest", "test": {"name": "banned member stays out"}, "changes": {"assignments": {"member": True, "banned": True, "invited": False}}},
]
# Preview the change. A dry run stores nothing, so the branch stays where it was.
preview = call(
"POST",
f"/v1/models/{model}/changes",
{"branch": "main", "expectedHead": first_head, "edits": edits, "dryRun": True},
)
head_after_preview = call("GET", f"/v1/models/{model}/refs")["branches"]["main"]["head"]
# Commit the change. The branch moves only if it is still at expectedHead.
committed = call(
"POST",
f"/v1/models/{model}/changes",
{"branch": "main", "expectedHead": first_head, "edits": edits, "message": "Invited guests may enter"},
idempotency_key=str(uuid.uuid4()),
)
print(json.dumps({
"model": model,
"first_head": first_head,
"preview_stored_nothing": head_after_preview == first_head,
"new_inputs": [item["name"] for item in preview["created"]],
"head": committed["head"],
}))
6. Analyses of logic sent with a request
These routes analyse logic you send, without creating a model. The server analyses it in memory and never stores or logs it; only the compute time is metered.
| Route | Request | Answer |
|---|---|---|
POST /v1/logic/parse | text, optional context (logic whose names it may use), language | status, diagnostics with positions and the engine's repairs, canonicalText, the literal reading, and the inputs it names |
POST /v1/logic/evaluate | logic, assignment (input to true or false), language | Each formula's value, complete, missing inputs, and the evaluation trace |
POST /v1/logic/check | logic, query: kind (consistency, satisfiable, tautology, falsifiable, contradiction, equivalence, validity, premises-consistent), formula, otherFormula, otherText | The result: its verdict, and a replayed case where there is one |
POST /v1/logic/compare | logic, formulas a and b | result.relation (equivalent, at-least-as-strict, looser, incomparable, or unknown), the verdicts aWithinB and bWithinA, and a replayed case for each direction that fails |
POST /v1/logic/truth-table | logic, page (from 0), pageSize (1 to 1,024, default 256) | One page of rows in the engine's order (row 0 all FALSE, the first input the most significant bit), with rowCount and pages |
POST /v1/logic/reasons | logic, formula, and optionally the value, a case (assignment), and the inputs a change may not touch (fixed) | The necessary conditions and the ways to qualify; for a case, an irreducible reason and the smallest changes |
POST /v1/logic/code | logic, target (python, postgresql, smt-lib) | The code, its file name, the identifier map, warnings, and its provenance |
- Logic is
{ "text": { "mode", "categories", "scales", "quantities", "inputs", "formulas", "conclusion", "assumptions" } }, written as inPOST /v1/models, or{ "logic": <a tangibool.logic/1 model> }. Formulas and inputs are named by ID or by name. The same text sent twice gets the same IDs, so its digest is the same too. - Results (all but
parse) are bound to thelogicDigestand theengineVersionandsemanticsVersionthey came from. Verdicts areholds,violated, orunknown, never a bare boolean; witnesses are replayed; an exhausted budget isunknownwith its reason and status200. Generated code states that it came from logic sent with a request, with no confirmed interpretation. - Consent. These routes need the
analysesscope and the person's consent to server analysis. Without the consent the answer is403 consent-requiredand nothing is analysed. - Limits. The per-minute limit of section 4 (in addition to the request limit), the 8 MiB body, and the engine's model limits. Server compute is metered toward the person's own account.
- Not a decision service. Evaluation is for analysis and testing. It is rate-limited and is not meant for deciding live cases.
POST /v1/analyses runs one exact check on a stored revision (modelId, revision, query), metered toward the model's account.
For example, is a AND b satisfiable? The answer has the verdict, a replayed case, and the digest and engine versions it is bound to.
curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/logic/check" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-d '{
"logic": { "text": { "inputs": [{ "name": "a" }, { "name": "b" }], "formulas": [{ "name": "both", "text": "a AND b" }] } },
"query": { "kind": "satisfiable", "formula": "both" }
}'
7. Webhooks
A webhook calls an HTTPS endpoint you own when something happens in a model.
Subscribe. A model admin or owner (for a model) or a team admin or owner (for a team) subscribes, in the app or with a token holding webhooks ($MODEL is the model of section 5):
curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/models/$MODEL/webhooks" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-d '{ "url": "https://ci.example.com/tangibool", "events": ["branch.updated", "operation.finished"] }'
The 201 answer has the webhook and its signing secret (whsec_…), shown only this once. The URL must use https, without a user name, password, or fragment, and must not be a private or reserved address or a local or internal name (422 invalid-webhook-url). A model has at most 10 subscriptions and a team 25 (409 too-many-webhooks). GET lists them, DELETE /v1/webhooks/{webhookId} removes one, and GET /v1/webhooks/{webhookId}/deliveries shows the deliveries of the last 7 days, newest first (200 a page without limit), with their status, attempts, and last HTTP status or error.
Events.
| Event | When | data |
|---|---|---|
branch.updated | A branch moves: a push, merge, fast-forward, restore, checkpoint promotion, change set, or whole snapshot | branch, from, to (commit IDs), reason |
tag.created | A tag is created | tag, target, kind |
merge_request.opened | A merge request is opened | mergeRequestId, number, sourceBranch, targetBranch |
merge_request.merged | A merge request is merged | the same, with commit and fastForward |
merge_request.closed | A merge request is closed | mergeRequestId, number, sourceBranch, targetBranch |
operation.finished | A test, coverage, or mutation run or an export ends | operationId, kind, status, and counts (the numbers of a successful run's summary) |
thread.created | A discussion thread is started | threadId, label, anchor (the kind of anchor) |
Payloads carry no model content: never formulas, source text, input names, comments, or notes. Read the details through the API with your own token.
{
"id": "1b5f0d4e-6f4b-4d55-9a53-6a3c2b1f0e77",
"type": "branch.updated",
"createdAt": "2026-11-04T10:00:00.000Z",
"modelId": "8d0c7a9e-2f1b-4c3d-8e5f-0a1b2c3d4e5f",
"teamId": null,
"data": { "branch": "main", "from": "…", "to": "…", "reason": "change-set" },
"links": { "api": "https://api.tangibool.com/v1/models/8d0c7a9e-2f1b-4c3d-8e5f-0a1b2c3d4e5f", "app": "https://app.tangibool.com/m/8d0c7a9e-2f1b-4c3d-8e5f-0a1b2c3d4e5f" }
}
Each delivery is a POST with Content-Type: application/json, User-Agent: Tangibool-Webhooks/1.0, Tangibool-Event, Tangibool-Event-Id (the payload's id), Tangibool-Delivery-Id, and Tangibool-Signature.
Verify the signature before acting on a delivery. The header is Tangibool-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>, computed with the whole secret as the key over <t>.<raw body>. Compute it over the body exactly as received, compare in constant time, and refuse old deliveries (the SDK allows 5 minutes). In Python:
import hashlib
import hmac
import time
def verify_tangibool_signature(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
t, signatures = None, []
for item in header.split(","):
key, _, value = item.strip().partition("=")
if key == "t":
t = value
elif key == "v1":
signatures.append(value)
if not t or not t.isdigit() or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, s) for s in signatures)
In TypeScript, use verifyWebhookSignature from the SDK (section 9).
Delivery.
- At least once: deduplicate on the event ID. One event has the same ID in every subscription it reaches; each delivery has its own delivery ID.
- Answer with any
2xxstatus. Anything else, a redirect, no answer within 10 seconds, or a network error is a failed attempt. Redirects are never followed. - Failed deliveries are retried after 1, 5, 15, and 30 minutes, then after 1, 2, and 4 hours, then every 6 hours, for at most 24 hours from the event; then the delivery is marked failed. A payload over 64 KiB is not sent.
- At every attempt the destination's name is resolved again, and every address must be public: private, loopback, link-local, cloud-metadata, and other reserved addresses (IPv6 forms of them included) are refused. The connection goes to the address that was checked.
- After 15 failed attempts in a row the subscription pauses, and its creator is emailed. It also pauses when its creator can no longer read the model (or, for a team subscription, has left the team); a team subscription's delivery about a model its creator cannot read, such as one deleted since, is dropped, and the subscription goes on. A paused subscription receives nothing more and is not resumed: fix the endpoint, delete the subscription, and subscribe again.
8. AI assistants: the MCP server
The MCP server lets an AI assistant use Tangibool for the person it works for: check and compare rules, explain results, read models, run saved tests, and propose changes that the person reviews. Tangibool's engine computes every result, the assistant proposes, and the person confirms meaning in the app. No tool calls an AI provider; the assistant's own model does the drafting.
Connecting an assistant
Add a remote MCP server with the URL https://api.tangibool.com/mcp. It speaks the Streamable HTTP transport and keeps no session, so any server can answer. It offers no stream of its own messages: a GET (and a DELETE) is answered 405 Method Not Allowed with Allow: POST, as the transport allows, so a client does not hold a stream open or keep reconnecting.
- With OAuth. A client that supports MCP authorization finds everything itself: the server's
401nameshttps://api.tangibool.com/.well-known/oauth-protected-resource/mcp, which names the authorization serverhttps://app.tangibool.com. The client registers (section 2.2) and sends you to the app, where you sign in and approve what it may read and do. The token it gets is for the resourcehttps://api.tangibool.com/mcp; a token for the API is refused here. - With a personal access token. A developer tool that lets you set headers can send
Authorization: Bearer tb_pat_….
Give the assistant only the scopes it needs: models:read to read models, analyses to analyse logic and run tests, and models:write to propose changes. Every MCP request (a POST), and every API call a tool makes, counts toward your per-minute request limit; a refused GET or DELETE does not.
Tools
| Tool | What it does | Calls | Scope |
|---|---|---|---|
parse_logic | Parses one formula (text): diagnostics with positions and repairs, the canonical text, the literal reading | POST /v1/logic/parse | analyses |
check_logic | Checks one property (property, formula, other_formula) of logic sent as text (logic): the verdict and a replayed case | POST /v1/logic/check | analyses |
compare_rules | Compares two rules (rule_a, rule_b, over inputs): equivalent, at least as strict, looser, incomparable, or unknown, with a replayed case for each direction that fails | POST /v1/logic/compare | analyses |
evaluate_case | The outputs and trace of one case | POST /v1/logic/evaluate | analyses |
truth_table | One page of rows (page, page_size up to 256, default 64) | POST /v1/logic/truth-table | analyses |
explain_case | Why a case got its result for a formula: necessary conditions, ways to qualify, an irreducible reason, the smallest changes | POST /v1/logic/reasons | analyses |
generate_code | Python, PostgreSQL, or SMT-LIB (target), stating that no interpretation was confirmed | POST /v1/logic/code | analyses |
list_models | The models you can read, with your role (at most 200, with the total) | GET /v1/models | models:read |
get_model | The outline of a revision (model_id, revision; the default branch by default), not the native snapshot | GET /v1/models/{modelId}?view=outline | models:read |
propose_change | A dry run of edits on a branch (the default branch by default): diagnostics, the resulting outline, the behaviour comparison. Stores nothing | POST /v1/models/{modelId}/changes with dryRun | models:read, models:write |
save_proposal | Commits edits on the proposal branch proposals/<name>, created from the branch base (the default branch by default) when it does not exist | POST /v1/models/{modelId}/branches, POST /v1/models/{modelId}/changes | models:read, models:write |
run_tests | Runs the saved tests of a revision and waits up to 25 seconds; otherwise returns the operation ID | POST /v1/test-runs with Prefer: wait | analyses (and models:read without revision) |
get_operation | Status and result of a job | GET /v1/operations/{operationId} | analyses |
Every tool but save_proposal and run_tests is marked read-only (readOnlyHint). The edits are those of section 5, and the logic is the text form of section 6.
Results have a short text summary and structured content that follows the tool's declared output schema; objects may carry more fields than the schema names. Verdicts keep holds, violated, and unknown. A result over 50,000 characters is cut, and truncated gives the full counts of what was cut. A refusal is a tool error (isError) whose text is the API's error code and message.
Proposals, not decisions
save_proposalwrites only toproposals/<name>(a name of letters, digits,.,_, and-), and its commit recordsviawith kindassistantand the name of the token or app.- Tests, assumptions, and glossary meanings it adds are
ai-proposedand unconfirmed. A proposed assumption is not applied to any check until you confirm it in the app. - No tool confirms, approves, merges, deletes, shares, or changes membership or protection. You review the proposal's text and behaviour differences in the app and merge it there (through a merge request where the target branch requires review), confirm the tests' expected results, and confirm the interpretation again.
Text people wrote. Titles, source text, names, glossary meanings, and comments come back inside structured result fields, and a refusal's text may quote a name. They are never in tool descriptions or the server's instructions, and the instructions tell the assistant to treat them as data, not as instructions. Tool descriptions never change with model content.
Example: is the internal rule at least as strict as the prospectus rule?
You connect your assistant and approve, in the app, what it may read and do. You ask the question in plain words, and the assistant calls the tools. The calls below are the ones it makes, written with curl so that you can see what it gets: an MCP tool call is one JSON-RPC request to /mcp.
# tool NAME ARGUMENTS calls one tool and prints the answer.
tool() {
curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/mcp" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "'"$1"'", "arguments": '"$2"' } }'
echo
}
# A model that holds the internal rule, for this example.
created=$(curl -sS --fail-with-body -X POST "$TANGIBOOL_API_URL/v1/models" \
-H "Authorization: Bearer $TANGIBOOL_TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "Bond eligibility",
"teamId": "'"$TEAM"'",
"inputs": [{ "name": "investment_grade" }, { "name": "on_watch" }],
"formulas": [{ "name": "eligible", "text": "investment_grade" }]
}')
BONDS=$(field model.id <<< "$created")
1. Ask. The assistant reads the rules with get_model, and asks the engine with compare_rules, passing the two formulas and their inputs. Here the internal rule is rule_a.
tool get_model '{ "model_id": "'"$BONDS"'" }'
tool compare_rules '{
"rule_a": "investment_grade",
"rule_b": "investment_grade AND NOT on_watch",
"inputs": [{ "name": "investment_grade" }, { "name": "on_watch" }]
}'
The answer: relation is looser, and aNotB is a replayed case the internal rule admits and the prospectus rule does not, a bond that is investment grade and on watch. Its assignment gives each input's value by ID, and inputs gives the name of each ID. To see the case for yourself, enter it in the model's Simulation tab in the app.
2. Fix. You ask for a fix. The assistant previews its edits with propose_change, which stores nothing, then saves them with boundary tests through save_proposal, on proposals/<name>. The tests are marked AI-proposed, and the commit records via with kind assistant.
edits='[
{ "op": "setFormulaText", "formula": { "name": "eligible" }, "text": "investment_grade AND NOT on_watch" },
{ "op": "addTest", "test": { "name": "investment grade, on watch", "assignments": { "investment_grade": true, "on_watch": true }, "expected": { "eligible": false } } },
{ "op": "addTest", "test": { "name": "investment grade, not on watch", "assignments": { "investment_grade": true, "on_watch": false }, "expected": { "eligible": true } } }
]'
tool propose_change '{ "model_id": "'"$BONDS"'", "edits": '"$edits"' }'
tool save_proposal '{ "model_id": "'"$BONDS"'", "name": "on-watch", "message": "Bonds on watch are not eligible", "edits": '"$edits"' }'
3. Decide. In the app you review the proposal's text and behaviour differences, merge it, confirm the tests' expected results, and confirm the interpretation again. The assistant never confirms, approves, or merges.
9. The TypeScript SDK
@tangibool/sdk is the official TypeScript client. Its types are generated from the specification, and its version is the specification's: a program that compiles against 1.x keeps working within v1. It runs wherever fetch and Web Crypto do: Node 20 or later, Deno, Bun, edge runtimes, and browsers.
npm install @tangibool/sdk
import { createTangiboolClient, unwrap, waitForOperation } from '@tangibool/sdk';
const tb = createTangiboolClient({ token: process.env.TANGIBOOL_TOKEN!, baseUrl: process.env.TANGIBOOL_API_URL });
const { models } = unwrap(await tb.GET('/v1/models'));
const started = unwrap(await tb.POST('/v1/test-runs', { params: { header: { Prefer: 'wait=25' } }, body: { modelId: models[0].id, revision: 'main' } }));
const run = ['queued', 'running'].includes(started.operation.status) ? await waitForOperation(tb, started.operation.id) : started.operation;
console.log(models[0].title, run.status);
createTangiboolClient({ token, baseUrl?, fetch?, headers? }).tokenmay be a function, called before every request, for an OAuth access token you refresh.baseUrldefaults tohttps://api.tangibool.com.- Every method takes the path as the specification writes it and answers
{ data, error, response }.unwrapreturns the data or throws aTangiboolApiErrorwithstatus, the stablecode,details,retryAfterSeconds, andrequestId. waitForOperation(client, operationId, { timeoutMs?, intervalMs?, signal? })reads a job until it ends, waiting out429answers; it gives up after 10 minutes by default (the job keeps running).verifyWebhookSignature({ body, signature, secret, toleranceSeconds?, now? })checks a delivery in constant time. It is asynchronous: await the event, which isnullwhen the signature does not match or the delivery is older thantoleranceSeconds(300 by default).
The SDK's README has more examples. For the command line and CI, the headless runner reads cloud models with a token too.