Chronos/DBWaitlist

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 $GATEWAY for its address, such as http://localhost:7400 or https://gateway.example.com.
  • Every request carries Authorization: Bearer <token>, except GET /health and the pages.
  • Bodies are JSON (Content-Type: application/json). Answers are JSON.
  • Times in answers (created, expires) are milliseconds since 1970.
  • Only GET and POST /v1/approve answer web pages on other sites (CORS, for the origins in GATEWAY_ALLOWED_ORIGINS). Everything else is for servers.
  • With OTEL_EXPORTER_OTLP_ENDPOINT set, a request with a W3C traceparent header 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.

TokenMade byWho holds itOpensHow long
cgk_ developer keythe console, POST /v1/keys, chronos-gateway keys create <name>, or GATEWAY_API_KEYyour backendeverything but a run’s own SQL, MCP and MongoDB tools, and the widget’s callsuntil revoked
cgr_ run tokenPOST /v1/runs, onceone agentthat one run: its sql, mcp, mongo, changes, propose and GETuntil the run ends or its time runs out (GATEWAY_RUN_TTL)
cga_ approval tokenPOST /v1/runs/:id/approvals, or a Slack message of a held mergeone personGET and POST /v1/approve for one held change, at the version it was made for, onceGATEWAY_APPROVAL_TTL
cgu_ undo linka Slack message of a mergewhoever is in the channelGET and POST /v1/approve to undo one merged change, once, as far as its rows are unchangedGATEWAY_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 tokenAnswer
No key, or a run or approval token, on a key endpoint401: send a developer key: Authorization: Bearer cgk_... (chronos-gateway keys create)
A key that is revoked or unknown401: that developer key isn’t valid
A developer key on a run-only endpoint401: send the run’s token
Another run’s token401: that token isn’t this run’s
Anything but cga_ or cgu_ on /v1/approve401: 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.

EndpointsHow the database is named
GET /v1/status, POST /v1/setup, POST /v1/refresh, /v1/labels, /v1/masks, /v1/policyThe header or ?source=.
POST /v1/connectname in the body, to connect one more.
POST /v1/runssource in the body, or the header.
/v1/runs/:id/..., approvals, undoNothing: a run belongs to one database and every call on it goes there.
GET /v1/runsEvery database’s runs; ?source=<name> or the header for one’s.
Keys, webhooks, events, single sign-onThe 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.

the rules of the database connected as shop
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.

an error
HTTP/1.1 409 Conflict{"error": {"message": "the run's changes changed since they were shown: look at them again before deciding", "code": "stale"}}
StatusMeans
400The request is wrong: a missing or bad field. Fix it; sending it again fails the same way.
401No token, the wrong kind, or one that isn’t valid.
403The token is right but may not do this: a run that is over, a person not allowed.
404No such run, key, webhook or database.
409The state doesn’t allow it: a conflict, a stale version, a used link, something already there.
410A link expired.
429A rate limit. Wait and try again.
500The gateway’s own store failed. The message says the gateway’s store: ....
502The engine couldn’t be reached, or your identity provider couldn’t.
503No 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

