Skip to content
Ankole

Console API reference

For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/console-api/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.

This page is the REST reference for the Console API: its authentication gate, the routes under /api/v1, and the permission action for each route.

The decisive property, stated up front: the Console API is stateless and bearer-authenticated, and it re-confirms the caller is still an active admin on every request. There is no session cookie doing the work for you, and a disabled admin stops working immediately, not on the next login.

Every route under /api/v1 runs through the :console_api pipeline and the RequireConsoleAccessToken plug. The plug runs three independent checks, all required:

  1. a well-formed Authorization: Bearer header;
  2. a console JWT that verifies;
  3. the principal the JWT names is still an active admin.

On success it stashes the principal and claims as conn assigns for the downstream policy checks; on any failure it halts with 401. This is the per-request, cookie-free equivalent of what session plus CSRF do for the browser surfaces. There is no second, weaker path into these routes.

The configuration surfaces

Configuration is organized by what is being configured, not by controller. The surfaces an operator actually drives:

Providers and model access

A running agent needs a model behind it. The operator wires that through AIGateway’s provider surface and the agent’s model profiles:

Method Path Purpose
GET /ai-gateway/provider-kinds List the provider kinds this deployment instance can configure
GET /ai-gateway/providers List configured providers
GET /ai-gateway/providers/:provider_id Read one provider and its credential-pool status
PUT /ai-gateway/providers/:provider_id Create or replace a provider
DELETE /ai-gateway/providers/:provider_id Remove a provider
POST /ai-gateway/providers/:provider_id/credentials Add a credential-pool member
PUT /ai-gateway/providers/:provider_id/credentials/:credential_id Update or reauthenticate a pool member
DELETE /ai-gateway/providers/:provider_id/credentials/:credential_id Remove a pool member
PUT /ai-gateway/providers/:provider_id/credential-pool/strategy Set the pool selection strategy
POST /ai-gateway/providers/:provider_id/chatgpt-login Start one ChatGPT device or browser login
POST /ai-gateway/providers/:provider_id/chatgpt-login/poll Poll one device login
POST /ai-gateway/providers/:provider_id/chatgpt-login/browser-callback Complete the browser-paste fallback
POST /ai-gateway/providers/:provider_id/chatgpt-enterprise-credentials Add an Enterprise access token
GET /agents/:agent_uid/model-profiles List an agent’s model profiles
PUT /agents/:agent_uid/model-profiles/:profile Create or replace a profile
DELETE /agents/:agent_uid/model-profiles/:profile Remove a profile

Provider credentials live as encrypted pool members in the control plane, never in the agent’s environment. A model profile binds an agent to a provider and model. AIGateway selects a healthy member inside that provider, and the projection returns only safe account facts, health, rate-limit data, and usage.

Agents and their capabilities

The agent is the unit an operator configures everything else against:

Method Path Purpose
GET /agents List agents
POST /agents Create an agent
GET /agents/:agent_uid Read one agent
PATCH /agents/:agent_uid Update an agent
POST /agents/:agent_uid/enable Re-enable a disabled agent
DELETE /agents/:agent_uid Disable an active agent, or permanently delete a disabled one

Signal routing rules

A signal routing rule (Signal Binding in the API schema) connects a provider adapter to an Agent so shared work can reach it:

Method Path Purpose
GET /signal-adapters List adapters this deployment instance declared
GET /signal-bindings List routing rules; ?agent= filters to one Agent
PUT /agents/:agent_uid/signal-bindings/:adapter_id/:binding_name Create or replace a routing rule
PATCH /agents/:agent_uid/signal-bindings/:binding_name Update a routing rule
DELETE /agents/:agent_uid/signal-bindings/:binding_name Remove a routing rule
GET /signal-channels/:channel_id/standing-orders Read one channel’s standing orders
PUT /signal-channels/:channel_id/standing-orders Replace one channel’s standing orders

Disabling a binding stops new signals from waking its agent without deleting the binding.

Agent Library capabilities

The Agent Library is what an agent can do — its plugins and skills. The Console exposes two scopes: a global default, and per-agent overrides:

