Gateway
Gateway API
Every endpoint: what it takes, what it answers, who may call it, and its errors.
Self-hostedChronos Gateway runs on your own servers today. Releases and install script. The engine under it: Chronos DB, self-hosted
Basics
- The API listens on port 7400 (
GATEWAY_LISTEN). The examples use$GATEWAYfor its address, such ashttp://localhost:7400orhttps://gateway.example.com. - Every request carries
Authorization: Bearer <token>, exceptGET /healthand the pages. - Bodies are JSON (
Content-Type: application/json). Answers are JSON. - Times in answers (
created,expires) are milliseconds since 1970. - Only
GETandPOST /v1/approveanswer web pages on other sites (CORS, for the origins inGATEWAY_ALLOWED_ORIGINS). Everything else is for servers. - With
OTEL_EXPORTER_OTLP_ENDPOINTset, a request with a W3Ctraceparentheader joins the caller’s trace.
This page describes gateway 0.4.4 on Chronos DB (the engine) 0.6.2. The Python (chronos-gateway) and TypeScript (@chronosdb/gateway) clients wrap these calls.
Tokens
Each token is 32 random bytes with a prefix. The gateway keeps only its SHA-256 hash, so a token is shown once, when it is made.
| Token | Made by | Who holds it | Opens | How long |
|---|---|---|---|---|
| cgk_ developer key | the console, POST /v1/keys, chronos-gateway keys create <name>, or GATEWAY_API_KEY | your backend | everything but a run’s own SQL, MCP and MongoDB tools, and the widget’s calls | until revoked |
| cgr_ run token | POST /v1/runs, once | one agent | that one run: its sql, mcp, mongo, changes, propose and GET | until the run ends or its time runs out (GATEWAY_RUN_TTL) |
| cga_ approval token | POST /v1/runs/:id/approvals, or a Slack message of a held merge | one person | GET and POST /v1/approve for one held change, at the version it was made for, once | GATEWAY_APPROVAL_TTL |
| cgu_ undo link | a Slack message of a merge | whoever is in the channel | GET and POST /v1/approve to undo one merged change, once, as far as its rows are unchanged | GATEWAY_APPROVAL_TTL |
In the tables below, key means a developer key, run the run’s own token, approval a cga_ or cgu_ token, and sign-in the cookie of a person signed in. The console calls the key endpoints with its sign-in cookie in place of a key (see Console sign-in).
| Wrong token | Answer |
|---|---|
| No key, or a run or approval token, on a key endpoint | 401: send a developer key: Authorization: Bearer cgk_... (chronos-gateway keys create) |
| A key that is revoked or unknown | 401: that developer key isn’t valid |
| A developer key on a run-only endpoint | 401: send the run’s token |
| Another run’s token | 401: that token isn’t this run’s |
Anything but cga_ or cgu_ on /v1/approve | 401: send the approval token: Authorization: Bearer cga_... |
Naming a database
One gateway can work beside several databases. The first is named default. A request for another names it with the header X-Chronos-Source: <name> or the query ?source=<name>. Without one it means default, so nothing changes for a gateway with one database.
| Endpoints | How the database is named |
|---|---|
GET /v1/status, POST /v1/setup, POST /v1/refresh, /v1/labels, /v1/masks, /v1/policy | The header or ?source=. |
POST /v1/connect | name in the body, to connect one more. |
POST /v1/runs | source in the body, or the header. |
/v1/runs/:id/..., approvals, undo | Nothing: a run belongs to one database and every call on it goes there. |
GET /v1/runs | Every database’s runs; ?source=<name> or the header for one’s. |
| Keys, webhooks, events, single sign-on | The gateway’s own, shared by all. |
A name is 1 to 32 of a-z, 0-9, _ and -. One that isn’t connected answers 404 no_source, and the message lists those that are. A run across two databases isn’t offered.
curl -s "$GATEWAY/v1/policy" -H "Authorization: Bearer $KEY" -H 'X-Chronos-Source: shop'Errors
An error is an HTTP status and {"error": {"message", "code"?, ...}}. message is a sentence for a person. code, when there is one, is a SQLSTATE from the engine (42501, 23505, ...) or one of the gateway’s own. Some errors carry more keys beside them: conflicts, reasons, runs, sql, login.
HTTP/1.1 409 Conflict{"error": {"message": "the run's changes changed since they were shown: look at them again before deciding", "code": "stale"}}| Status | Means |
|---|---|
| 400 | The request is wrong: a missing or bad field. Fix it; sending it again fails the same way. |
| 401 | No token, the wrong kind, or one that isn’t valid. |
| 403 | The token is right but may not do this: a run that is over, a person not allowed. |
| 404 | No such run, key, webhook or database. |
| 409 | The state doesn’t allow it: a conflict, a stale version, a used link, something already there. |
| 410 | A link expired. |
| 429 | A rate limit. Wait and try again. |
| 500 | The gateway’s own store failed. The message says the gateway’s store: .... |
| 502 | The engine couldn’t be reached, or your identity provider couldn’t. |
| 503 | No engine yet (no_engine), or no gateway leads right now (no_leader, with Retry-After: 5). |
An error the engine answers keeps the engine’s status, message and code.
Every error code
| Code | Status | From | Meaning |
|---|---|---|---|
| act_as | 400 | POST /v1/runs | act_as is wrong: a role or settings the gateway can’t take. |
| attach | 400 | POST /v1/connect | The engine’s attach didn’t go through. The message holds what it said. |
| attached | 409 | POST /v1/connect | This gateway has a database already, or the name is taken. |
| bad_code | 401 | POST /console/setup | The setup code isn’t right, or it expired. |
| bad_key | 401 | POST /console/login | That developer key isn’t valid. |
| cascade | 409 | undo | Undoing would change rows besides the run’s own. Preview it, then undo with allow_cascade. |
| children_live | 409 | propose | From 0.4.0. The run has a child run still live. |
| depth | 400 | POST /v1/runs/:id/children | From 0.4.0. A child run can’t have children of its own. |
| evidence | 400 | propose | From 0.4.0. An evidence item is malformed, or there are more than 50. |
| changed_since | 409 | undo | Rows the run wrote have changed since. Nothing was undone. Undo with skip_changed to leave them. |
| confirm | 400 | POST /v1/connect | Over 1,000,000 rows. Send yes: true to go on. The message gives the sizes. |
| conflict | 409 | propose, approve, POST /v1/approve | Rows the run changed were changed in the database too. Nothing was written. With conflicts for a developer key. |
| disconnecting | 409 | DELETE /v1/sources/:name, POST /v1/connect | That database is being disconnected. |
| expired | 409, 403, 410 | propose; a run’s SQL, MCP, MongoDB; /v1/approve | The run’s time ran out (409 on propose, 403 for its agent), or the link expired (410). |
| forbidden_sql | 400 | a run’s SQL | A statement a run can’t send: it works inside its own world and reaches the database only through propose. |
| held | 409 | propose | This run’s merge is waiting for a person already. |
| invalid | 401 | /v1/approve | The approval or undo link isn’t valid. |
| mongo_tool | 400, 409 | POST /v1/runs/:id/mongo | A MongoDB tool was given what it doesn’t take (400), or a document kept changing under an update (409). |
| no_engine | 503 | anything that needs the engine | No engine yet: connect a database first. |
| no_leader | 503 | any request, with several gateways | No gateway leads right now. Retry-After: 5. |
| no_source | 404, 400 | anything that names a database | No database is connected under that name (404), or the name isn’t a valid one (400). |
| no_sso | 404 | the sign-in endpoints | Single sign-on isn’t set up here. |
| no_undo_record | 409 | undo | The run merged before the gateway kept merge ids, or the engine is older than 0.5.0. |
| not_admin | 403 | GET /v1/console/me | Signed in, and may approve, but isn’t on GATEWAY_OIDC_ADMINS. With approvals, where to go. |
| not_allowed | 403 | sign-in | The person isn’t on GATEWAY_OIDC_ALLOW. |
| not_yours | 403 | /v1/approve | The link was made for another approver than the person signed in. |
| origin | 403 | console and sign-in calls | Not from the gateway’s own pages: the console’s header is missing, or Origin isn’t GATEWAY_PUBLIC_URL. |
| reads_changed | 409 | approve, POST /v1/approve | What the run read changed since it began, or was too much to check. Nothing was merged. With reasons. |
| run_changed | 409 | approve, reject, discard, the reviewer, the sweeper | From 0.4.0. Another decision on the run came first. With status, what it is now. |
| runs_live | 409 | DELETE /v1/sources/:name | Runs of that database are still in progress. With runs, how many. |
| scope | 400 | POST /v1/runs/:id/children | From 0.4.0. The child’s may_change goes past its parent’s. |
| set_up | 409 | POST /console/setup | The gateway is set up already: sign in with a developer key. |
| setup_locked | 403 | POST /console/setup | Too many wrong setup codes. Make a new one with chronos-gateway setup-code. |
| sign_in | 401 | /v1/approve, the sign-in and console endpoints | A person must sign in first. With login, where. |
| sso_person | 403 | GET /sso/callback | The ID token doesn’t say who the person is. |
| sso_provider | 502 | sign-in | Your identity provider couldn’t be reached. |
| sso_token | 401 | GET /sso/callback | The ID token was refused. |
| stale | 409 | approve | The run changed after the person saw it (version). |
| tenant_column | 400 | POST /v1/runs | No attached table has that tenant column. The message lists the tables and their columns. |
| too_many_proposes | 429 | propose | Past GATEWAY_RUN_PROPOSES_PER_MINUTE. |
| too_many_runs | 429 | POST /v1/runs | The tenant has had GATEWAY_RUNS_PER_HOUR runs in the last hour. |
| undo_not_ready | 409 | undo | The gateway’s role has no table to keep what merges write. With sql, the statements to run once. |
| used | 409 | /v1/approve | The link was already used. |
| window_passed | 409 | approve, POST /v1/approve, Chronos Cloud | From 0.4.1. A strict change (it sends payment, payout, transfer or refund effects) whose window ran out. Nothing was merged. Reject it; the agent proposes again. With strict. |
| strict_target | 409 | approve, POST /v1/approve, Chronos Cloud | From 0.4.2. A strict change approved after other changes reached the database since its hold. Nothing was merged. Reject it; the agent proposes again. |
| world_lost | 409 | any call on a run | The run’s copy was lost with a crashed engine. The run is now failed. Start a new run. |
a run status (merged, rejected, ...) | 409, 403 | propose, reject; a run’s SQL, MCP, MongoDB | The run is in that state and can’t do this any more. |
Past GATEWAY_RUN_STATEMENTS_PER_MINUTE, a run’s SQL, MCP and MongoDB calls answer 429 with a message and no code.
Status and health
| Call | Who | Answers |
|---|---|---|
| GET /health | none | {"ok": true}, for load balancers. Each gateway answers it itself, a follower too. |
| GET /v1/status | key | The gateway’s state, for the database the request names. |
curl -s "$GATEWAY/v1/status" -H "Authorization: Bearer $KEY"{ "engine": {"configured": true, "healthy": true}, "ha": {"shared": false, "role": "leader"}, "extensions": {}, "source": "default", "sources": [{"name": "default", "kind": "postgres", "tables": ["leads", "accounts"], "tenant_column": "org_id"}], "attached": {...}, "policy": {"name": "gateway", "rules": {...}}, "tenant_column": "org_id", "runs": {"open": 2, "held": 1, "merged": 40}, "webhooks": {"pending": 0, "failed": 0}, "cloud": null}| Field | Meaning |
|---|---|
| engine | configured: a database is connected. healthy: the engine answers. |
| ha | Alone: {shared: false, role: "leader"}. Sharing a store: {shared: true, node, role: "leader" | "follower", leader: {node, url, expires}}. |
| extensions | What is built in beside the gateway itself. Empty in the open gateway. |
| source, sources | The database this answer is about, and all of them: {name, kind, tables, tenant_column}. |
| attached | The engine’s own account of what is attached, undo.ready and capabilities included. Null before a database is connected. |
| policy | The merge policy’s name and its rules now. |
| runs | Run counts by status. |
| webhooks | Deliveries pending and failed. |
| cloud | Null unless linked to Chronos Cloud: {state, reason, connector_id, link, cloud, share, allow, outbox, since}, state one of starting, connecting, online, offline, stopped. |
Connect and sources
| Call | Who | Body | Answers |
|---|---|---|---|
| POST /v1/connect/check | key | url, schema (public) | What is in the database. Reads the catalog only; the URL is kept nowhere. |
| POST /v1/connect | key | url, tables, tenant_column, yes, name, fields (MongoDB) | {ok, tables, tenant_column, source, output} |
| GET /v1/sources | key | {sources: [{name, kind, tables, tenant_column}]} | |
| DELETE /v1/sources/:name | key | ?discard_runs=true | {ok, name, discarded} |
| POST /v1/setup | key | tenant_column | {ok, policy, rules}: the merge policy made, or set to the rules again |
| POST /v1/refresh | key | The engine’s refresh: {at, changed, tables, skipped} |
POST /v1/connect/check
Takes a postgres://, mysql://, mariadb://, mongodb:// or mongodb+srv:// URL. It answers {source, role, superuser, server_version, database, tables, attachable, tenant_candidates, role_sql, warnings, follow}.
| Field | Meaning |
|---|---|
| source | postgres, mysql (with flavor: mysql or mariadb) or mongodb. |
| tables | Each {name, rows, key, columns, generated, partitioned, row_security, attachable, refused, sensitive}. refused says why one can’t be attached. sensitive lists columns whose names suggest values agents shouldn’t read (email, phone, ssn, password, token, card, address, ...), a hint for masks. Beside MySQL also auto_increment and inserts; beside MongoDB also fields. |
| tenant_candidates | Columns that look like a tenant column: {column, tables, of}. |
| role_sql | The statements that make a least-privilege role for the gateway. A mongosh script beside MongoDB. |
| warnings | For example: the URL logs in as a superuser, or points at a read replica. |
| follow | {ready, missing}: whether GATEWAY_FOLLOW can work there, and what is missing. |
curl -s "$GATEWAY/v1/connect/check" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"url": "postgres://admin:ADMIN_PASSWORD@db.internal:5432/app"}'POST /v1/connect
| Field | Meaning |
|---|---|
| url | The gateway’s own role’s URL. Kept in the data folder (source.url, mode 600). Refused (400) while GATEWAY_SOURCE_FILE is set: the URL is that file’s. |
| tables | The tables, or collections, agents may work on. Only these are copied. |
| tenant_column | The column that names each row’s tenant. Recorded, so a run can give just the value. |
| yes | true to attach more than 1,000,000 rows. |
| name | Connects one more database under this name. Kept in <data>/sources/<name>/. Not with an engine run elsewhere (CHRONOS_ENGINE_URL). |
| fields | Beside MongoDB: the fields kept as columns. See MongoDB tools. |
curl -s "$GATEWAY/v1/connect" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"url": "postgres://chronos_gateway:ROLE_PASSWORD@db.internal:5432/app?sslmode=verify-full", "tables": ["leads", "accounts"], "tenant_column": "org_id"}'Errors: 409 attached, 400 confirm, 400 attach, 409 disconnecting.
DELETE /v1/sources/:name
Disconnects a database connected under a name. The gateway stops its engine and deletes its own copy and settings (<data>/sources/<name>/, its rules, labels and masks). Nothing is touched in the database itself, where Chronos’s own tables stay. Its runs stay in the list as history, and the name is free again afterwards.
- While runs of it are still in progress (open, held, in conflict, failed): 409
runs_live, witherror.runs.?discard_runs=truediscards them with it. - The first database (
default) isn’t disconnected this way: 400. A gateway for another database starts on a data folder of its own. - A name that isn’t connected: 404
no_source. One being disconnected already: 409disconnecting.
Runs
| Call | Who | Body or query | Answers |
|---|---|---|---|
| POST /v1/runs | key | see below | 201: the run, with its token |
| GET /v1/runs | key | ?status=&limit=&source= (limit 50, 500 at most) | {runs} |
| GET /v1/runs/:id | key or run | The run | |
| DELETE /v1/runs/:id | key | {"status": "discarded"} | |
| POST /v1/runs/:id/children | key | intent, may_change, max_rows, max_deletes, row_rules, ttl_seconds, run_id, meta | From 0.4.0. 201: a child run, with its own token and parent. See Child runs |
| PATCH /v1/runs/:id/meta | key or run | an object of keys (null removes one) | From 0.4.0. {id, meta}, at most 64 KB |
POST /v1/runs
| Field | Meaning |
|---|---|
| tenant | Required. Whose rows the run may touch: {"org_id": 42}, "org_id = 42", or just 42 when tenant_column was set at connect. |
| intent | What the run is for. Shown to approvers and in Slack. |
| end_user | Who it acts for. |
| ttl_seconds | A shorter life than GATEWAY_RUN_TTL. Never longer. |
| meta | Any JSON you want kept with the run. |
| run_id | Your own id for the run, kept on its world. |
| source | The database it works beside. Without it: the header’s, else default. |
| may_change, max_rows, max_deletes | What the run declares about its change, kept on its world with the intent. |
| row_rules | Conditions each row the run changes must keep, such as "payments: new.amount <= 100". A row breaking one holds the merge. They can only make the policy stricter. |
| act_as | Postgres only. {"role": "authenticated", "settings": {"request.jwt.claims": {...}}}: the run’s writes reach Postgres as that role, with those settings, so your grants and row-level security judge them. |
curl -s "$GATEWAY/v1/runs" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"tenant": {"org_id": 42}, "intent": "remove the duplicate lead", "end_user": "user_7"}'{ "id": "run_...", "token": "cgr_...", "sql_url": "https://gateway.example.com/v1/runs/run_.../sql", "mcp_url": "https://gateway.example.com/v1/runs/run_.../mcp", "status": "open", "tenant": {"column": "org_id", "value": 42}, "intent": "remove the duplicate lead", "end_user": "user_7", "source": "default", "created": 1767225600000, "expires": 1767229200000}Errors: 400 tenant_column, 400 act_as, 404 no_source, 429 too_many_runs (and a run.refused event), 503 no_engine.
A run
| Field | Meaning |
|---|---|
| id, world, agent | The run’s id, and the engine world and agent behind it. |
| status | open, held, merged, conflict, rejected, undone, partly_undone, expired, discarded or failed. |
| tenant | {"column", "value"}. |
| intent, end_user, meta | As given. |
| created, updated, expires, hold_expires | Times. hold_expires is set while it is held. |
| outcome | The last answer about its merge: rows merged, reasons held, conflicts, who approved, the reviewer’s verdict, the error. |
| merges | The ids of the merges that wrote it to the database: what an undo names. |
| parent, children, evidence | From 0.4.0. A child run’s parent; a parent’s children ([{id, status, intent, created, expires, outcome}]); the evidence its propose carried ({items, in_engine}). |
| source | The database it works beside. |
| sql_url, mcp_url | Where its agent sends SQL and MCP. |
SQL, MCP and MongoDB for a run
These three take the run’s token only. A developer key is refused: the agent’s side is the agent’s.
| Call | Body | Answers |
|---|---|---|
| POST /v1/runs/:id/sql | sql, params | The engine’s {results: [{command, columns, types, rows}]}. Rows past GATEWAY_RUN_MAX_ROWS are cut and marked truncated. |
| POST /v1/runs/:id/mcp | one JSON-RPC message | MCP over HTTP, as the run’s agent. |
| POST /v1/runs/:id/mongo | tool, arguments | One of MongoDB’s own tools, beside MongoDB. See MongoDB tools. |
curl -s "$GATEWAY/v1/runs/$RUN/sql" -H "Authorization: Bearer $RUN_TOKEN" -H 'Content-Type: application/json' \ -d '{"sql": "delete from leads where id = $1", "params": [3]}'The MCP endpoint offers the tools that work inside a world, each pointed at the run’s world: describe, find, sql, put, diff, history, check_reads, merge_preview, rebase, checkpoint, rollback, merge_policies, check_merge_policy and merge_checks. Tools that merge, fork or drop worlds are left out. Beside MongoDB it adds mongo_find, mongo_count, mongo_insert, mongo_update_one, mongo_update_many, mongo_delete_one and mongo_delete_many.
Errors: 401 for a token that isn’t this run’s; 403 with the run’s status as the code once it is no longer open or in conflict; 403 expired; 429 past GATEWAY_RUN_STATEMENTS_PER_MINUTE; 400 forbidden_sql for a statement a run can’t send; 400 mongo_tool; 409 world_lost; and the engine’s own errors with their SQLSTATE (42501 for a write outside the tenant’s rows).
Changes and propose
| Call | Who | Body or query | Answers |
|---|---|---|---|
| GET /v1/runs/:id/changes | key or run | ?limit= (200, 2,000 at most) | {status, version, total, summary, tables, changes, more, reasons} |
| POST /v1/runs/:id/propose | key or run | confirm_deletes, evidence (from 0.4.0: [{kind, uri, sha256, note}], at most 50), and to settle conflicts by_columns, resolve, rows, target | see below |
{ "status": "open", "version": 4, "total": 1, "summary": ["1 lead removed"], "tables": {...}, "changes": [{"text": "Remove lead “Hooli”", "kind": "...", "table": "leads", "key": "...", "before": {...}, "after": {...}}], "more": false, "reasons": null}version is what an approval names, so a person approves what they looked at. A run that is over reads its changes from its record, its database connected or not.
| Propose answers | Meaning |
|---|---|
200 {"status": "merged", "merged": n} | Within the rules: written to the database. |
202 {"status": "held", "reasons": [...]} | A rule was broken. Nothing is written yet. merge.held is sent. From 0.4.1, with engine 0.6.2, a strict change also has strict: {channels, until}: see below. |
409 conflict, with conflicts | Rows the run changed were changed in the database too. Nothing is written. Proposing the same way again fails the same way: propose again settled, or have a person approve it settled. |
409 expired | The run’s time ran out first. |
409 held | It is waiting for a person already. |
409 children_live | From 0.4.0. A child run of it is still live: propose once its children are done. |
200 {"status": "merged", "into"} | From 0.4.0. A child run, merged into its parent’s world. |
200 {"status": "merged", "reconciled": true} | From 0.4.0. The engine’s answer was lost, and its history shows the merge landed. |
| 409, the run’s status as the code | It is merged, rejected or otherwise over. |
429 too_many_proposes | Past GATEWAY_RUN_PROPOSES_PER_MINUTE. Each propose locks and compares rows in your database. |
curl -s "$GATEWAY/v1/runs/$RUN/propose" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'HTTP/1.1 202 Accepted{"status": "held", "reasons": ["deletes 1 row, more than 0"]}Approve, reject and undo
| Call | Who | Body | Answers |
|---|---|---|---|
| POST /v1/runs/:id/approve | key | version, by, skip_read_check; only_tables or only_keys for a part; by_columns, resolve, rows, target to settle | {"status": "merged", "merged": n}; a part: {status, merged, partial: true} |
| POST /v1/runs/:id/reject | key | reason, by | {"status": "rejected"} |
| POST /v1/runs/:id/undo | key | preview, skip_changed, allow_cascade, by | {status: "undone" | "partly_undone", rows, skipped, changed_since, effects_not_undone} |
Approve
Merges a held run, or one in conflict, as a person. The write has the same row checks as any merge.
version(from/changes): approve only what you looked at. If the run changed since: 409stale.by: who decided, kept in the outcome and sent inmerge.landed.only_tables(["leads"]) oronly_keys(["leads/7"]): approve a part. The rest is left in the run as it was, to approve or reject after.merge.landedsayspartial.- 409
reads_changed, withreasons: what the run read changed since it began, in the database or the gateway’s copy, or was too much to check (over 100,000 rows of a table read by more than its keys). Nothing was merged. skip_read_check: truemerges without that check. The rows it changed are still checked.merge.landedand the outcome sayreads_checked: false.- 409
conflictif rows still conflict. - 409
window_passed, withstrict: a strict change whose window ran out (from 0.4.1). Nothing was merged. - 409
strict_target: a strict change approved after other changes reached the database since its hold (from 0.4.2). Nothing was merged. A strict change is approved whole:only_tablesoronly_keyson one are refused 400.
curl -s "$GATEWAY/v1/runs/$RUN/approve" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"version": 4, "by": "ada@example.com"}'{"status": "merged", "merged": 1}Strict changes
From 0.4.1, with engine 0.6.2. A held run whose merge sends payment, payout, transfer or refund effects, or ones its merge policy names in strict_channels, records strict: {channels, until} (until in ms) in its hold, in merge.held and in the propose’s answer. Only a person approves it, before until: 15 minutes from the hold unless the policy’s strict_window says otherwise.
- The AI reviewer never approves one: it passes it to a person with why.
- Every approval of it checks the window, through the API, an approval link or Chronos Cloud, held or in conflict: after
until, 409window_passed. Proposed again into a conflict, it keeps its window. - If the engine’s
EXPLAIN MERGEfails at the hold, the change is taken as strict:{channels: [], until, unchecked: true}. - From 0.4.2 the hold also records
strict.target, the state of the database the run merges into, and every approval merges bound to it: after other changes reached the database, 409strict_target, as an engine strict proposal is superseded. A run held by 0.4.1 has no target and is approved on its window alone.
See Approvals.
Undo
Puts back every row a run’s merges wrote, as it was before, through the database as any merge goes: each row locked and compared, one transaction. It takes a merged run; a partly_undone run, for the rows left; and a run that ended rejected, expired or discarded after a part of it was approved, for what that part wrote. For 30 days after the merge. Needs engine 0.5.0 or later, and the engine’s record table in the database (attached.undo.ready in GET /v1/status).
| Field | Meaning |
|---|---|
| preview | true writes nothing and answers {preview, rows, skipped, changes, changed_since, cascades, effects_not_undone}. Each change is in words: “Change the owner of lead Acme from Ada to Bo”, “Remove note 7”, “Add lead Hooli”. Masked columns read (masked). |
| skip_changed | Rows changed since the merge stay as they are, and the rest go back. Without it they refuse the undo: 409 changed_since, nothing written, merge.undo_conflict sent. |
| allow_cascade | An undo that would change rows besides the run’s own (as with ON DELETE CASCADE) is refused, 409 cascade, until this is true. A preview names the tables in cascades (Postgres; null beside MySQL, which can’t say). |
| by | Who undid it. |
changed_since lists the rows changed since the merge, each with the row now. effects_not_undone lists [{id, channel, state}]: emails and webhooks the merge queued, which are never unsent. Other errors: 409 no_undo_record, 409 undo_not_ready (with error.sql), and 409 with the run’s status as the code for a run that is still live (open, held, conflict, failed), one already undone, or one that ended without any merge.
A partly_undone run is undone again the same way, once the rows left hold what the run wrote: changed back through a run, or directly in the database with GATEWAY_FOLLOW on or after a refresh. Rows the first undo put back are not counted. rows is what this undo put back, outcome.undone.rows is every row over both, and the run becomes undone when none is left. With an engine older than 0.5.2 the second undo needs "skip_changed": true. See Undo.
curl -s "$GATEWAY/v1/runs/$RUN/undo" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"preview": true}'curl -s "$GATEWAY/v1/runs/$RUN/undo" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"skip_changed": true, "by": "ada@example.com"}'{"status": "partly_undone", "rows": 11, "skipped": 1, "changed_since": [...], "effects_not_undone": []}Settling conflicts
A run in conflict changed rows that the database changed too since the run began. propose and approve take these fields to settle them. The result is judged under the merge policy like any merge.
| Field | Does |
|---|---|
| by_columns: true | A row where the two sides changed different columns combines. Try this first. |
| by_columns: true, resolve: "ours" | "theirs" | That side wins only for the columns both changed (ours: the run’s; theirs: the database’s). Each column only one side changed keeps its value. |
| rows | Single rows: {"orders/7": "ours" | "theirs" | "delete" | {the row to keep}}. |
| resolve, without by_columns | Whole rows, overwriting the other side’s changes to other columns. Use it last: a policy with overwrite = false (the default) sends it to a person. |
| target | The target a preview of the merge gave (the run’s MCP merge_preview), so rows settle against the data as that preview saw it. |
curl -s "$GATEWAY/v1/runs/$RUN/propose" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"by_columns": true, "rows": {"orders/7": "theirs"}}'Approval links
| Call | Who | Body | Answers |
|---|---|---|---|
| POST /v1/runs/:id/approvals | key | end_user, expires_in, approver | {token, version, approver, expires, link, widget: {script, html}} for a held run |
| GET /v1/approve | approval | The change, in words | |
| POST /v1/approve | approval | decision, reason, skip_read_check, skip_changed | The run’s new status |
linkis a page of the gateway’s showing the change (/approve#<token>), to send anyone. The token is after#, so it never reaches a server’s log.widgetholds ascriptURL and anhtmltag for your own page.expires_in: seconds, from 1 toGATEWAY_APPROVAL_TTL. Without it:GATEWAY_APPROVAL_TTL.end_user: who it is for; without it, the run’s.approver: an email onGATEWAY_OIDC_ALLOW, with single sign-on only. Only that person, signed in, can see or decide it.
<script src="https://gateway.example.com/widget.js"></script><chronos-approve base="https://gateway.example.com" token="cga_..."></chronos-approve>GET /v1/approve answers {run: {id, intent}, summary, changes, total, more, reasons, stale, strict, expires, approver, signed_in}; strict (from 0.4.1) is {channels, until} for a strict change, else null. For an undo link (cgu_) it answers {kind: "undo", run, rows, changes, changed_since, cascades}, each change as {kind, text, table, key}: words, never a row’s values.
POST /v1/approve takes {"decision": "approve"} or "reject" (with a reason), once per token; approving merges exactly the version the link was made at. For an undo link it takes {"decision": "undo"}, with skip_changed to leave rows changed since.
| Answer | Meaning |
|---|---|
401 invalid | The link isn’t valid. |
401 sign_in, with login | The link was made for an approver, or GATEWAY_OIDC_REQUIRE=on, and nobody is signed in. |
403 not_yours | Someone else is signed in than the link was made for. |
409 used | Already decided, or already undone. |
410 expired | The link’s time ran out. Make a new one. |
409 reads_changed | As for approve. The token is not used up: the widget asks the person, and approves again with skip_read_check if they say so. |
409 conflict | Rows it touches changed in the database, said in words only. The rows themselves are for a developer key, from POST /v1/runs/:id/approve. |
409 changed_since, cascade, undo_not_ready | An undo link’s refusals. See Webhooks and Slack. |
Single sign-on
For people who approve, when GATEWAY_OIDC_ISSUER is set. These are a browser’s, with the sign-in cookie (chronos_gateway_session) on the gateway’s own pages. Without a sign-in: 401 sign_in, with login. When single sign-on isn’t set up: 404 no_sso.
| Call | Takes | Answers |
|---|---|---|
| GET /sso/login | ?next=/approvals (a path of the gateway’s) | 302 to your provider’s sign-in (authorization code, PKCE, a nonce). |
| GET /sso/callback | your provider’s answer | The ID token checked, the person checked against GATEWAY_OIDC_ALLOW: 302 to next, signed in; or a page saying why not. |
| POST /sso/logout | {ok}: the sign-in ended. | |
| GET /approvals | A page: the held changes, to review and decide signed in. | |
| GET /v1/me | {email, name, sub, groups} | |
| GET /v1/me/held | {runs: [{id, intent, tenant, end_user, created, hold_expires, reasons}]}, newest first. | |
| POST /v1/me/runs/:id/approval | An approval of that held run for the person signed in, for the widget on /approvals. 403 origin from another site’s page. |
A decision made signed in records approved_by: {end_user, person: {email, name, sub}, via: "sso"}. A decision made with a developer key records {by, via: "api"}: by is whatever the caller sent, kept as given and never checked. Your backend says who decided; the gateway vouches only for via. via: "console" and via: "sso" name a person the gateway signed in itself.
Policy
| Call | Who | Body | Answers |
|---|---|---|---|
| GET /v1/policy | key | {name, rules, text, source, engine, known} | |
| PUT /v1/policy | key | rules: the whole set | As GET, after the engine took it, with ended: the names of the rules that were set before and this set left out ([] when none). 400 for an unknown rule or a bad value. |
rulesis the rules as an object;textthe same as the engine’s text.sourceisset(byPUT, kept in the gateway’s store) orconfig(GATEWAY_POLICY_RULES). Rules that were set win over the setting.engineis the policy as the engine holds it, or null.knownlists every rule’s name.PUTreplaces the whole set: a rule left out ends, and the answer names it inended. To change one rule,GETthe rules, change it, andPUTthem all.
curl -s -X PUT "$GATEWAY/v1/policy" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"rules": {"max_rows": 100, "max_deletes": 0, "rows_per_hour": 5000, "max_age": "30 minutes", "check_reads": true, "require_scope": true}}'{"name": "gateway", "rules": {...}, "text": "...", "source": "set", "engine": {...}, "known": [...], "ended": []}The example sends every rule. Sent with max_rows alone, it would end max_deletes = 0 too, and deletes would merge without a person.
What each rule means is in Rules, labels and masks.
Labels and masks
| Call | Who | Body | Answers |
|---|---|---|---|
| GET, PUT /v1/labels | key | {tables: {<table>: {name, plural, title, columns: {<col>: label | null}}}} | The labels |
| GET, PUT /v1/masks | key | {tables: {<table>: {<col>: "hash" | "null" | "partial" | "format" | null}}} | The masks, as the engine holds them |
- Labels name tables and columns in approvals, and hide a column from people’s view of a change (
null). They hide nothing from the agent. - Masks are what an agent reads.
hash: a keyed hash of each value, so it can still join and count on it.null: NULL.partial: the last four characters.format: a value of the same shape.null(not the string) unmasks a column; a column not named keeps its mask. - Runs started after a mask is set read it. A run already open keeps the table as it was when it started.
- Your database is never changed by either.
curl -s -X PUT "$GATEWAY/v1/labels" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"tables": {"leads": {"name": "lead", "title": "name", "columns": {"owner": "owner", "org_id": null}}}}'curl -s -X PUT "$GATEWAY/v1/masks" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \ -d '{"tables": {"leads": {"email": "hash", "phone": "partial"}}}'Webhooks and events
| Call | Who | Body or query | Answers |
|---|---|---|---|
| POST /v1/webhooks | key | url, events (none: all), format (json or slack) | 201 {id, url, events, format, created, secret}: the secret only now |
| GET /v1/webhooks | key | {webhooks: [{id, url, events, format, created}]} | |
| DELETE /v1/webhooks/:id | key | {"ok": true}; 404 if there is none | |
| GET /v1/effects | key | ?status= (pending, delivered or dead), limit | From 0.4.0. {effects: [{id, source, channel, payload, world, approved, status, attempts, next_at, last_error, receipt, created, updated}], delivering}, newest first. See Effects |
| GET /v1/events | key | ?after=<event id>&limit= (100, 1,000 at most), or ?last=N | {events: [{id, type, run_id, data, created}]}, oldest first |
Event types, their fields, the signature and the Slack format are in Webhooks and Slack.
Keys
| Call | Who | Body | Answers |
|---|---|---|---|
| GET /v1/keys | key | {keys: [{id, name, created, revoked}]} | |
| POST /v1/keys | key | name: what uses it (backend, ci), at most 100 characters | 201 {id, name, key}: the key only now |
| DELETE /v1/keys/:id | key | {"ok": true}; 404 if there is none |
curl -s "$GATEWAY/v1/keys" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"name": "ci"}'{"id": "key_...", "name": "ci", "key": "cgk_..."}A key set with GATEWAY_API_KEY isn’t in this list and can’t be revoked here: remove the setting and restart.
Console sign-in
The console’s page signs in with a developer key or single sign-on, and then calls the API above with a cookie (chronos_gateway_session) in place of a bearer token. Those calls need the header X-Chronos-Console: 1 and, when the browser sends one, an Origin equal to GATEWAY_PUBLIC_URL. They are for the console’s own page; your backend uses a key.
| Call | Body | Answers |
|---|---|---|
| POST /console/login | key | Sets the cookie. 401 bad_key; 403 origin without the console’s header. |
| POST /console/setup | code (from the log), name | While no key exists: makes the first key, sets the cookie, {ok, key, id, person}. 409 set_up, 401 bad_code, 403 setup_locked. |
| GET /v1/console/setup | {needed, code}: whether no key exists yet, and whether a setup code waits. | |
| GET /v1/console/me | {person, gateway: {version, public_url, policy}, sso}. 401 sign_in; 403 not_admin (signed in by single sign-on, not on GATEWAY_OIDC_ADMINS). |
Pages and scripts
| Path | Is |
|---|---|
| GET /console | The console. It signs in. |
| GET /approve | The page an approval or undo link opens. Its token is after #. |
| GET /approvals | The held changes, for people signed in (single sign-on). |
| GET /widget.js | The approval widget’s script, for your own pages. |