CodeStatusFromMeaning
act_as400POST /v1/runsact_as is wrong: a role or settings the gateway can’t take.
attach400POST /v1/connectThe engine’s attach didn’t go through. The message holds what it said.
attached409POST /v1/connectThis gateway has a database already, or the name is taken.
bad_code401POST /console/setupThe setup code isn’t right, or it expired.
bad_key401POST /console/loginThat developer key isn’t valid.
cascade409undoUndoing would change rows besides the run’s own. Preview it, then undo with allow_cascade.
children_live409proposeFrom 0.4.0. The run has a child run still live.
depth400POST /v1/runs/:id/childrenFrom 0.4.0. A child run can’t have children of its own.
evidence400proposeFrom 0.4.0. An evidence item is malformed, or there are more than 50.
changed_since409undoRows the run wrote have changed since. Nothing was undone. Undo with skip_changed to leave them.
confirm400POST /v1/connectOver 1,000,000 rows. Send yes: true to go on. The message gives the sizes.
conflict409propose, approve, POST /v1/approveRows the run changed were changed in the database too. Nothing was written. With conflicts for a developer key.
disconnecting409DELETE /v1/sources/:name, POST /v1/connectThat database is being disconnected.
expired409, 403, 410propose; a run’s SQL, MCP, MongoDB; /v1/approveThe run’s time ran out (409 on propose, 403 for its agent), or the link expired (410).
forbidden_sql400a run’s SQLA statement a run can’t send: it works inside its own world and reaches the database only through propose.
held409proposeThis run’s merge is waiting for a person already.
invalid401/v1/approveThe approval or undo link isn’t valid.
mongo_tool400, 409POST /v1/runs/:id/mongoA MongoDB tool was given what it doesn’t take (400), or a document kept changing under an update (409).
no_engine503anything that needs the engineNo engine yet: connect a database first.
no_leader503any request, with several gatewaysNo gateway leads right now. Retry-After: 5.
no_source404, 400anything that names a databaseNo database is connected under that name (404), or the name isn’t a valid one (400).
no_sso404the sign-in endpointsSingle sign-on isn’t set up here.
no_undo_record409undoThe run merged before the gateway kept merge ids, or the engine is older than 0.5.0.
not_admin403GET /v1/console/meSigned in, and may approve, but isn’t on GATEWAY_OIDC_ADMINS. With approvals, where to go.
not_allowed403sign-inThe person isn’t on GATEWAY_OIDC_ALLOW.
not_yours403/v1/approveThe link was made for another approver than the person signed in.
origin403console and sign-in callsNot from the gateway’s own pages: the console’s header is missing, or Origin isn’t GATEWAY_PUBLIC_URL.
reads_changed409approve, POST /v1/approveWhat the run read changed since it began, or was too much to check. Nothing was merged. With reasons.
run_changed409approve, reject, discard, the reviewer, the sweeperFrom 0.4.0. Another decision on the run came first. With status, what it is now.
runs_live409DELETE /v1/sources/:nameRuns of that database are still in progress. With runs, how many.
scope400POST /v1/runs/:id/childrenFrom 0.4.0. The child’s may_change goes past its parent’s.
set_up409POST /console/setupThe gateway is set up already: sign in with a developer key.
setup_locked403POST /console/setupToo many wrong setup codes. Make a new one with chronos-gateway setup-code.
sign_in401/v1/approve, the sign-in and console endpointsA person must sign in first. With login, where.
sso_person403GET /sso/callbackThe ID token doesn’t say who the person is.
sso_provider502sign-inYour identity provider couldn’t be reached.
sso_token401GET /sso/callbackThe ID token was refused.
stale409approveThe run changed after the person saw it (version).
tenant_column400POST /v1/runsNo attached table has that tenant column. The message lists the tables and their columns.
too_many_proposes429proposePast GATEWAY_RUN_PROPOSES_PER_MINUTE.
too_many_runs429POST /v1/runsThe tenant has had GATEWAY_RUNS_PER_HOUR runs in the last hour.
undo_not_ready409undoThe gateway’s role has no table to keep what merges write. With sql, the statements to run once.
used409/v1/approveThe link was already used.
window_passed409approve, POST /v1/approve, Chronos CloudFrom 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_target409approve, POST /v1/approve, Chronos CloudFrom 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_lost409any call on a runThe run’s copy was lost with a crashed engine. The run is now failed. Start a new run.
a run status (merged, rejected, ...)409, 403propose, reject; a run’s SQL, MCP, MongoDBThe 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

CallWhoAnswers
GET /healthnone{"ok": true}, for load balancers. Each gateway answers it itself, a follower too.
GET /v1/statuskeyThe gateway’s state, for the database the request names.
GET /v1/status
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}
FieldMeaning
engineconfigured: a database is connected. healthy: the engine answers.
haAlone: {shared: false, role: "leader"}. Sharing a store: {shared: true, node, role: "leader" | "follower", leader: {node, url, expires}}.
extensionsWhat is built in beside the gateway itself. Empty in the open gateway.
source, sourcesThe database this answer is about, and all of them: {name, kind, tables, tenant_column}.
attachedThe engine’s own account of what is attached, undo.ready and capabilities included. Null before a database is connected.
policyThe merge policy’s name and its rules now.
runsRun counts by status.
webhooksDeliveries pending and failed.
cloudNull 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

CallWhoBodyAnswers
POST /v1/connect/checkkeyurl, schema (public)What is in the database. Reads the catalog only; the URL is kept nowhere.
POST /v1/connectkeyurl, tables, tenant_column, yes, name, fields (MongoDB){ok, tables, tenant_column, source, output}
GET /v1/sourceskey{sources: [{name, kind, tables, tenant_column}]}
DELETE /v1/sources/:namekey?discard_runs=true{ok, name, discarded}
POST /v1/setupkeytenant_column{ok, policy, rules}: the merge policy made, or set to the rules again
POST /v1/refreshkeyThe 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}.

