RabbinatixDocs
Sign inGet started

Run and observe

CI and the API

Gate deployments in CI with the safety check and record what you deploy, using an API token and the HTTP API.

Open API & CI in the app

What you can do from CI today

Rabbinatix has an HTTP API for CI pipelines. With an API token you can:

  • check whether a release can go to an environment (the safety check, can-i-deploy);
  • record a deployment after it succeeds;
  • list your systems and read the status of their contracts.

You call it with any HTTP client, such as curl, from any CI system. Integrations → API & CI shows the same examples with your own address and a system of yours filled in, ready to copy, and a GitHub Actions workflow built from them.

Create an API token

  1. Open Integrations and go to API tokens.
  2. Click New token.
  3. Give it a Name, such as GitHub Actions.
  4. Pick its Scopes. Pick only what the pipeline needs.
  5. Click Create token and copy the token. It starts with cm_live_ and is shown only once.

Store the token as a secret in your CI system, for example RABBINATIX_TOKEN. The list shows each token's scopes and Last used. Revoke stops a token at once: pipelines using it fail on their next call.

ScopeLets the token
readList systems, read contracts, run the safety check
deployRecord deployments

AI assistants use keys of their own, not API tokens. See API and tokens.

The API address

Copy the Base URL from Integrations → API & CI. It ends in /v1. Set it once in your pipeline:

export RABBINATIX_API="https://<your functions host>/api/v1"   # the Base URL
export RABBINATIX_TOKEN="cm_live_…"                             # from your CI secrets

Every request sends the token as a bearer token. Check it works:

curl -s "$RABBINATIX_API/whoami" -H "Authorization: Bearer $RABBINATIX_TOKEN"

The routes

RouteScopeWhat it does
GET /v1/whoamianyThe token's organization, name and scopes
GET /v1/systemsreadYour systems, with their IDs
GET /v1/contracts?system=<id>readContracts with their status and problems (one system's, or all)
GET /v1/can-i-deploy?system=<id>&version=<v>&env=<id>readThe safety check
POST /v1/deploymentsdeployRecord {"system", "version", "env"}
GET /v1/mock?system=<id or name>readA system's published APIs, for the test server on your machine (rabbinatix mock, see Test server)
POST /v1/impactread (deploy to keep it)What a code change affects. Sent by rabbinatix impact; see below
POST /v1/code-scanscanSecurity findings in your code, into Code scan. Sent by rabbinatix scan --report
POST /v1/code-statusreadYour code's anchors against the map. Sent by rabbinatix status
POST /v1/testreadRuns flows' test cases, simulated. Sent by rabbinatix test (a few calls a minute per token)
GET /v1/openapi?system=<id>&version=<v>readA system's OpenAPI, stamped. Sent by rabbinatix openapi pull
POST /v1/openapi/diffreadA spec's operations against the map. Sent by rabbinatix openapi diff
POST /v1/generatereadGenerated code of logic or a system. Sent by rabbinatix generate (/v1/generate/record lists it on the code panel's Exported tab)
GET /v1/runs?logic=<key>&language=<lang>readA logic's recorded test runs, ready to replay. Sent by rabbinatix verify

System IDs come from GET /v1/systems. Environment IDs are dev, staging and prod unless you added your own.

You rarely call these yourself: the rabbinatix CLI wraps each one with readable output and exit codes. Every command: The rabbinatix CLI.

Gate a deployment

The safety check runs the same check as the Safety check view on the Deployments page. It answers with approved (true or false), the contracts that block, and output: the same lines the app prints. Leave out version to check the system's current declarations.

The call succeeds even when the deployment is blocked, so your script decides to stop:

result=$(curl -sf "$RABBINATIX_API/can-i-deploy?system=auth-service&version=2.5.0&env=prod" \
  -H "Authorization: Bearer $RABBINATIX_TOKEN")
echo "$result" | jq -r .output
echo "$result" | jq -e .approved > /dev/null || exit 1

A blocked check is also an event: it shows in the activity log and can notify people through deployment.blocked webhooks.

Record a deployment

After the deploy succeeds, tell Rabbinatix what now runs where:

curl -sf -X POST "$RABBINATIX_API/deployments" \
  -H "Authorization: Bearer $RABBINATIX_TOKEN" \
  -H "content-type: application/json" \
  -d '{"system":"auth-service","version":"2.5.0","env":"staging"}'

The release must exist already: make it under Releases in the sidebar first. Development always runs what is published, so recording there answers 409. An environment that asks for approval first answers 202 with a move request for its suggested approvers; send "approval":"none" to record it at once instead (the answer says "withoutApproval": true, and so does the deployment). With no approvers set there, it is recorded at once, without approval. The CLI's rabbinatix deploy record --no-approval does the same. The deployment shows on Deployments with API · <token name> as who recorded it.

A full pipeline step

  1. Build and test as usual.
  2. Run the safety check for the target environment. Stop when approved is false.
  3. Deploy.
  4. Record the deployment.

Run steps 2 to 4 for each environment you move releases to, such as staging and then production.

Check what a pull request affects

rabbinatix impact runs in your pull request pipeline and says what the change affects on the map: the logic its code belongs to, the flows and contracts around it, and the test cases worth running. It reads the code on the CI machine and sends only keys, names, file paths and line numbers. Integrations → API & CI has a GitHub Actions workflow to copy:

npx -y rabbinatix impact --store --comment impact.md   # needs RABBINATIX_API and RABBINATIX_TOKEN
gh pr comment "$PR" --edit-last --body-file impact.md   # one comment, updated on each push

--store needs a token with the deploy scope; reading the answer needs only read. How to set it up, every option, and how to read the reports on the Code impact page: Code impact.

Errors

StatusMeaning
401No token, or the token was revoked
403The token lacks the scope for this route
404No such route, system, environment or release
413The change is too big to send (over 256 KB of keys and paths)
409Recorded to Development (it runs what is published)