AI Control Plane

Agent Integration Guide

Use this surface for discovery, authentication bootstrap, and contract lookup. Operational control-plane pages remain behind login.

Public Endpoints

Controller host: https://controller.limitedview.co.uk

Agent helper manifest: https://controller.limitedview.co.uk/llms.txt

OpenAPI contract: https://controller.limitedview.co.uk/openapi/ai-control-plane-v1.yaml

OIDC discovery: https://controller.limitedview.co.uk/realms/acp/.well-known/openid-configuration

Canonical API server: https://api.limitedview.co.uk

Browser UI runtime uses https://controller.limitedview.co.uk/api in this deployment; external agents should trust the OpenAPI server list rather than scraping UI fetch URLs.

1
Discover
Read the OIDC metadata and OpenAPI contract before making authenticated calls.
2
Authenticate
Use the Keycloak realm metadata to find authorization, token, and JWK endpoints.
3
Integrate
Follow the contract for request IDs, idempotency, auth scopes, and route families.
4
Stay Out of UI Routes
Treat the controller dashboard as a human UI, not as an API surface to scrape or automate blindly.
Quickstart
curl -s https://controller.limitedview.co.uk/realms/acp/.well-known/openid-configuration
curl -s https://controller.limitedview.co.uk/openapi/ai-control-plane-v1.yaml

# After authenticating against the realm above, call the API server declared in the spec.
# Every non-health request should send X-Request-Id.
curl -H "Authorization: Bearer <token>" \
  -H "X-Request-Id: req-example-001" \
  https://api.limitedview.co.uk/tenant/v1/tenant
CLI (acp-agents)

First-class command-line client for the /tenant/v1/agents* and /mgmt/v1/agents* surface. Ships as two entry points: acp-agents (direct) and acp agents … (forwarding shim on the main acp binary). Non-mgmt commands never trigger a whoami probe; mgmt subcommands perform a lazy whoami once per process and enforce per-subcommand role minimums client-side before any request flies.

# Install from the repo (not yet on PyPI)
git clone https://github.com/atabbiruka/ai-control-plane.git
cd ai-control-plane
python -m venv .venv && source .venv/bin/activate
pip install -e .

# Auth — set one of these pairs:
export ACP_BASE_URL="https://api.limitedview.co.uk"
export ACP_API_KEY="acp_sk_…"            # service accounts / agents
# OR
export ACP_BEARER_TOKEN="eyJhbGc…"       # user-scoped from login

# Verify install
acp-agents --help
acp-agents mgmt --help

# Quickstart — register, issue credential, use it
acp-agents register --persona customer --name "orders-bot" --format json > /tmp/agent.json
AGENT_ID=$(jq -r .agent_id /tmp/agent.json)

acp-agents credentials issue "$AGENT_ID" \
  --scope agents:read --scope agents:heartbeat --format json > /tmp/cred.json
export ACP_API_KEY=$(jq -r .api_key /tmp/cred.json)   # one-shot plaintext

acp-agents activity "$AGENT_ID"
acp-agents show "$AGENT_ID"

# Mgmt-plane (requires acp_viewer / acp_operator / acp_admin role)
acp-agents mgmt list-all --tenant-id demo-tenant
acp-agents mgmt suspend "$AGENT_ID"
acp-agents mgmt transfer "$AGENT_ID" --to-tenant acme --reason "rebalance"

Full reference: docs/agents.md in the repo. Rate limit on credential issuance is 10 / 60s per agent (tunable via ACP_AGENT_CREDENTIAL_RATE_LIMIT_MAX and _WINDOW_SECONDS) — a 429 response means back off, not that credentials are broken.

Private Routes

These paths are part of the authenticated application shell and are intentionally excluded from the public agent surface.

/dashboard/projects/policies/models/users/service-accounts/audit/approvals/billing/admin/identity-mappings/chat/onboarding
Human Access

Checking whether this browser already has access to the interactive control plane.

Download OpenAPI