Reference

HTTP API

The complete current HTTP surface for agents and project owners.

Conventions

Use your instance’s origin as the base URL. Send JSON bodies with Content-Type: application/json. Responses are JSON with Cache-Control: no-store. These are unversioned preview routes.

Agent means a project Bearer key. Owner means the signed-in owner; localhost supplies a development identity. Check and status routes support CORS preflight with OPTIONS returning 204. CORS does not make public exposure of a project key safe.

Endpoint index

Method and path	Auth	Purpose
`POST /api/check`	Agent	Evaluate and log an action
`GET /api/confirmations/:id/status`	Agent	Poll a review
`POST /api/projects/bootstrap`	Owner	Create or load a project
`POST /api/api-keys/rotate`	Owner	Revoke active keys and issue a new key
`GET /api/policy`	Owner	Read policy
`PATCH /api/policy`	Owner	Replace the complete policy
`GET /api/logs`	Owner	Query audit records
`GET /api/confirmations`	Owner	List reviews
`GET /api/confirmations/:id`	Owner	Read a review and action metadata
`POST /api/confirmations/:id/resolve`	Owner	Approve or deny one review

Check request and response

The check guide covers request fields, limits, and idempotency. Legacy body-based key authentication remains accepted by the check route; new clients should send the header.

Selected response fields

{
  "decision": "requires_human",
  "reason": "Action \"submit\" requires human confirmation for this project.",
  "confirmation_id": "<confirmation-id>",
  "confirmation_url": "http://localhost:3000/dashboard/confirmations/<confirmation-id>",
  "data_type_detected": null,
  "check_id": "<check-id>"
}

Field	Meaning
decision	approved, denied, or requires_human.
reason	Optional explanation provided by a matching rule.
data_type_detected	One category or null.
check_id	Audit-record ID.
confirmation_id / confirmation_url	Present for review checks. The current URL leads to the demo dashboard.
idempotent_replay	true when an existing check was returned.
log	id, timestamp, project_id, action_type, destination, task_context, data_type_detected, decision, and reason. No raw data.

Management shapes

The paths in this table are relative to /api. Success is HTTP 200 unless noted.

Endpoint	Request	Response
POST /projects/bootstrap	Optional {"name":"My project"}	201 on creation or 200 on reload: project, policy, api_keys; raw api_key on creation only.
POST /api-keys/rotate	No body required.	api_key and api_keys metadata.
GET /policy	No body.	{ policy: { allowlistedDomains, flaggedTypes, requiresHumanActions } }
PATCH /policy	All three arrays.	{ policy: updatedPolicy }
GET /logs	decision, from, to, before, limit.	{ logs: [...], next_before: timestampOrNull }
GET /confirmations	status: pending/approved/denied. limit defaults to 100, maximum 200.	{ confirmations: [...] }
GET /confirmations/:id	The confirmation ID, not the check ID.	{ confirmation: { id, log_id, status, created_at, resolved_at, action_type, destination, task_context, data_type_detected, reason } }
POST /confirmations/:id/resolve	{"decision":"approved"} or {"decision":"denied"}	{ confirmation: resolvedRecord }
GET /confirmations/:id/status	Agent key, no body.	{ confirmation_id, status, decision, resolved_at }

Errors and status codes

Error envelope

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be valid JSON."
  }
}

HTTP / error code	Meaning	Next step
400 · invalid_request	Invalid JSON, wrong field type, unsupported filter/rule, or a limit violation.	Correct the request before retrying.
401 · invalid_api_key	Missing, malformed, unknown, or revoked key.	Use an active key for this instance.
401 · authentication_required	Owner endpoint has no authenticated viewer.	Use the owner session or local walkthrough.
404 · project_not_initialized	Owner has no project.	Bootstrap first.
404 · not_found	No matching review in this project.	Check the ID and project.
409 · already_resolved	The opposite outcome is already recorded.	Respect the existing resolution.
429 · rate_limit_exceeded	Check quota exhausted.	Wait Retry-After seconds; reuse the same action key.
500 · internal_error	The operation failed on the server.	Keep blocked; inspect logs and cautiously retry transient failures.

Hosting errors can have a different body, including an HTML sign-in page. Invalid JSON or an unexpected response is a failed check, not permission to proceed.

Limits and unsupported operations

Check quota: 120 new evaluations per project per minute. Character limits: action 64; data 20,000; destination 2,048; task context 1,000; idempotency key 200. See policy limits for configuration sizes.

No public run-execution, webhook, project-delete, log-delete, review-cancel, team-management, inference, or file-upload endpoint is implemented. Future versions may change this preview contract.

Conventions#

Endpoint index#

Check request and response#

Management shapes#