Skip to main content

Backend Route Inventory

The public contract is exposed only by backend/engine. Internal services keep the same path shape so the engine can proxy without changing Manager, mobile, SDK, ADK, web, or external API clients.

Engine Public Routes​

  • GET /api/v1/health
  • GET /api/v1/ready
  • POST /api/v1/auth/token
  • POST /api/v1/auth/register
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/realms
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/realms/:id/members
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/realms/:id/agents
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/realms/:id/services
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/realms/:id/identities/services
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/realms/:id/theme
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/users/:id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/auth/keys
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/auth/is-authenticated
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/auth/introspect
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/internal/webhooks/inbound
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/stores
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/search
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/product
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/carts
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/carts/clear
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/orders
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/catalog/orders/complete
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/status
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/capabilities
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/flows
  • POST /api/v1/runtime/flows/draft
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/flows/:id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/flows/:id/activate
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/flows/:id/preview
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/flows/:id/execute
  • POST /api/v1/runtime/flows/:id/publish|archive|rollback|test|promote
  • GET /api/v1/runtime/flows/:id/versions|fixtures|triggers
  • POST /api/v1/runtime/flows/:id/fixtures|triggers
  • POST /api/v1/runtime/flows/:id/triggers/:trigger_id/fire
  • DELETE /api/v1/runtime/flows/:id/triggers/:trigger_id
  • POST /api/v1/runtime/mcp/tool-proposals/generate
  • GET /api/v1/runtime/mcp/tool-proposals
  • POST /api/v1/runtime/mcp/tool-proposals/:proposal_id/review
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/prompts
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/prompts/:id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/prompts/:id/activate
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/agents/:agent_id/config
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/agents/:agent_id/mcp-servers
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/agents/:agent_id/mcp-servers/:mcp_server_id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/agents/:agent_id/flows/:flow_id/select
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/sessions
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/sessions/:session_id
  • POST /api/v1/runtime/sessions/:session_id/complete
  • POST /api/v1/runtime/sessions/:session_id/cancel
  • POST /api/v1/runtime/sessions/:session_id/reset
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/sessions/:session_id/messages
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/users/:user_id/context
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/sessions/:session_id/context
  • GET|PUT /api/v1/runtime/sessions/:session_id/state
  • DELETE /api/v1/runtime/sessions/:session_id/state/:key
  • POST /api/v1/runtime/sessions/:session_id/summarize
  • GET|POST /api/v1/runtime/knowledge
  • POST /api/v1/runtime/knowledge/search
  • DELETE /api/v1/runtime/knowledge/:knowledge_id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/routing/rules
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/routing/rules/:id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/routing/preview
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/routing/reload
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/routing/trace/:trace_id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/ai/chat
  • GET /api/v1/runtime/flow-routing-profiles
  • GET|PUT /api/v1/runtime/flows/:id/routing-profile
  • GET|PUT /api/v1/runtime/flow-routing-policy
  • POST /api/v1/runtime/flow-routing-preview
  • POST /api/v1/runtime/execute
  • GET|POST /api/v1/runtime/executions
  • GET /api/v1/runtime/executions/:id
  • POST /api/v1/runtime/executions/:id/cancel
  • POST /api/v1/runtime/executions/:id/retry
  • POST /api/v1/runtime/executions/:id/resume
  • GET /api/v1/runtime/executions/:id/events
  • GET /api/v1/runtime/executions/:id/actions
  • POST /api/v1/runtime/executions/:id/approvals/:approval_id/approve
  • POST /api/v1/runtime/executions/:id/approvals/:approval_id/deny
  • GET|POST /api/v1/runtime/evaluations
  • GET /api/v1/runtime/routing-recommendations
  • POST /api/v1/runtime/routing-recommendations/generate
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/ai/usage
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/ai/usage/stats
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/providers
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/providers/:id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/providers/:id/toggle
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/providers/templates
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/providers/templates/:type
  • GET /api/v1/runtime/configuration/schema
  • GET /api/v1/runtime/configuration/export
  • POST /api/v1/runtime/configuration/deploy (dry_run=true plans, false applies)
  • POST /api/v1/governance/flow-routing-evaluations

Provider create/update payloads use the authenticated JWT realm_id and the shared provider contract: name, description, type, write-only api_key, base_url, supports_text, supports_image, text_model, image_model, price fields, currency, is_default, is_active, and optional settings. At least one capability must be enabled and each enabled capability requires its matching model.

Automatic Flow classification uses only the authenticated realm's active, text-capable default provider. Agent-level provider assignments apply after Flow selection. If that default is unavailable, routing-disabled, or denied by data-egress policy, the resolver uses deterministic local fallback instead of another provider.

  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/servers
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/servers/:id
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/servers/:id/toggle
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/servers/:id/test
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/servers/:id/discover
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/servers/:id/tools
  • GET|POST|OPTIONS /api/v1/runtime/mcp/servers/:id/credentials
  • POST|OPTIONS /api/v1/runtime/mcp/servers/:id/credentials/:version/rollback
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/proxy
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/tools/route
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/tools/execute
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/tools/execute-parallel
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/runtime/mcp/tools/aggregate
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/usages
  • GET|POST|PUT|PATCH|DELETE|OPTIONS /api/v1/usages/summary
  • POST /api/v1/data/events
  • POST /api/v1/data/events/batch
  • GET /api/v1/data/query
  • GET /api/v1/data/summary