Method Path Purpose
GET /agent-library/capabilities List global library capabilities
PUT /agent-library/agent-plugins/:id Set a plugin’s global default state
PUT /agent-library/skills/:id Set a skill’s global default state
GET /agents/:agent_uid/library-capabilities List an agent’s effective capabilities
PUT /agents/:agent_uid/library-capabilities/agent-plugins/:id Override a plugin for one agent
PUT /agents/:agent_uid/library-capabilities/skills/:id Override a skill for one agent
GET /agents/:agent_uid/library-documents List library documents for an agent
PUT /agents/:agent_uid/library-documents/:document_kind Set a library document
GET /agents/:agent_uid/skill-lessons List active and retired Skill lessons
POST /agents/:agent_uid/skill-lessons Add a human Skill lesson to an enabled Skill
POST /agents/:agent_uid/skill-lessons/:lesson_id/retire Retire a Skill lesson

A capability is enabled globally, then narrowed or widened per agent. Skill lessons give one Agent additional process guidance without changing the Skill source. The list includes evidence and retirement history. A retired lesson stops being delivered, and Dreaming keeps human-retired content on its never-relearn list. See Skill lessons for the lifecycle and limits.

Environment variables (WorkerEnv)

An Agent Computer Worker can need environment variables such as API keys and tokens. The Console calls this feature Environment variables. The API keeps WorkerEnv as its resource name:

Method Path Purpose
GET /worker-envs List named WorkerEnv entries
GET /worker-envs/:name Read one entry (metadata, not plaintext)
PUT /worker-envs/:name Create or update an entry
DELETE /worker-envs/:name Remove an entry
GET /agents/:agent_uid/worker-envs List entries attached to an agent
PUT /agents/:agent_uid/worker-envs/:name Attach an entry to an agent
DELETE /agents/:agent_uid/worker-envs/:name Detach an entry
POST /worker-envs/:name/decryptions Decrypt one entry (audited, privileged)

Decryption is a separate, audited operation. Listing and reading return metadata, not the secret value. A worker receives its environment only when a turn starts; changes take effect on the next turn, not one already running.

Control Plane Plugins

Method Path Purpose
GET /control-plane-plugins List Control Plane Plugins and their state
PUT /control-plane-plugins Enable or disable plugins

Control Plane Plugins are the first-party extensions that change what the control plane itself does, such as a signals adapter.

Identity providers and AppConfiguration

Method Path Purpose
GET /identity-provider-adapters List the IdP adapters this deployment instance supports
GET /identity-providers List configured identity providers
PUT /identity-providers/:provider_id Create or replace an IdP
POST /identity-providers/:provider_id/sync-runs Sync directory groups from an IdP
GET /app-configurations List operator-managed configuration keys
PUT /app-configurations/:key Set a configuration value
POST /app-configurations/:key/decryptions Decrypt one secret configuration value

AppConfiguration is for operator-managed settings — the declared Ankole.AppConfigure keys. Bootstrap configuration (process-startup facts and credentials) stays out of it, in environment or secret mounts, as the project boundaries require.

The read surfaces

Alongside configuration, the Console is the observability path for the rest of the system — each subsystem already documented has its read surface here:

  • Agents in flight: /agents/:agent_uid/sessions, per-Agent cron schedule and checkback management; the list endpoints are installation-wide with an agent filter.
  • Workers: /agent-computer-workers, with file upload, move, and listing per worker.
  • Jobs: /background-agent-jobs (list, read, cancel).
  • AI activity: /ai-gateway/conversations, with messages per conversation.
  • Principals and AuthZ: /principals, /principal-groups, /permission-grants — the permission model from the Principal and AuthZ page.

A note on what is not here

The /webhooks/* and /api/v1/ai-gateway/* routes are deliberately not under console_api. Webhook ingress authenticates the provider, not an admin; the AIGateway runtime API authenticates an agent or admin token for live AI calls. The Console is the operator’s configuration surface, and it is the only surface that trusts an admin bearer token to change how the deployment instance behaves.

Next steps