RabbinatixDocs
Sign inGet started

Manage your organization

API and tokens

Create API tokens for CI and scripts, choose their scopes, and call the REST API at /api/v1.

Open Integrations → API tokens in the app

What the API is for

The Rabbinatix REST API lets your CI pipeline and scripts read your systems and contracts, ask whether a version may be deployed, and record deployments. Every call sends an API token. CI and the API shows the pipeline steps, and Integrations → API & CI has them ready to copy.

AI assistants don't use API tokens. They have keys of their own, and those keys don't work on this API (see Your AI assistant).

Create a token

You need the Integrations permission. Owners and Admins have it.

  1. Open Integrations in the sidebar and go to API tokens.
  2. Click New token.
  3. Give it a name that says where it's used, such as GitHub Actions. Each token of a project needs its own name.
  4. Tick one or more scopes. Pick only what the pipeline needs.
  5. Click Create token.
  6. Copy the token with the copy button, then click Done.
WarningThe token is shown once. Rabbinatix keeps only a hash of it, so nobody can show it to you again. If you lose it, revoke it and create a new one.

Tokens start with cm_live_. Keep them in your CI's secret store, never in code.

Scopes

ScopeLets the token
readList systems and contracts, and run the safety check
deployRecord a deployment

Manage tokens

The API tokens tab lists each token with its name, the first characters of the token, its scopes, when it was last used and when it was created. Last used updates at most once a minute.

Click Revoke to stop a token. Pipelines using it fail at once. Creating and revoking tokens are both recorded in the activity log.

Call the API

Send the token in the Authorization header:

Authorization: Bearer cm_live_…

The routes are:

Method and pathScopeWhat it does
GET /api/v1/whoamianyThe token's organization, name and scopes
GET /api/v1/systemsreadYour systems: id, name, kind and visibility (public when one of its APIs is published)
GET /api/v1/contractsreadYour contracts with their status and problems. Add ?system=<id> for one system's
GET /api/v1/can-i-deployreadWhether a version may go to an environment
POST /api/v1/deploymentsdeployRecord that a version runs in an environment

The contract watcher reports to POST /api/v1/watch/report with its own key, made when you download a watcher. That key can do nothing else. See Contract watcher.

Safety check (can-i-deploy)

Send system, version and env in the query string, using ids. A new project has two environments, dev and prod; the examples under Integrations → API & CI use your project's own. An id that doesn't exist answers 404 with the ids you can use.

GET /api/v1/can-i-deploy?system=auth-service&version=1.4.0&env=prod

The answer has approved (true or false), the blocking contracts, the warnings (in Development, calls that would break don't block: they are listed here), and output, the same lines the Deployments page shows. A blocked check also raises a Deployment blocked event, so the team is notified, and adds deployment.blocked to the activity log. See Environments and deployments.

Record a deployment

POST /api/v1/deployments
{"system": "auth-service", "version": "1.4.0", "env": "prod"}

The release must exist first, and the environment can't be Development (it runs what is published: 409). An environment that asks for approval first, as Production does unless you change it, answers 202 with a move request for its approvers instead; send "approval":"none" to record it at once, marked without approval. The answer is 201 with the new deployment, which shows as deployed by "API · " and the token's name.

Errors

Errors come back as JSON with an error message:

StatusMeans
401No token, or it is wrong or revoked
403The token lacks the scope this route needs
400A required field is missing
404No such route, release, environment or system
409Recorded to Development, which runs what is published

The /api/v1 routes don't set a rate limit of their own.