Tangibool for developers
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.

WhatWhere
API for programshttps://api.tangibool.com/v1
MCP server for AI assistantshttps://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 serverhttps://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.

2.2 OAuth for apps and assistants

Apps and AI assistants connect through OAuth 2.1, so the person never copies a token.

EndpointURL
Authorization server metadata (RFC 8414)https://app.tangibool.com/.well-known/oauth-authorization-server
Authorizationhttps://app.tangibool.com/oauth/authorize
Tokenhttps://app.tangibool.com/oauth/token
Dynamic client registrationhttps://app.tangibool.com/oauth/register
Revocationhttps://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)

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

ScopeRoutes
models:readGET /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:writePOST /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
analysesPOST /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
exportsPOST /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 exportsGET /v1/operations/{operationId} and DELETE /v1/operations/{operationId}: the job's kind decides which
discussionGET /v1/models/{modelId}/threads, POST /v1/models/{modelId}/threads, GET /v1/threads/{threadId}, POST /v1/threads/{threadId}/messages. Private notes are not available
webhooksGET /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:

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:

StatusCodes
400invalid-json
415unsupported-media-type: send the body as application/json
401unauthenticated
402plan-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
403insufficient-scope, session-required, person-required, forbidden (the role does not allow it), branch-protected, approval-required, consent-required
404not-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
409head-mismatch, request-in-progress, tag-exists, too-many-webhooks
413payload-too-large
422invalid-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
429rate-limited, compute-quota, with Retry-After; too-many-operations (too many of your jobs are queued or running: wait for one to end)
503compute-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.

PlanRequests per minuteAnalyses of logic sent with a request, per minuteServer compute per day (analyses and jobs)
Free60105 minutes
Basic1203030 minutes
Pro300602 hours
Team6001202 hours per editor seat, pooled

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.

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

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:

EditFieldsEffect
setFormulaTextformula, textReplaces a formula's text; a new name in it becomes an input
addFormulatext, name?Adds an output (decision mode) or a premise (argument mode)
renameFormula, removeFormulaformula, (name)Renaming keeps the formula's ID
addVariablenameAdds an input
renameVariablevariable, nameKeeps the input's ID, so saved tests still match it
removeVariablevariable, replaceWith?An input a formula still uses needs replaceWith: true, false, or another input
setThresholdvariable, quantity, comparator (<, <=, >, >=), bound, domain? (integer, decimal); or clear: trueDefines (or clears) a threshold input; a quantity that does not exist yet is created
setSourceTexttext, language?The source rule text
setGlossaryMeaningtarget, meaning, language?The meaning of an input or formula
addAssumption, removeAssumptiontext, name?, description?; assumptionStated assumptions, written as formulas
addTest, updateTest, removeTesttest; test, changes; testSaved tests (section 3 for their sources)
replaceLogiclogic (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.

RouteRequestAnswer
POST /v1/logic/parsetext, optional context (logic whose names it may use), languagestatus, diagnostics with positions and the engine's repairs, canonicalText, the literal reading, and the inputs it names
POST /v1/logic/evaluatelogic, assignment (input to true or false), languageEach formula's value, complete, missing inputs, and the evaluation trace
POST /v1/logic/checklogic, query: kind (consistency, satisfiable, tautology, falsifiable, contradiction, equivalence, validity, premises-consistent), formula, otherFormula, otherTextThe result: its verdict, and a replayed case where there is one
POST /v1/logic/comparelogic, formulas a and bresult.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-tablelogic, 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/reasonslogic, 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/codelogic, target (python, postgresql, smt-lib)The code, its file name, the identifier map, warnings, and its provenance

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.

EventWhendata
branch.updatedA branch moves: a push, merge, fast-forward, restore, checkpoint promotion, change set, or whole snapshotbranch, from, to (commit IDs), reason
tag.createdA tag is createdtag, target, kind
merge_request.openedA merge request is openedmergeRequestId, number, sourceBranch, targetBranch
merge_request.mergedA merge request is mergedthe same, with commit and fastForward
merge_request.closedA merge request is closedmergeRequestId, number, sourceBranch, targetBranch
operation.finishedA test, coverage, or mutation run or an export endsoperationId, kind, status, and counts (the numbers of a successful run's summary)
thread.createdA discussion thread is startedthreadId, 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.

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.

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

ToolWhat it doesCallsScope
parse_logicParses one formula (text): diagnostics with positions and repairs, the canonical text, the literal readingPOST /v1/logic/parseanalyses
check_logicChecks one property (property, formula, other_formula) of logic sent as text (logic): the verdict and a replayed casePOST /v1/logic/checkanalyses
compare_rulesCompares 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 failsPOST /v1/logic/compareanalyses
evaluate_caseThe outputs and trace of one casePOST /v1/logic/evaluateanalyses
truth_tableOne page of rows (page, page_size up to 256, default 64)POST /v1/logic/truth-tableanalyses
explain_caseWhy a case got its result for a formula: necessary conditions, ways to qualify, an irreducible reason, the smallest changesPOST /v1/logic/reasonsanalyses
generate_codePython, PostgreSQL, or SMT-LIB (target), stating that no interpretation was confirmedPOST /v1/logic/codeanalyses
list_modelsThe models you can read, with your role (at most 200, with the total)GET /v1/modelsmodels:read
get_modelThe outline of a revision (model_id, revision; the default branch by default), not the native snapshotGET /v1/models/{modelId}?view=outlinemodels:read
propose_changeA dry run of edits on a branch (the default branch by default): diagnostics, the resulting outline, the behaviour comparison. Stores nothingPOST /v1/models/{modelId}/changes with dryRunmodels:read, models:write
save_proposalCommits edits on the proposal branch proposals/<name>, created from the branch base (the default branch by default) when it does not existPOST /v1/models/{modelId}/branches, POST /v1/models/{modelId}/changesmodels:read, models:write
run_testsRuns the saved tests of a revision and waits up to 25 seconds; otherwise returns the operation IDPOST /v1/test-runs with Prefer: waitanalyses (and models:read without revision)
get_operationStatus and result of a jobGET /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

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);

The SDK's README has more examples. For the command line and CI, the headless runner reads cloud models with a token too.