example.com with your deployment domain. The public demo API is available at https://api.demo.acornops.dev/api/v1 for evaluation. Browser traffic uses a cookie-backed session. In default deployments, the management console host also proxies /api to the control plane so browser auth callbacks and session cookies stay on the management console origin.
Use this page to understand how the API is organized. Use the API reference sidebar for individual endpoint parameters, request bodies, response schemas, and generated examples.
If you are building a bot, workflow adapter, or custom client, start with Integrations for the supported auth and event patterns before wiring endpoint calls.
Auth model
The browser API uses aSameSite=Lax session cookie. Mutating requests that carry a session cookie must also send the CSRF token in x-csrf-token; password login, signup, email verification, verification resend, forgot password, and reset password require the same CSRF token before a session exists.
Default production installs support OIDC plus username/password login, with self-service signup disabled and password reset enabled. When self-service password signup is enabled, email verification is required unless an operator explicitly allows unverified signup for a private deployment.
Runtime service-to-service calls use separate bearer tokens and are not part of
the public browser API. Installed external integration clients are a narrow
exception: account-link lifecycle, explicitly documented linked-user reads,
Workflow session operations, and webhook route connect/status accept a
registered client bearer token and derive the client from
EXTERNAL_INTEGRATION_CLIENTS_JSON. Workflow writes require an explicit
deployment client ceiling, user-approved grant, and linked-user role; the
default remains read-only.
Endpoint families
The API reference is grouped by these areas:
Admin endpoints are documented separately in the Admin API reference. They use the
/admin/v1 route namespace and are for operator administration, not normal browser workflows.
Integration boundaries
AcornOps v1 does not expose a public PAT or broad bot service-account credential for the control-plane API. External integration client bearer tokens are only for external integration link lifecycle, linked-user bot endpoints, and external webhook route connect/status. They must not be treated as authority for general workspace actions. Deployments may explicitly grant a linked external integrationcreate_read_write_runs so it can request write-capable troubleshooting runs and active read-write or approval-gated Workflows. After explicit confirmation from the linked external user, the exact originating integration link/client may decide troubleshooting approvals plus Workflow pre-step and runtime write approvals. Browser-created, other-link/client, scheduled, and system-triggered approvals remain unavailable to external credentials.
Internal service tokens such as ORCH_SERVICE_TOKEN, EXECUTION_ENGINE_DISPATCH_TOKEN, and LLM_GATEWAY_ADMIN_TOKEN are platform credentials. They are not public integration credentials.
Execution-engine and LLM-gateway runtime APIs are internal platform surfaces. External integrations should use webhooks, run events, the public control-plane API, and the management console.
Workflow notes
Password auth uses enumeration-safe response patterns for verification resend and reset request flows. Password reset consumes a single-use token, updates the password, verifies the email, revokes existing sessions, and does not create a new session. Workspace role responses include server-owned permission fields. Clients should use those fields rather than copying role or capability logic. Kubernetes registration returns the cluster record, its one-time AgentK key, and install instructions; AgentK key rotation returns a replacement key. Virtual-machine registration accepts a read-only host policy by default or a read-write policy scoped to exact restartable systemd services, then returns the normalized VM record and a 15-minute, single-use AgentV enrollment command. VM records also expose the effective run permission mode, optional VM override, and policy source. AgentV’s durable credential and enrollment-bound host policy are exchanged directly with the root installer and are never exposed as editable command arguments. VM repair commands reuse the credential and policy already on the host, while credential replacement returns another short-lived enrollment command and leaves the active credential unchanged until cutover succeeds. Run events are replayable through the events endpoint and streamable through server-sent events. Current event types include run lifecycle, assistant message, token delta, provider reasoning summary, tool call, write approval, failure, cancellation, and completion events. Reasoning summary events contain provider-generated summaries only, not raw chain-of-thought. That full event detail is available to browser sessions. Linked external integrations receive bounded run projections and sanitized event payloads: lifecycle state plus safe approval metadata, without prompts, reasoning, token deltas, raw tool arguments, or tool results. Only the exact originating link/client receives final assistant output from the run detail endpoint. Approval lists and decision responses likewise expose only bounded control metadata to linked integrations; executable arguments, tool references and digests, actor identifiers, continuations, and tool results are omitted. Multi-step Workflow executions also expose a workspace-readable sanitized execution DTO and aggregate replayable SSE stream. The aggregate stream carries execution status, step/run discovery, public run events, approval references, safe output metadata, and terminal state. Resume it withLast-Event-ID or
after. Sensitive snapshots, context, compiled claims, continuation state, and
integration provenance identifiers are excluded.
Write approval decisions are first-writer-wins. Repeating the same decision is idempotent, while a conflicting decision or a decision that arrives after the approval expiry returns conflict with the current approval state.
Webhook events and delivery jobs are durable, but delivery is at least once and
is not globally ordered. Verify AcornOps-Signature using
timestamp + "." + raw_json_body, signed with HMAC-SHA256 and encoded as
v1=<hex>.