Internal Services​

  • auth-service: /api/v1/health, /api/v1/ready, auth, realm, user, auth-status, /api/v1/auth/verify, and /api/v1/auth/introspect routes.
  • runtime-service: /api/v1/health, /api/v1/ready, runtime status, flows, prompts, agents, sessions, context, and routing routes.
  • ai-service: /api/v1/health, /api/v1/ready, AI chat, AI usage, and provider routes.
  • mcp-service: /health, /ready, /mcp, /api/v1/health, /api/v1/ready, MCP server management, proxy, routing, execution, parallel execution, and aggregation routes.
  • usage-service: /api/v1/health, /api/v1/ready, usage listing and summary routes.
  • catalog-service: /api/v1/health and Catalog auth, webhook, store, product, cart, and order routes. The Engine is its default public boundary; an explicitly secured dedicated ingress is optional.
  • enrichment-service: /health plus internal Enrichment execution, usage, and job routes. Manager calls it over the private service network.
  • data-service: anonymous realm-scoped commerce, search, and conversation event ingestion, OpenSearch query, and aggregation routes.
  • safezone-service: internal tenant policy resolution, installed Safe Zone health checks, request/response inspection, masking/blocking decisions, and decision-only audit metadata.

Health and readiness routes are safe for probes. All domain routes require engine-signed internal headers when INTERNAL_SERVICE_SECRET is configured.

MCP server registration automatically calls tools/list, persists discovered tools in mcp_tools, and uses that registry for route selection when callers do not provide explicit mcp_server_ids. Manual rediscovery remains available through POST /api/v1/runtime/mcp/servers/:id/discover.

Unified MCP Service​

The unified mcp-service exposes MCP JSON-RPC over HTTP:

  • POST / for initialize, tools/list, and tools/call
  • POST /mcp for the same MCP JSON-RPC methods
  • GET /health
  • GET /ready

Core tools:

  • acp_api_request: generic engine /api/v1 request tool for complete API coverage.
  • acp_mcp_authenticate: authenticate MCP access through Auth with a Manager API key or legacy realm service identity.
  • acp_auth_register: register a user when enabled.
  • acp_runtime_ai_chat: call runtime AI chat.
  • acp_runtime_execute: synchronously run the versioned durable execution contract.
  • acp_runtime_create_execution: queue a durable execution.
  • acp_runtime_list_executions, acp_runtime_execution_get: inspect execution state and normalized results.
  • acp_runtime_execution_events, acp_runtime_execution_actions: inspect progress or replay normalized actions without side effects.
  • acp_runtime_execution_cancel, acp_runtime_execution_retry, acp_runtime_execution_resume: control durable work.
  • acp_runtime_approval_approve, acp_runtime_approval_deny: decide pending write-tool approvals.
  • acp_runtime_list_flows: list flows available to the authenticated realm.
  • acp_runtime_list_providers: list AI providers.
  • acp_runtime_mcp_execute_tool: execute a routed MCP tool through the engine.
  • acp_usage_summary: read usage summary.
  • acp_configuration_schema, acp_configuration_export: inspect or export portable, secret-free realm configuration.
  • acp_configuration_plan, acp_configuration_apply: validate/diff or transactionally apply reviewed configuration.
  • acp_data_record_event, acp_data_record_events: ingest anonymous events after PII removal and pseudonymization.
  • acp_data_query, acp_data_summary: query realm-scoped anonymous event data and aggregations.

The Merchant Commerce reference contract is catalog_search, catalog_get_product, cart_create, cart_get, cart_add_item, cart_update_item, cart_remove_item, cart_clear, cart_close, checkout_prepare, checkout_get, and checkout_cancel. Legacy Catalog aliases remain available for migration compatibility. Every write requires an idempotency key; checkout is an opaque payment handoff. Procurement and payment-provider tools are intentionally not exposed by ACP's built-in merchant profile.

Catalog MCP tool calls accept a merchant API key through Authorization: Bearer, x-api-key, X-Catalog-API-Key, or the legacy X-MCP-API-Key. Realm-bound Engine tools use an Engine Identities API key:

  • X-ACP-Realm-ID
  • Authorization: Bearer <api-key> or x-api-key: <api-key>

The same values can also be provided as realmId and apiKey, or inside auth: { realmId, apiKey }. Legacy accessKey and secretKey arguments and headers remain supported.

Developer, Observability, and Governance Routes​

All Go services expose an internal-network GET /metrics endpoint for Prometheus scraping. Metrics contain service, HTTP method, route, and status labels only; realm identifiers and request payloads are excluded.

  • GET /api/v1/sdk/config
  • GET /api/v1/observability/logs
  • GET /api/v1/observability/traces/:trace_id
  • GET /api/v1/observability/metrics
  • GET|POST /api/v1/observability/alerts
  • GET|POST /api/v1/integrations/clients
  • POST /api/v1/integrations/clients/:id/rotate-secret
  • GET /api/v1/governance
  • POST /api/v1/governance/policies
  • POST /api/v1/governance/policies/:id/activate
  • POST /api/v1/governance/allowlist
  • POST /api/v1/governance/allowlist/:id/decision
  • PUT /api/v1/governance/quotas
  • POST /api/v1/governance/evaluation-datasets
  • POST /api/v1/governance/evaluation-runs
  • POST /api/v1/governance/deployment-profiles
  • POST /api/v1/governance/support-access
  • POST /api/v1/governance/lawful-requests
  • POST /api/v1/runtime/webhooks
  • GET /api/v1/runtime/configuration/schema
  • GET /api/v1/runtime/configuration/export
  • POST /api/v1/runtime/configuration/deploy
  • GET /api/v1/usages/tools/summary
  • POST /api/v1/usages/export