Cloud HTTP API
Lifecycle upload and console endpoints, authentication and response codes.
Base URL and authentication
Use your Cloud website origin followed by /api. Browser endpoints use the signed-in Static Web Apps session and verify workspace membership. Upload uses Authorization: Bearer with a lifecycle token. Do not send database credentials or forge browser identity headers. Direct Function-host access is not the supported production route.
POST /api/agents/sync
Lifecycle bearer token required. Workspace is derived from the token, never from the payload. Accepts exactly the schema-v1 allowlisted fields shown by coldctl agent sync --dry-run. The example is a report from an empty installation; replace its UUID and capturedAtUnixMs with actual values. For populated reports, use the agent serializer rather than constructing job records manually.
{
"schemaVersion": 1,
"agentId": "11111111-1111-4111-8111-111111111111",
"agentVersion": "0.1.0",
"capturedAtUnixMs": 1791200000000,
"sources": [],
"destinations": [],
"policies": [],
"jobs": []
}Upload responses
200: {"accepted":true}. 400: invalid schema, fields, types, counts, size or future clock. 401: invalid token, wrong scope, expiry, revocation or lost creator membership. 409: older/duplicate report or concurrent update; collect again. A gateway may also reject an oversized HTTP body with 413. Network/5xx failures do not roll back or modify local archives.
GET /api/agents?workspaceId=WORKSPACE_ID
Signed-in browser member required. Returns an array of {receivedAt, report}; report uses the upload schema. 401 means no session; 403 means no workspace membership; 400 means invalid/missing workspace ID; 413 means the listing exceeds 100 installations. Response is not cached.
POST /api/tokens
Signed-in workspace member required. Creates a token; plaintext is returned only once. Only lifecycle scope is supported; omitting scope defaults to lifecycle. Existing legacy tokens are not upgraded. Optional expiresAt must be in the future. Store returned secrets securely; do not include them in bug reports.
{
"workspaceId": "WORKSPACE_ID",
"name": "test-installation",
"scope": "lifecycle"
}GET /api/tokens?workspaceId=WORKSPACE_ID
Signed-in workspace member required. Returns id, name, prefix, scope, createdAt, lastUsedAt, expiresAt and revoked. Plaintext tokens are never returned by this list endpoint.
DELETE /api/tokens/TOKEN_ID?workspaceId=WORKSPACE_ID
Signed-in workspace member required. Revokes an existing credential. Success returns {"message":"Token revoked."}. Existing reports remain available; future authentication with the revoked token fails.
Legacy routes
Legacy source, scan, finding, access and overview APIs have been removed. Database metadata comes from agent lifecycle reports. This reference documents the lifecycle integration. No HTTP endpoints start, resume, cancel, restore or delete database data.