FieldMeaning
sourcepostgres, mysql (with flavor: mysql or mariadb) or mongodb.
tablesEach {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_candidatesColumns that look like a tenant column: {column, tables, of}.
role_sqlThe statements that make a least-privilege role for the gateway. A mongosh script beside MongoDB.
warningsFor 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.
look first
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

FieldMeaning
urlThe 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.
tablesThe tables, or collections, agents may work on. Only these are copied.
tenant_columnThe column that names each row’s tenant. Recorded, so a run can give just the value.
yestrue to attach more than 1,000,000 rows.
nameConnects one more database under this name. Kept in <data>/sources/<name>/. Not with an engine run elsewhere (CHRONOS_ENGINE_URL).
fieldsBeside MongoDB: the fields kept as columns. See MongoDB tools.
attach
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, with error.runs. ?discard_runs=true discards 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: 409 disconnecting.

Runs

CallWhoBody or queryAnswers
POST /v1/runskeysee below201: the run, with its token
GET /v1/runskey?status=&limit=&source= (limit 50, 500 at most){runs}
GET /v1/runs/:idkey or runThe run
DELETE /v1/runs/:idkey{"status": "discarded"}
POST /v1/runs/:id/childrenkeyintent, may_change, max_rows, max_deletes, row_rules, ttl_seconds, run_id, metaFrom 0.4.0. 201: a child run, with its own token and parent. See Child runs
PATCH /v1/runs/:id/metakey or runan object of keys (null removes one)From 0.4.0. {id, meta}, at most 64 KB

POST /v1/runs

FieldMeaning
tenantRequired. Whose rows the run may touch: {"org_id": 42}, "org_id = 42", or just 42 when tenant_column was set at connect.
intentWhat the run is for. Shown to approvers and in Slack.
end_userWho it acts for.
ttl_secondsA shorter life than GATEWAY_RUN_TTL. Never longer.
metaAny JSON you want kept with the run.
run_idYour own id for the run, kept on its world.
sourceThe database it works beside. Without it: the header’s, else default.
may_change, max_rows, max_deletesWhat the run declares about its change, kept on its world with the intent.
row_rulesConditions 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_asPostgres 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.
start a run
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

FieldMeaning
id, world, agentThe run’s id, and the engine world and agent behind it.
statusopen, held, merged, conflict, rejected, undone, partly_undone, expired, discarded or failed.
tenant{"column", "value"}.
intent, end_user, metaAs given.
created, updated, expires, hold_expiresTimes. hold_expires is set while it is held.
outcomeThe last answer about its merge: rows merged, reasons held, conflicts, who approved, the reviewer’s verdict, the error.
mergesThe ids of the merges that wrote it to the database: what an undo names.
parent, children, evidenceFrom 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}).
sourceThe database it works beside.
sql_url, mcp_urlWhere 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.

CallBodyAnswers
POST /v1/runs/:id/sqlsql, paramsThe engine’s {results: [{command, columns, types, rows}]}. Rows past GATEWAY_RUN_MAX_ROWS are cut and marked truncated.
POST /v1/runs/:id/mcpone JSON-RPC messageMCP over HTTP, as the run’s agent.
POST /v1/runs/:id/mongotool, argumentsOne of MongoDB’s own tools, beside MongoDB. See MongoDB tools.
SQL in the run’s world
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

CallWhoBody or queryAnswers
GET /v1/runs/:id/changeskey or run?limit= (200, 2,000 at most){status, version, total, summary, tables, changes, more, reasons}
POST /v1/runs/:id/proposekey or runconfirm_deletes, evidence (from 0.4.0: [{kind, uri, sha256, note}], at most 50), and to settle conflicts by_columns, resolve, rows, targetsee below
GET /v1/runs/:id/changes
{  "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 answersMeaning
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 conflictsRows 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 expiredThe run’s time ran out first.
409 heldIt is waiting for a person already.
409 children_liveFrom 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 codeIt is merged, rejected or otherwise over.
429 too_many_proposesPast GATEWAY_RUN_PROPOSES_PER_MINUTE. Each propose locks and compares rows in your database.
propose
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

CallWhoBodyAnswers
POST /v1/runs/:id/approvekeyversion, 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/rejectkeyreason, by{"status": "rejected"}
POST /v1/runs/:id/undokeypreview, 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: 409 stale.
  • by: who decided, kept in the outcome and sent in merge.landed.
  • only_tables (["leads"]) or only_keys (["leads/7"]): approve a part. The rest is left in the run as it was, to approve or reject after. merge.landed says partial.
  • 409 reads_changed, with reasons: 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: true merges without that check. The rows it changed are still checked. merge.landed and the outcome say reads_checked: false.
  • 409 conflict if rows still conflict.
  • 409 window_passed, with strict: 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_tables or only_keys on one are refused 400.
approve what was seen
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, 409 window_passed. Proposed again into a conflict, it keeps its window.
  • If the engine’s EXPLAIN MERGE fails 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, 409 strict_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).

