Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.acornops.dev/llms.txt

Use this file to discover all available pages before exploring further.

The public API is served by the control plane under: 
https://acornops.dev/api/v1
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 https://console.acornops.dev. Runtime traffic between platform services uses separate internal credentials and should stay on private network paths.

​
Auth

FlowEndpoint
OIDC loginGET /api/v1/auth/oidc/login?return_to=<management-console-url>
OIDC callbackGET /api/v1/auth/oidc/callback
Password loginPOST /api/v1/auth/password/login
Password signupPOST /api/v1/auth/password/signup
LogoutPOST /api/v1/auth/logout
Current userGET /api/v1/me
Password auth is deployment-dependent and is disabled by default for production-style installs. Dev-login is for non-production use only. For default production settings, the OIDC callback URL registered with the provider is https://console.acornops.dev/api/v1/auth/oidc/callback. If the deployment overrides the redirect URI, register the exact override value.

​
Workspaces and members

Workspaces group members, clusters, sessions, runs, tools, MCP servers, and webhooks. Common workspace endpoints:
  • GET /api/v1/workspaces
  • POST /api/v1/workspaces
  • DELETE /api/v1/workspaces/{workspaceId}
  • GET /api/v1/workspaces/{workspaceId}/members
  • POST /api/v1/workspaces/{workspaceId}/members
  • PATCH /api/v1/workspaces/{workspaceId}/members/{userId}
  • DELETE /api/v1/workspaces/{workspaceId}/members/{userId}
  • GET /api/v1/workspaces/{workspaceId}/invitations
  • POST /api/v1/workspaces/{workspaceId}/invitations
  • DELETE /api/v1/workspaces/{workspaceId}/invitations/{invitationId}
  • GET /api/v1/workspace-invitations/{token}
  • POST /api/v1/workspace-invitations/{token}/accept
Invitation tokens are returned once on creation. The control plane stores token hashes, not raw invitation tokens.

​
Roles

RoleMain capabilities
ownerFull workspace control, owner management, clusters, tools, MCP servers, keys, read-only and read-write runs
adminManage non-owner members, clusters, tools, MCP servers, keys, read-only and read-write runs
operatorCreate sessions, create read-only runs, read allowed logs, cancel runs
viewerRead workspace, cluster, session, and run data
Workspace and catalog responses include server-owned permission fields. Clients should use those fields rather than copying role logic.

​
Clusters

Cluster endpoints:
  • GET /api/v1/workspaces/{workspaceId}/clusters
  • GET /api/v1/workspaces/{workspaceId}/clusters/{clusterId}
  • POST /api/v1/workspaces/{workspaceId}/clusters/register
  • PATCH /api/v1/workspaces/{workspaceId}/clusters/{clusterId}
  • DELETE /api/v1/workspaces/{workspaceId}/clusters/{clusterId}
  • POST /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/rotate-agent-key
  • GET /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/pods/{namespace}/{podName}/logs
Registration returns the cluster, a one-time agent key, and install instructions. Agent-key rotation returns a replacement key and updated install instructions.

​
Sessions and runs

Session and run endpoints:
  • POST /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/sessions
  • GET /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/sessions
  • DELETE /api/v1/sessions/{sessionId}
  • GET /api/v1/sessions/{sessionId}/messages
  • POST /api/v1/sessions/{sessionId}/messages
  • GET /api/v1/runs/{runId}
  • GET /api/v1/runs/{runId}/events
  • GET /api/v1/runs/{runId}/stream
  • POST /api/v1/runs/{runId}/cancel
Posting a session message accepts content, toolAccessMode, and clientMessageId, then returns message_id and run_id. Run events are replayable through the events endpoint and streamable through server-sent events. Events include a sequence number, timestamp, type, and payload. Current event types include run lifecycle, assistant message, token delta, tool-call, failure, cancellation, and completion events.

​
Tools and MCP servers

Tool catalog and MCP endpoints:
  • GET /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/tools/catalog
  • PATCH /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/tools/{toolName}
  • GET /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/mcp/servers
  • POST /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/mcp/servers
  • PATCH /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/mcp/servers/{serverId}
  • DELETE /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/mcp/servers/{serverId}
  • POST /api/v1/workspaces/{workspaceId}/clusters/{clusterId}/mcp/servers/{serverId}/test-connection
Builtin Kubernetes tools come from the k8s agent. Remote MCP servers are discovery-first: the gateway discovers available tools with tools/list, then calls tools with tools/call during authorized runs.

​
Webhooks

Webhook management endpoints:
  • GET /api/v1/workspaces/{workspaceId}/webhooks
  • POST /api/v1/workspaces/{workspaceId}/webhooks
  • GET /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}
  • PATCH /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}
  • DELETE /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}
  • GET /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}/history
Webhook delivery is best-effort. Each delivery includes:
  • AcornOps-Event-Id
  • AcornOps-Event-Type
  • AcornOps-Timestamp
  • AcornOps-Signature
The signature input is timestamp + "." + raw_json_body, signed with HMAC-SHA256 and encoded as v1=<hex>.