Start here if you want to call the IDKMesh Control Tower without reading server code. This page is a map; each topic links to the page that owns it.
The Control Tower API is a local, loopback, read and inspect HTTP API at
/api/v1/. It reports capability status, retained run evidence, the
Product Spine read model (runs, attempts, work units, projects, connection
metadata), operational metrics, and an event feed. It grants no write
authority: it does not record human decisions, dispatch work, change canonical
state, push Git or merge. It is not a multi-user or network service.
/api/v1/ route needs the local session token, sent only in the
X-IDKMesh-UI-Token header. /healthz and /readyz need no token and expose
no project state.http destination so the token
cannot be sent elsewhere, never follows redirects, and keeps the token out of
repr() and exception messages.The authoritative list is the OpenAPI document (see Download the OpenAPI definition); the CLI and HTTP quick reference shows examples.
| Route | Purpose | Python client |
|---|---|---|
GET /api/v1/status |
capability status and the limits in force | status() |
GET /api/v1/openapi.json |
the running API definition | get_openapi() |
GET /api/v1/metrics |
fixed-cardinality operational metrics | get_metrics() |
POST /api/v1/run-evidence/inspect |
inspect an evidence report you supply | inspect_run_evidence() |
GET /api/v1/runs |
list runs (filters, cursor) | list_runs(), iter_runs() |
GET /api/v1/runs/{run_id} |
one run | get_run() |
GET /api/v1/runs/{run_id}/attempts |
the run’s attempts | get_run_attempts() |
GET /api/v1/runs/{run_id}/evidence |
retained evidence report | get_run_evidence() |
GET /api/v1/work-units, GET /api/v1/work-units/{work_unit_id} |
derived work units | list_work_units(), get_work_unit() |
GET /api/v1/projects/{project_id} |
one project summary | get_project() |
GET /api/v1/connections |
secret-free connector metadata | list_connections() |
GET /api/v1/connections/{connection_id} |
one secret-free connector resource; no probe, secret resolution or provider call | get_connection() |
GET /api/v1/events |
keyset-paginated event list | list_events() |
GET /api/v1/events/stream |
Server-Sent Events | stream_events() |
GET /healthz, GET /readyz |
liveness and readiness, no token | not wrapped |
The definition of the exact build you are talking to is served at
GET /api/v1/openapi.json:
curl -s -H "X-IDKMesh-UI-Token: $IDKMESH_CONTROL_TOWER_TOKEN" \
http://127.0.0.1:8770/api/v1/openapi.json -o control-tower-openapi.json
or ControlTowerClient.get_openapi(). A reviewed, versioned snapshot of the
public surface is also tracked in the repository as
openapi.yaml.
When the two differ, the running server is the authority for that build.
Response documents carry a kind and schema_version and validate against the
JSON Schemas in
schemas/. Schemas are
never edited incompatibly in place (see the
compatibility policy).
| Document | Schema file |
|---|---|
| error envelope | idkmesh-api-error-v0.1.schema.json |
| list page | idkmesh-list-v0.1.schema.json |
| event | idkmesh-event-v0.1.schema.json |
| status | idkmesh-control-tower-status-v0.1.schema.json |
| operational metrics | idkmesh-api-operational-metrics-v0.1.schema.json |
| run | idkmesh-control-tower-run-response-v0.1.schema.json |
| run attempts | idkmesh-control-tower-run-attempts-response-v0.1.schema.json |
| run evidence | idkmesh-control-tower-run-evidence-response-v0.1.schema.json |
| evidence inspection | idkmesh-control-tower-inspection-response-v0.1.schema.json |
| work unit | idkmesh-control-tower-work-unit-response-v0.1.schema.json |
| project | idkmesh-control-tower-project-response-v0.1.schema.json |
Last-Event-ID resume; de-duplicate on
event_id.idkmesh.api_client.ControlTowerClient is standard-library only. It enforces a
mandatory timeout, verifies the whole-response X-IDKMesh-Content-Digest and
embedded evidence digests, exposes the request ID on every result, and raises a
stable exception taxonomy. It makes one exchange per call unless you pass a
RetryPolicy, which retries only idempotent reads, with bounded deterministic
backoff. Details and runnable snippets: quickstart.
The URL carries the compatibility version; deprecations are announced in the CHANGELOG with a replacement and an earliest removal. The binding rules and the behaviour changes to check before pinning a beta are in the compatibility, deprecation and migration guide.
The server binds loopback only. The security questions that must be answered before any exposure beyond loopback are in the API threat model (a planning baseline, not a certification).
Do not code against these (tracked on #746):
record_human_decision(...) and a decision route: blocked on
#740 (accountable identity).idkmesh checkout today.