FieldMeaning
previewtrue 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_changedRows 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_cascadeAn 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).
byWho 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.

preview, then 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.

FieldDoes
by_columns: trueA 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.
rowsSingle rows: {"orders/7": "ours" | "theirs" | "delete" | {the row to keep}}.
resolve, without by_columnsWhole 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.
targetThe target a preview of the merge gave (the run’s MCP merge_preview), so rows settle against the data as that preview saw it.
propose again, settled
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

CallWhoBodyAnswers
POST /v1/runs/:id/approvalskeyend_user, expires_in, approver{token, version, approver, expires, link, widget: {script, html}} for a held run
GET /v1/approveapprovalThe change, in words
POST /v1/approveapprovaldecision, reason, skip_read_check, skip_changedThe run’s new status
  • link is 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.
  • widget holds a script URL and an html tag for your own page.
  • expires_in: seconds, from 1 to GATEWAY_APPROVAL_TTL. Without it: GATEWAY_APPROVAL_TTL. end_user: who it is for; without it, the run’s.
  • approver: an email on GATEWAY_OIDC_ALLOW, with single sign-on only. Only that person, signed in, can see or decide it.
the widget
<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.

AnswerMeaning
401 invalidThe link isn’t valid.
401 sign_in, with loginThe link was made for an approver, or GATEWAY_OIDC_REQUIRE=on, and nobody is signed in.
403 not_yoursSomeone else is signed in than the link was made for.
409 usedAlready decided, or already undone.
410 expiredThe link’s time ran out. Make a new one.
409 reads_changedAs 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 conflictRows 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_readyAn 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.

CallTakesAnswers
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/callbackyour provider’s answerThe 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 /approvalsA 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/approvalAn 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

CallWhoBodyAnswers
GET /v1/policykey{name, rules, text, source, engine, known}
PUT /v1/policykeyrules: the whole setAs 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.
  • rules is the rules as an object; text the same as the engine’s text.
  • source is set (by PUT, kept in the gateway’s store) or config (GATEWAY_POLICY_RULES). Rules that were set win over the setting.
  • engine is the policy as the engine holds it, or null. known lists every rule’s name.
  • PUT replaces the whole set: a rule left out ends, and the answer names it in ended. To change one rule, GET the rules, change it, and PUT them all.
replace the rules
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

CallWhoBodyAnswers
GET, PUT /v1/labelskey{tables: {<table>: {name, plural, title, columns: {<col>: label | null}}}}The labels
GET, PUT /v1/maskskey{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.
labels
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}}}}'
masks
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

CallWhoBody or queryAnswers
POST /v1/webhookskeyurl, events (none: all), format (json or slack)201 {id, url, events, format, created, secret}: the secret only now
GET /v1/webhookskey{webhooks: [{id, url, events, format, created}]}
DELETE /v1/webhooks/:idkey{"ok": true}; 404 if there is none
GET /v1/effectskey?status= (pending, delivered or dead), limitFrom 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/eventskey?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

CallWhoBodyAnswers
GET /v1/keyskey{keys: [{id, name, created, revoked}]}
POST /v1/keyskeyname: what uses it (backend, ci), at most 100 characters201 {id, name, key}: the key only now
DELETE /v1/keys/:idkey{"ok": true}; 404 if there is none
make a key
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.

CallBodyAnswers
POST /console/loginkeySets the cookie. 401 bad_key; 403 origin without the console’s header.
POST /console/setupcode (from the log), nameWhile 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

PathIs
GET /consoleThe console. It signs in.
GET /approveThe page an approval or undo link opens. Its token is after #.
GET /approvalsThe held changes, for people signed in (single sign-on).
GET /widget.jsThe approval widget’s script, for your own pages.
Gateway API · Chronos