{ "info": { "_postman_id": "acp-engine-collection", "name": "Thyris Agentic Commerce API - Customer Collection", "description": "# Thyris Agentic Commerce API - Customer Collection\n\nThis collection covers the public ACP Engine API for customer integration. Customer clients call only the public `base_url`; internal deployment details are outside the contract.\n\n## Recommended Run Order\n1. Exchange credentials for a bearer token.\n2. Configure one active text-capable realm default provider and publish eligible Flows with a semantic manifest or dedicated routing profile.\n3. Create a subject-bound runtime session; the collection stores `session_id` and `resume_token`.\n4. Use Runtime AI Chat without `flow_id` for automatic routing or with `flow_id` for explicit selection.\n5. Use Runtime Execute for structured sync/async operations and MCP Tools Execute only for a known approved tool.\n\nFlows are domain-neutral realm capability modules. Deterministic, adaptive, and hybrid Flows use the same integration endpoints; adaptive decisions remain bounded by declared branches, tools, outputs, risk, and Runtime policy.\n\nKeep `resume_token`, provider credentials, MCP credentials, and integration secrets in protected server-side state. Caller-supplied provider, MCP server, or tool identifiers cannot override ACP routing policy. Merchant Services keys may expire or be revoked; rotate the registered key and rerun discovery after a downstream 401.\n\nThe session section includes status reads, valid-token refresh, service-identity recovery, and permission-gated non-expiring creation. Treat Postman environment variables containing resume tokens as protected test data.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "base_url", "value": "http://localhost:8080", "type": "string" }, { "key": "mcp_base_url", "value": "http://localhost:8090", "type": "string" }, { "key": "access_key", "value": "PASTE_ACCESS_KEY", "type": "string" }, { "key": "secret_key", "value": "PASTE_SECRET_KEY", "type": "string" }, { "key": "token", "value": "PASTE_JWT_TOKEN", "type": "string" }, { "key": "user_id", "value": "USER_UUID", "type": "string" }, { "key": "realm_id", "value": "REALM_UUID", "type": "string" }, { "key": "agent_id", "value": "AGENT_UUID", "type": "string" }, { "key": "service_id", "value": "SERVICE_UUID", "type": "string" }, { "key": "mcp_service_secret_key", "value": "PASTE_MCP_SERVICE_SECRET_KEY", "type": "string" }, { "key": "mcp_service_access_key", "value": "PASTE_MCP_SERVICE_ACCESS_KEY", "type": "string" }, { "key": "provider_id", "value": "PROVIDER_UUID", "type": "string" }, { "key": "mcp_server_id", "value": "MCP_SERVER_UUID", "type": "string" }, { "key": "secondary_mcp_server_id", "value": "SECONDARY_MCP_SERVER_UUID", "type": "string" }, { "key": "routing_rule_id", "value": "ROUTING_RULE_UUID", "type": "string" }, { "key": "flow_id", "value": "FLOW_UUID", "type": "string" }, { "key": "prompt_id", "value": "PROMPT_UUID", "type": "string" }, { "key": "trace_id", "value": "TRACE_ID", "type": "string" }, { "key": "merchant_mcp_url", "value": "https://merchant.thyris.cloud/mcp", "type": "string" }, { "key": "merchant_api_key", "value": "PASTE_SCOPED_TR_LIVE_KEY", "type": "string" }, { "key": "session_id", "value": "00000000-0000-4000-8000-000000000001", "type": "string" }, { "key": "resume_token", "value": "", "type": "secret" }, { "key": "customer_subject_id", "value": "customer-reference-42", "type": "string" }, { "key": "chat_id", "value": "chat-10001", "description": "Protected test value; replace with the response value when available." }, { "key": "execution_id", "value": "EXECUTION_UUID", "description": "Protected test value; replace with the response value when available." } ], "item": [ { "name": "Health and Capabilities", "description": "# Health and Capabilities\n\nUse this section at the beginning of an integration session to verify that ACP Engine is reachable, correctly configured, and ready to serve runtime traffic. These endpoints are also useful for uptime checks, deployment validation, and customer environment handover.\n\n## Recommended Usage\n1. Run `Health Check` first to confirm the API is reachable from the customer network.\n2. Run `Runtime Status` after authentication to validate that the runtime layer can access AI, MCP, routing, and transaction services.\n3. Run `Runtime Capabilities` to see the enabled provider types, MCP execution modes, routing strategies, and feature flags exposed to the customer environment.\n\n## Request Guide\n- `Health Check`: lightweight availability check for service health, version, uptime, and dependency readiness.\n- `Runtime Status`: operational status view for runtime modules such as assistant backends, MCP tool selection, flow manager, and usage tracking.\n- `Runtime Capabilities`: integration metadata for client applications that need to decide which features to show or enable.\n\n## Integration Notes\n- Health checks are designed for monitoring and deployment smoke tests.\n- Capability responses can be cached by frontend or SDK clients for short periods.\n- A healthy API does not necessarily mean a provider or downstream MCP server is active; use the runtime status and MCP test endpoints for deeper validation.", "item": [ { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/health", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "health" ] }, "description": "Returns service health, version, uptime, and dependency readiness.\n\nExpected result: a compact operational response that confirms whether the environment is reachable and ready for integration checks. Use this before deeper runtime testing or after deployments.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Runtime Status", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/status", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "status" ] }, "description": "Returns runtime readiness for assistant backends, MCP tool selection, flow manager, and transaction services.\n\nExpected result: a compact operational response that confirms whether the environment is reachable and ready for integration checks. Use this before deeper runtime testing or after deployments.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Runtime Capabilities", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/capabilities", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "capabilities" ] }, "description": "Returns enabled features, supported provider types, MCP execution modes, and available routing strategies.\n\nExpected result: a compact operational response that confirms whether the environment is reachable and ready for integration checks. Use this before deeper runtime testing or after deployments.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] } ] }, { "name": "Public MCP Facade", "description": "# Public MCP Facade\n\nUse this folder to validate the public acp-mcp JSON-RPC endpoint. MCP clients authenticate with a realm-bound service identity created through Realms / Create Service. The facade accepts only service credentials scoped to the requested realm.", "item": [ { "name": "MCP Initialize", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {\n \"tools\": {\n }\n },\n \"clientInfo\": {\n \"name\": \"postman\",\n \"version\": \"1.0.0\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{mcp_base_url}}/", "host": [ "{{mcp_base_url}}" ], "path": [ "" ] }, "description": "Initializes the MCP session against acp-mcp." }, "response": [] }, { "name": "MCP List Tools", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"tools/list\",\n \"params\": {\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{mcp_base_url}}/", "host": [ "{{mcp_base_url}}" ], "path": [ "" ] }, "description": "Lists acp-mcp tools exposed in front of the engine API." }, "response": [] }, { "name": "MCP Authenticate Service Identity", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 3,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"acp_mcp_authenticate\",\n \"arguments\": {\n \"realmId\": \"{{realm_id}}\",\n \"accessKey\": \"{{mcp_service_access_key}}\",\n \"secretKey\": \"{{mcp_service_secret_key}}\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{mcp_base_url}}/", "host": [ "{{mcp_base_url}}" ], "path": [ "" ] }, "description": "Validates that the realm-bound service identity can authenticate through acp-mcp." }, "response": [] }, { "name": "MCP Execute Routed Tool Through Engine", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 4,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"acp_runtime_mcp_execute_tool\",\n \"arguments\": {\n \"auth\": {\n \"realmId\": \"{{realm_id}}\",\n \"accessKey\": \"{{mcp_service_access_key}}\",\n \"secretKey\": \"{{mcp_service_secret_key}}\"\n },\n \"realm_id\": \"{{realm_id}}\",\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"tool_name\": \"search_products\",\n \"arguments\": {\n \"query\": \"black shoes\",\n \"limit\": 10\n }\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{mcp_base_url}}/", "host": [ "{{mcp_base_url}}" ], "path": [ "" ] }, "description": "Calls the engine routed MCP execution endpoint through the public MCP facade. The engine may select the downstream MCP server from the discovered tool registry." }, "response": [] } ] }, { "name": "Auth", "description": "# Authentication\n\nThis section covers the complete ACP Engine authentication lifecycle: identity creation, credential exchange, JWT validation, and credential rotation. ACP Engine uses an access-key and secret-key model for obtaining short-lived bearer tokens.\n\n## Recommended Usage\n1. Run `Register` to create the first customer admin identity and realm.\n2. Run `Token Exchange` immediately after registration. The returned JWT is saved into `{{token}}` automatically.\n3. Run `Is Authenticated` to verify that Postman is sending the bearer token correctly.\n4. Use `Create New Auth Key` when rotating credentials or provisioning a new backend integration credential for the same identity.\n\n## Request Guide\n- `Register`: creates a user and optionally creates a realm in the same call. The response includes `access_key`, `secret_key`, `user.id`, and optionally `realm.id`.\n- `Token Exchange`: exchanges `{{access_key}}` and `{{secret_key}}` for a JWT access token.\n- `Is Authenticated`: validates the current token and returns the authenticated user context.\n- `Create New Auth Key`: issues a new credential pair for the authenticated user.\n\n## Variables Updated Automatically\n- `{{access_key}}` and `{{secret_key}}` from registration or key creation.\n- `{{token}}` from token exchange.\n- `{{user_id}}` and `{{realm_id}}` when available in the response.\n\n## Security Notes\n- The secret key is only returned at creation time and should be stored securely.\n- Use short-lived JWTs for API calls and long-lived keys only for token exchange.\n- For customer production environments, rotate credentials on a schedule and after team changes.", "item": [ { "name": "Register", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"username\": \"customer-admin\",\n \"user_type\": \"user\",\n \"realm_name\": \"Customer Production Realm\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/auth/register", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "auth", "register" ] }, "description": "Creates a new identity. When `realm_name` is provided, ACP Engine also creates a realm and assigns the user as realm admin.\n\nThe response contains `access_key` and `secret_key`. Store the secret key immediately.\n\nExpected result: an identity, credential, or token response that can be reused by the rest of the collection. The collection scripts store common values automatically when the response includes them.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Register succeeded\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.access_key) {", " pm.collectionVariables.set('access_key', json.access_key);", " pm.environment.set('access_key', json.access_key);", "}", "if (json.secret_key) {", " pm.collectionVariables.set('secret_key', json.secret_key);", " pm.environment.set('secret_key', json.secret_key);", "}", "if (json.user && json.user.id) {", " pm.collectionVariables.set('user_id', json.user && json.user.id);", " pm.environment.set('user_id', json.user && json.user.id);", "}", "if (json.realm && json.realm.id) {", " pm.collectionVariables.set('realm_id', json.realm && json.realm.id);", " pm.environment.set('realm_id', json.realm && json.realm.id);", "}" ] } } ], "response": [] }, { "name": "Token Exchange", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"access_key\": \"{{access_key}}\",\n \"secret_key\": \"{{secret_key}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/auth/token", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "auth", "token" ] }, "description": "Exchanges long-lived credentials for a short-lived JWT access token.\n\nExpected result: an identity, credential, or token response that can be reused by the rest of the collection. The collection scripts store common values automatically when the response includes them.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Token created\", function () { pm.expect(pm.response.code).to.be.oneOf([200]); });", "const json = pm.response.json();", "if (json.access_token) {", " pm.collectionVariables.set('token', json.access_token);", " pm.environment.set('token', json.access_token);", "}", "if (json.user_id) {", " pm.collectionVariables.set('user_id', json.user_id);", " pm.environment.set('user_id', json.user_id);", "}", "if (json.realm_id) {", " pm.collectionVariables.set('realm_id', json.realm_id);", " pm.environment.set('realm_id', json.realm_id);", "}" ] } } ], "response": [] }, { "name": "Is Authenticated", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/auth/is-authenticated", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "auth", "is-authenticated" ] }, "description": "Validates the current JWT and returns the authenticated user context.\n\nExpected result: an identity, credential, or token response that can be reused by the rest of the collection. The collection scripts store common values automatically when the response includes them.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create New Auth Key", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/v1/auth/keys", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "auth", "keys" ] }, "description": "Creates a new access key and secret key for the authenticated user.\n\nExpected result: an identity, credential, or token response that can be reused by the rest of the collection. The collection scripts store common values automatically when the response includes them.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Key created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.access_key) {", " pm.collectionVariables.set('access_key', json.access_key);", " pm.environment.set('access_key', json.access_key);", "}", "if (json.secret_key) {", " pm.collectionVariables.set('secret_key', json.secret_key);", " pm.environment.set('secret_key', json.secret_key);", "}" ] } } ], "response": [] } ] }, { "name": "Realms", "description": "# Realms\n\nRealms represent tenant workspaces in ACP Engine. A realm isolates users, agents, service accounts, assistant backends, MCP servers, flows, themes, and usage data. Customer integrations usually begin by creating or selecting a realm, then attaching users and runtime resources to it.\n\n## Recommended Usage\n1. Create a realm for the customer production workspace.\n2. Add users who need administrative or operational access.\n3. Create agent and service identities for runtime and backend integrations.\n4. Configure branding through the theme endpoints.\n\n## Request Guide\n- `Create Realm`: creates a tenant workspace and makes the current user the realm admin.\n- `Add Realm Member`: adds an existing user to a realm with a role such as `admin` or `member`.\n- `Get Realm Members`: returns current realm membership for review and access control checks.\n- `Create Agent`: creates an agent identity used by AI chat, flows, MCP tool selection, and usage tracking.\n- `Create Service`: creates a service identity for backend-to-backend calls.\n- `Get Realm Theme`: retrieves white-label and branding configuration.\n- `Update Realm Theme`: updates colors, logos, login metadata, chat metadata, and other customer-facing theme settings.\n\n## Key Variables\n- `{{realm_id}}`: used by most runtime, provider, flow, prompt, MCP, and usage endpoints.\n- `{{agent_id}}`: created from the agent endpoint and used in chat, routing, sessions, and reporting.\n- `{{service_id}}`: useful for backend integration and SDK bootstrap flows.\n\n## Integration Notes\n- Keep one realm per customer tenant or deployment boundary.\n- Use service identities for server-side integrations and agent identities for runtime AI behavior.\n- Theme metadata can be consumed by frontend clients during SDK/bootstrap initialization.", "item": [ { "name": "Create Realm", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Production Realm\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/realms", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "realms" ] }, "description": "Creates a new tenant realm. The authenticated user becomes the realm admin.\n\nExpected result: realm-scoped data used by runtime, provider, MCP, flow, theme, and reporting endpoints. Confirm `{{realm_id}}` before continuing with customer configuration.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Realm created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.id) {", " pm.collectionVariables.set('realm_id', json.id);", " pm.environment.set('realm_id', json.id);", "}" ] } } ], "response": [] }, { "name": "Add Realm Member", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"user_id\": \"{{user_id}}\",\n \"role\": \"member\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/realms/:id/members", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "realms", ":id", "members" ], "variable": [ { "key": "id", "value": "{{realm_id}}" } ] }, "description": "Adds an existing user to the realm. Admin permission is required.\n\nExpected result: realm-scoped data used by runtime, provider, MCP, flow, theme, and reporting endpoints. Confirm `{{realm_id}}` before continuing with customer configuration.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Get Realm Members", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/realms/:id/members", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "realms", ":id", "members" ], "variable": [ { "key": "id", "value": "{{realm_id}}" } ] }, "description": "Lists members of the selected realm.\n\nExpected result: realm-scoped data used by runtime, provider, MCP, flow, theme, and reporting endpoints. Confirm `{{realm_id}}` before continuing with customer configuration.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create Agent", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"username\": \"commerce-agent\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/realms/:id/agents", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "realms", ":id", "agents" ], "variable": [ { "key": "id", "value": "{{realm_id}}" } ] }, "description": "Creates an agent identity in the realm for AI and MCP workflows.\n\nExpected result: realm-scoped data used by runtime, provider, MCP, flow, theme, and reporting endpoints. Confirm `{{realm_id}}` before continuing with customer configuration.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Agent created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.agent_id) {", " pm.collectionVariables.set('agent_id', json.agent_id);", " pm.environment.set('agent_id', json.agent_id);", "}" ] } } ], "response": [] }, { "name": "Create Service", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"username\": \"integration-service\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/realms/:id/identities/services", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "realms", ":id", "identities", "services" ], "variable": [ { "key": "id", "value": "{{realm_id}}" } ] }, "description": "Creates a realm-bound service identity for backend-to-backend integrations and public acp-mcp access. The response includes service_id plus access_key and secret_key; store the secret immediately.\n\nUse these credentials with X-ACP-Realm-ID, X-ACP-Access-Key, and X-ACP-Secret-Key when calling the public MCP facade.\n\nExpected result: realm-scoped service identity data used by runtime, provider, MCP, flow, theme, and reporting endpoints. Confirm {{realm_id}} before continuing with customer configuration.\n\nOperational note: This request creates credentials. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Service created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.service_id) {", " pm.collectionVariables.set('service_id', json.service_id);", " pm.environment.set('service_id', json.service_id);", "}", "if (json.access_key) {", " pm.collectionVariables.set('mcp_service_access_key', json.access_key);", " pm.environment.set('mcp_service_access_key', json.access_key);", "}", "if (json.secret_key) {", " pm.collectionVariables.set('mcp_service_secret_key', json.secret_key);", " pm.environment.set('mcp_service_secret_key', json.secret_key);", "}", "if (json.service_key && !json.secret_key) {", " pm.collectionVariables.set('mcp_service_secret_key', json.service_key);", " pm.environment.set('mcp_service_secret_key', json.service_key);", "}" ] } } ], "response": [] }, { "name": "Get Realm Theme", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/realms/:id/theme", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "realms", ":id", "theme" ], "variable": [ { "key": "id", "value": "{{realm_id}}" } ] }, "description": "Returns branding and theme settings for the realm.\n\nExpected result: realm-scoped data used by runtime, provider, MCP, flow, theme, and reporting endpoints. Confirm `{{realm_id}}` before continuing with customer configuration.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update Realm Theme", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"colors\": {\n \"primary\": \"#2563eb\",\n \"secondary\": \"#14b8a6\",\n \"background\": \"#ffffff\"\n },\n \"sidebar\": {\n \"logo_url\": \"https://example.com/logo.png\",\n \"collapsed\": false\n },\n \"showPoweredBy\": true,\n \"login\": {\n \"title\": \"Customer Portal\"\n },\n \"chat\": {\n \"welcome_message\": \"How can I help you today?\"\n },\n \"images\": {\n \"favicon_url\": \"https://example.com/favicon.ico\"\n },\n \"metadata\": {\n \"updated_by\": \"postman\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/realms/:id/theme", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "realms", ":id", "theme" ], "variable": [ { "key": "id", "value": "{{realm_id}}" } ] }, "description": "Updates realm theme and white-label configuration.\n\nExpected result: realm-scoped data used by runtime, provider, MCP, flow, theme, and reporting endpoints. Confirm `{{realm_id}}` before continuing with customer configuration.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] } ] }, { "name": "Users", "description": "# Users\n\nThis section provides user profile lookup for authenticated customer workflows. User data is intentionally narrow and identity-focused; operational context such as preferences and runtime memory is handled by the Runtime Sessions and User Context endpoints.\n\n## Request Guide\n- `Get User Profile`: returns the selected user profile when the requester has access to it.\n\n## Typical Uses\n- Confirm the user ID saved by registration or token exchange.\n- Display basic identity data in admin tools.\n- Validate access when adding users to realms or assigning runtime permissions.\n\n## Variables\n- `{{user_id}}` is populated automatically by registration and token exchange responses.", "item": [ { "name": "Get User Profile", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/users/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "users", ":id" ], "variable": [ { "key": "id", "value": "{{user_id}}" } ] }, "description": "Returns a user profile that is visible to the requester.\n\nExpected result: basic user identity metadata. Use this to confirm that saved IDs and access rules are aligned with the current customer realm.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] } ] }, { "name": "Runtime - AI Chat", "description": "# Runtime - AI Chat\n\n`POST /api/v1/runtime/ai/chat` is the primary conversational/BFF endpoint. It requires `agent_id` and ordered `messages`. Keep `session_id` plus `resume_token` for continuity. Omit `flow_id` for automatic intent routing; include a protected server-configured `flow_id` only to force one exact validated Flow.\n\nUse `/api/v1/runtime/execute` for structured sync/async controls. Caller-supplied provider, MCP server, or tool identifiers do not override ACP realm, Agent, Flow, or routing policy.", "item": [ { "name": "AI Chat - Automatic Flow Routing", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"resume_token\": \"{{resume_token}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Find black running shoes under 150 USD.\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/ai/chat", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "ai", "chat" ] }, "description": "Sends free text without `flow_id`, so ACP selects or continues an eligible published Flow. Keep the matching resume token in protected BFF state." }, "response": [] }, { "name": "AI Chat - Explicit Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"resume_token\": \"{{resume_token}}\",\n \"flow_id\": \"{{flow_id}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Start the configured checkout journey.\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/ai/chat", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "ai", "chat" ] }, "description": "Supplies `flow_id` to bypass intent classification and execute only that validated conversational Flow. ACP never silently falls back to another Flow." }, "response": [] }, { "name": "Record AI Usage", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"tool_name\": \"ai_chat\",\n \"action\": \"RESPOND\",\n \"input_tokens\": 120,\n \"output_tokens\": 80,\n \"total_tokens\": 200,\n \"input_cost\": 0.00012,\n \"output_cost\": 0.00024,\n \"total_cost\": 0.00036,\n \"metadata\": {\n \"source\": \"postman\",\n \"provider_id\": \"{{provider_id}}\"\n },\n \"is_payment_successful\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/ai/usage", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "ai", "usage" ] }, "description": "Records external AI usage and transaction metadata.\n\nExpected result: runtime AI output, usage metadata, or aggregate runtime statistics. Use a stable `{{session_id}}` for multi-turn testing and reporting continuity.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Get Runtime Usage Stats", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/ai/usage/stats?agent_id={{agent_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "ai", "usage", "stats" ], "query": [ { "key": "agent_id", "value": "{{agent_id}}", "description": "Optional agent filter" } ] }, "description": "Returns usage totals for the current realm and optionally a specific agent.\n\nExpected result: runtime AI output, usage metadata, or aggregate runtime statistics. Use a stable `{{session_id}}` for multi-turn testing and reporting continuity.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "AI Chat - Direct Response Eligible (No Forced MCP)", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"resume_token\": \"{{resume_token}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Explain the difference between OLED and LCD displays in simple terms.\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/ai/chat", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "ai", "chat" ] }, "description": "Sends a conversational request without forcing a Flow, MCP server, provider, or tool. ACP automatically selects the eligible Flow. That Flow may return a direct response without an MCP call. Retain `session_id` for continuity." }, "response": [ { "name": "200 - Direct AI Response", "originalRequest": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"resume_token\": \"{{resume_token}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Explain the difference between OLED and LCD displays in simple terms.\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/ai/chat", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "ai", "chat" ] }, "description": "Sends a conversational request without forcing a Flow, MCP server, provider, or tool. ACP automatically selects the eligible Flow. That Flow may return a direct response without an MCP call. Retain `session_id` for continuity." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"action\": \"RESPOND\",\n \"content\": \"OLED displays light each pixel individually, which usually provides deeper blacks and stronger contrast. LCD displays use a shared backlight.\",\n \"execution_id\": \"{{execution_id}}\",\n \"trace_id\": \"trace_client_direct_ai_001\",\n \"session_id\": \"{{session_id}}\",\n \"routing\": {\n \"strategy\": \"intent_router\",\n \"flow_id\": \"{{flow_id}}\",\n \"intent\": \"general_product_question\",\n \"confidence\": 0.93,\n \"session_pinned\": true,\n \"handoff\": false\n }\n}" } ] } ] }, { "name": "Runtime - Providers", "description": "# Runtime - Providers\n\nProviders connect ACP Engine to LLM backends such as chat-completions provider, chat-completions provider-compatible endpoints, and Thyris. Provider configuration is realm-scoped and can be activated, updated, rotated, or deleted without changing frontend clients.\n\n## Recommended Usage\n1. Run `Get Provider Templates` to inspect supported provider types and required fields.\n2. Create a provider using the template that matches the customer environment.\n3. Keep one active provider per primary runtime path unless the customer requires multiple model backends.\n4. Use update and toggle endpoints for model changes, API key rotation, and operational failover.\n\n## Request Guide\n- `Get Provider Templates`: lists provider types, required fields, and default configuration.\n- `Get Provider Template`: returns a single provider template by type.\n- `Create Provider - chat-completions provider`: creates a provider and saves `{{provider_id}}` automatically.\n- `List Providers`: returns providers visible to the runtime context.\n- `Get Provider Details`: returns provider metadata without exposing secret API keys.\n- `Update Provider`: changes name, base URL, model settings, activation state, or key material.\n- `Toggle Provider Active`: enables or disables provider usage.\n- `Delete Provider`: removes a provider configuration.\n\n## Configuration Notes\n- `type` controls validation and client creation. Common values include `chat-completions provider`, `openai_compatible`, and `thyris`.\n- `settings.model` controls which model is used for runtime calls.\n- `input_price` and `output_price` can be used for cost tracking per million tokens.\n- API keys are treated as secrets and are not returned by detail/list endpoints.", "item": [ { "name": "Get Provider Templates", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/providers/templates", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers", "templates" ] }, "description": "Lists supported provider templates and required configuration fields.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Get Provider Template", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/providers/templates/:type", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers", "templates", ":type" ], "variable": [ { "key": "type", "value": "chat-completions provider" } ] }, "description": "Returns the template for a provider type. Supported examples: `chat-completions provider`, `openai_compatible`, `thyris`.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create Provider - chat-completions provider", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"type\": \"openai_compatible\",\n \"name\": \"Customer Text Provider\",\n \"api_key\": \"sk-replace-me\",\n \"base_url\": \"https://provider.example.com/v1\",\n \"supports_text\": true,\n \"supports_image\": false,\n \"text_model\": \"approved-text-model\",\n \"input_price_per_million\": 0,\n \"output_price_per_million\": 0,\n \"currency\": \"USD\",\n \"is_default\": true,\n \"is_active\": true,\n \"settings\": {\n \"temperature\": 0.2,\n \"max_tokens\": 2000\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/providers", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers" ] }, "description": "Creates an assistant backend for the realm. API keys are stored as encrypted secrets.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Provider created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.id) {", " pm.collectionVariables.set('provider_id', json.id);", " pm.environment.set('provider_id', json.id);", "}" ] } } ], "response": [] }, { "name": "List Providers", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/providers", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers" ] }, "description": "Lists assistant backends available to the current runtime context.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Get Provider Details", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/providers/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers", ":id" ], "variable": [ { "key": "id", "value": "{{provider_id}}" } ] }, "description": "Returns a single provider without exposing the provider API key.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update Provider", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Customer Text Provider Updated\",\n \"type\": \"openai_compatible\",\n \"base_url\": \"https://provider.example.com/v1\",\n \"supports_text\": true,\n \"supports_image\": false,\n \"text_model\": \"approved-text-model-v2\",\n \"input_price_per_million\": 0,\n \"output_price_per_million\": 0,\n \"currency\": \"USD\",\n \"is_default\": true,\n \"is_active\": true,\n \"settings\": {\n \"temperature\": 0.1,\n \"max_tokens\": 3000\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/providers/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers", ":id" ], "variable": [ { "key": "id", "value": "{{provider_id}}" } ] }, "description": "Updates provider metadata, activation state, base URL, API key, or model settings.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] }, { "name": "Toggle Provider Active", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PATCH", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/providers/:id/toggle?is_active=true", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers", ":id", "toggle" ], "query": [ { "key": "is_active", "value": "true", "description": "Set true to activate or false to deactivate" } ], "variable": [ { "key": "id", "value": "{{provider_id}}" } ] }, "description": "Activates or deactivates a provider.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This request changes a specific state or property, commonly activation or availability." }, "response": [] }, { "name": "Delete Provider", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/providers/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "providers", ":id" ], "variable": [ { "key": "id", "value": "{{provider_id}}" } ] }, "description": "Deletes a provider configuration.\n\nExpected result: provider templates or provider configuration data for the active realm. Provider secrets are handled as sensitive values and should not be exposed in read responses.\n\nOperational note: This request removes a resource. Use it carefully in customer environments." }, "response": [] } ] }, { "name": "Runtime - MCP Servers", "description": "# Runtime - MCP Servers\n\nMCP servers expose tool capabilities such as product search, cart operations, checkout, CRM lookup, order tracking, and custom customer actions. ACP Engine stores the MCP registry centrally, validates connectivity, discovers tools automatically during registration/update, and proxies tool calls through a single authenticated API surface.\n\n## Recommended Usage\n1. Register each downstream MCP server with `Create MCP Server`.\n2. Run `Test MCP Server Connection` to validate reachability and credentials.\n3. Review the automatic discovery result returned by `Create MCP Server`; run `Discover MCP Server Tools` manually after downstream tool changes.\n4. Use `List MCP Server Tools` to review exposed tools before creating routing rules.\n5. Use `Proxy MCP Tool Call` for direct execution tests.\n\n## Request Guide\n- `List MCP Servers`: lists registered MCP endpoints for the realm.\n- `Create MCP Server`: registers URL, type, credentials, metadata, and capability hints; runs `tools/list` by default and stores discovered tools.\n- `Get MCP Server`: returns one server registration.\n- `Update MCP Server`: updates connection details, metadata, or activation state.\n- `Toggle MCP Server Active`: controls whether the server can be used by routing and proxy calls.\n- `Discover MCP Server Tools`: reads downstream MCP tool definitions and JSON schemas.\n- `List MCP Server Tools`: returns cached tool metadata for review and routing setup.\n- `Test MCP Server Connection`: validates health, authentication, and tool availability.\n- `Proxy MCP Tool Call`: executes a named tool directly against a selected MCP server.\n- `Delete MCP Server`: removes the server registration.\n\n## Integration Notes\n- Use clear server names such as `Commerce MCP`, `CRM MCP`, or `Orders MCP`.\n- Use `type` and `capabilities` consistently so routing rules can select the right server.\n- Keep inactive servers registered when you want to preserve configuration but remove them from execution.", "item": [ { "name": "List MCP Servers", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers" ] }, "description": "Lists MCP servers registered for the current realm.\n\nExpected result: MCP registry, health, discovery, or direct execution data. Use these requests to validate each downstream MCP before routing customer traffic to it.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create MCP Server", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Agentic Commerce Platform\",\n \"url\": \"https://mcp.customer.example.com/mcp\",\n \"type\": \"ecommerce\",\n \"description\": \"Commerce tools for search, cart, checkout, and order operations.\",\n \"api_key\": \"mcp-secret-key\",\n \"is_active\": true,\n \"capabilities\": [\n \"search\",\n \"cart\",\n \"checkout\",\n \"orders\"\n ],\n \"auto_discover\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers" ] }, "description": "Registers a downstream MCP server in the realm registry. By default, ACP Engine immediately calls the server's tools/list method, persists discovered tools, and returns a discovery object with status and count.\n\nSet auto_discover to false only when the downstream endpoint is intentionally not reachable yet. Use meaningful type, description, and capabilities values because they help routing rules and customer operators understand what the server does.\n\nExpected result: { server, discovery }. The collection stores mcp_server_id automatically from either response shape.\n\nOperational note: This request creates configuration and may call the downstream MCP server." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"MCP server created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "const server = json.server || json;", "if (server.id) {", " pm.collectionVariables.set('mcp_server_id', server.id);", " pm.environment.set('mcp_server_id', server.id);", "}", "if (json.discovery) {", " pm.test(\"Discovery completed or reported status\", function () { pm.expect(json.discovery.status).to.be.oneOf(['ok', 'skipped', 'error']); });", "}" ] } } ], "response": [] }, { "name": "Create Thyris Merchant MCP Server", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Thyris Merchant Commerce MCP\",\n \"url\": \"{{merchant_mcp_url}}\",\n \"type\": \"ecommerce\",\n \"description\": \"Merchant catalog, cart, and checkout-handoff tools.\",\n \"api_key\": \"{{merchant_api_key}}\",\n \"is_active\": true,\n \"capabilities\": [\n \"catalog\",\n \"cart\",\n \"checkout\"\n ],\n \"auto_discover\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers" ] }, "description": "Registers a merchant-commerce MCP with a scoped Merchant Services API key and immediately discovers approved catalog, cart, and checkout-handoff tools. ACP sends the stored key as both a bearer token and X-MCP-API-Key. Procurement and payment-provider execution are not part of ACP's built-in Merchant Commerce contract." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Merchant MCP server created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "const server = json.server || json;", "if (server.id) {", " pm.collectionVariables.set('mcp_server_id', server.id);", " pm.environment.set('mcp_server_id', server.id);", "}" ] } } ], "response": [] }, { "name": "Get MCP Server", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers", ":id" ], "variable": [ { "key": "id", "value": "{{mcp_server_id}}" } ] }, "description": "Returns one MCP server registration.\n\nExpected result: MCP registry, health, discovery, or direct execution data. Use these requests to validate each downstream MCP before routing customer traffic to it.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update MCP Server", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Agentic Commerce Platform\",\n \"url\": \"https://mcp.customer.example.com/mcp\",\n \"type\": \"ecommerce\",\n \"description\": \"Production commerce MCP endpoint.\",\n \"is_active\": true,\n \"auto_discover\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers", ":id" ], "variable": [ { "key": "id", "value": "{{mcp_server_id}}" } ] }, "description": "Updates MCP server connection details and metadata. By default, ACP Engine rediscovers tools after the update and disables stale tools that no longer appear in tools/list. Set auto_discover to false to skip discovery for this request.\n\nExpected result: { server, discovery }.\n\nOperational note: This request updates configuration and may call the downstream MCP server." }, "response": [] }, { "name": "Toggle MCP Server Active", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"is_active\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers/:id/toggle", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers", ":id", "toggle" ], "variable": [ { "key": "id", "value": "{{mcp_server_id}}" } ] }, "description": "Activates or deactivates an MCP server.\n\nExpected result: MCP registry, health, discovery, or direct execution data. Use these requests to validate each downstream MCP before routing customer traffic to it.\n\nOperational note: This request changes a specific state or property, commonly activation or availability." }, "response": [] }, { "name": "Discover MCP Server Tools", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"refresh_cache\": true,\n \"include_schemas\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers/:id/discover", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers", ":id", "discover" ], "variable": [ { "key": "id", "value": "{{mcp_server_id}}" } ] }, "description": "Manually calls downstream tools/list, normalizes the returned tools, persists them in the MCP tool registry, and disables stale tools missing from the latest response. Registration and update already run this by default unless auto_discover is false.\n\nUse this after downstream MCP deployments or tool contract changes." }, "response": [] }, { "name": "List MCP Server Tools", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers/:id/tools", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers", ":id", "tools" ], "variable": [ { "key": "id", "value": "{{mcp_server_id}}" } ] }, "description": "Lists persisted MCP tool registry entries for this server. If no cached tools exist yet, ACP Engine falls back to live discovery.\n\nUse this to confirm routable tool names and schemas before creating routing rules or runtime tests." }, "response": [] }, { "name": "Test MCP Server Connection", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"timeout_ms\": 5000,\n \"validate_tools\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers/:id/test", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers", ":id", "test" ], "variable": [ { "key": "id", "value": "{{mcp_server_id}}" } ] }, "description": "Runs a connectivity and capability validation check against an MCP server.\n\nExpected result: MCP registry, health, discovery, or direct execution data. Use these requests to validate each downstream MCP before routing customer traffic to it.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Proxy MCP Tool Call", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"mcp_server_id\": \"{{mcp_server_id}}\",\n \"tool_name\": \"search_products\",\n \"session_id\": \"{{session_id}}\",\n \"arguments\": {\n \"query\": \"black shoes\",\n \"limit\": 25,\n \"filters\": {\n \"max_price\": 150\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/proxy", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "proxy" ] }, "description": "Executes a specific tool on a specific MCP server through ACP Engine.\n\nExpected result: MCP registry, health, discovery, or direct execution data. Use these requests to validate each downstream MCP before routing customer traffic to it.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Delete MCP Server", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/servers/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "servers", ":id" ], "variable": [ { "key": "id", "value": "{{mcp_server_id}}" } ] }, "description": "Deletes an MCP server registration.\n\nExpected result: MCP registry, health, discovery, or direct execution data. Use these requests to validate each downstream MCP before routing customer traffic to it.\n\nOperational note: This request removes a resource. Use it carefully in customer environments." }, "response": [] } ] }, { "name": "Runtime - MCP tool selection", "description": "# Runtime - MCP tool selection\n\nMCP tool selection is the decision layer that maps customer intent, agent context, flow configuration, tool names, capability tags, and server health into a concrete MCP execution path. This allows frontend clients to stay simple while ACP Engine decides which tool should run and where it should run.\n\n## Recommended Usage\n1. Register MCP servers and review the automatic tool listing result.\n2. Create routing rules that match intent, tool names, keywords, or capability tags.\n3. Use route evaluation endpoints to inspect how ACP Engine selects an MCP server.\n4. Execute routed tools once rules are configured.\n5. Inspect routing traces when validating customer scenarios or diagnosing behavior.\n\n## Request Guide\n- `List Routing Rules`: returns routing rules for the realm.\n- `Create Routing Rule`: creates match criteria, target strategy, fallback behavior, and execution policy.\n- `Get Routing Rule`: returns one routing rule in detail.\n- `Update Routing Rule`: changes priority, match conditions, target servers, and retry/timeout policy.\n- `Delete Routing Rule`: removes a routing rule.\n- `Preview MCP Route`: evaluates the selected route for a request without running the downstream tool.\n- `Reload Routing Rules`: refreshes routing configuration and invalidates route caches.\n- `Get Routing Trace`: returns the decision trace for a previous routed request.\n- `Route Tool Request`: resolves the best target MCP server for a tool request, using the discovered tool registry when explicit server IDs are not supplied.\n- `Execute Routed Tool`: resolves and executes a tool in one call, using registry-backed selection when the request provides only a tool name.\n- `Execute Tools in Parallel`: executes across multiple MCP servers and aggregates the outputs.\n- `Aggregate Tool Results`: normalizes and ranks multiple tool responses.\n- `Get MCP Session Context`: reads session-level routing state.\n- `Update MCP Session Context`: changes selected servers, active flow, or metadata for a session.\n\n## Routing Strategies\n- `first_healthy`: chooses the highest-priority active server that passes health checks.\n- `parallel_aggregate`: calls multiple servers and merges results.\n- `explicit`: uses a server selected by the client or session context.\n- `fallback`: tries a primary route first and then moves to backup routes based on policy.\n\n## Integration Notes\n- Routing rules should be specific enough to avoid ambiguous tool selection; when no explicit rule target is supplied, the discovered MCP tool registry narrows candidates by tool name.\n- Use priorities to prefer customer-owned MCPs over generic fallback tools.\n- Route traces are valuable for customer demos because they show why a server or tool was selected.", "item": [ { "name": "List Routing Rules", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/rules", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "rules" ] }, "description": "Lists routing rules used to map user intent, flows, tools, and capabilities to MCP servers.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create Routing Rule", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Commerce Search Routing\",\n \"realm_id\": \"{{realm_id}}\",\n \"flow_id\": \"{{flow_id}}\",\n \"priority\": 100,\n \"enabled\": true,\n \"match\": {\n \"intents\": [\n \"product_search\",\n \"recommendation\"\n ],\n \"tool_names\": [\n \"search_products\",\n \"list_products\"\n ],\n \"keywords\": [\n \"find\",\n \"search\",\n \"show\"\n ],\n \"capability_tags\": [\n \"commerce\",\n \"products\"\n ]\n },\n \"target\": {\n \"strategy\": \"first_healthy\",\n \"mcp_server_ids\": [\n \"{{mcp_server_id}}\",\n \"{{secondary_mcp_server_id}}\"\n ],\n \"fallback_provider_id\": \"{{provider_id}}\"\n },\n \"policies\": {\n \"timeout_ms\": 8000,\n \"retry_count\": 1,\n \"cache_ttl_seconds\": 60\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/rules", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "rules" ] }, "description": "Creates a dynamic rule that maps intents, tool names, keywords, and capability tags to target MCP servers and execution policies.\n\nUse priority to control which rule wins when multiple rules match. Use target strategy to choose single-server, fallback, or parallel execution behavior.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Routing rule created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.id) {", " pm.collectionVariables.set('routing_rule_id', json.id);", " pm.environment.set('routing_rule_id', json.id);", "}" ] } } ], "response": [] }, { "name": "Get Routing Rule", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/rules/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "rules", ":id" ], "variable": [ { "key": "id", "value": "{{routing_rule_id}}" } ] }, "description": "Returns a routing rule with match conditions, target strategy, and policy settings.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update Routing Rule", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Commerce Search Routing - Updated\",\n \"priority\": 110,\n \"enabled\": true,\n \"target\": {\n \"strategy\": \"parallel_aggregate\",\n \"mcp_server_ids\": [\n \"{{mcp_server_id}}\",\n \"{{secondary_mcp_server_id}}\"\n ]\n },\n \"policies\": {\n \"timeout_ms\": 10000,\n \"retry_count\": 2,\n \"cache_ttl_seconds\": 120\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/rules/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "rules", ":id" ], "variable": [ { "key": "id", "value": "{{routing_rule_id}}" } ] }, "description": "Updates a routing rule and its execution policy.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] }, { "name": "Delete Routing Rule", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/rules/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "rules", ":id" ], "variable": [ { "key": "id", "value": "{{routing_rule_id}}" } ] }, "description": "Deletes a routing rule.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request removes a resource. Use it carefully in customer environments." }, "response": [] }, { "name": "Preview MCP Route", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"agent_id\": \"{{agent_id}}\",\n \"flow_id\": \"{{flow_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"intent\": \"product_search\",\n \"tool_name\": \"search_products\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Find black running shoes under 150 USD.\"\n }\n ],\n \"context\": {\n \"locale\": \"en-US\",\n \"channel\": \"web\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/preview", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "preview" ] }, "description": "Evaluates a routing decision for the provided intent, tool name, messages, and context. The response shows which rule matched, which MCP server is selected, which fallback path is available, and which policy values apply.\n\nUse this request when validating customer scenarios before executing a tool. It is especially useful during onboarding because it explains the route without changing downstream systems.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Reload Routing Rules", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"invalidate_cache\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/reload", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "reload" ] }, "description": "Reloads routing configuration and clears routing caches for a realm.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Get Routing Trace", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/routing/trace/:trace_id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "routing", "trace", ":trace_id" ], "variable": [ { "key": "trace_id", "value": "{{trace_id}}" } ] }, "description": "Returns a step-by-step routing decision trace for a previous request.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Route Tool Request", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"agent_id\": \"{{agent_id}}\",\n \"flow_id\": \"{{flow_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"tool_name\": \"search_products\",\n \"arguments\": {\n \"query\": \"black shoes\",\n \"limit\": 25\n },\n \"routing_hints\": {\n \"preferred_capabilities\": [\n \"commerce\",\n \"products\"\n ],\n \"strategy\": \"first_healthy\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/tools/route", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "tools", "route" ] }, "description": "Resolves the best MCP server and route for a tool request. If the request does not include explicit server IDs, ACP Engine uses routing rules and the discovered MCP tool registry to select a server that exposes the requested tool.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data." }, "response": [] }, { "name": "Execute Routed Tool", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"session_id\": \"{{session_id}}\",\n \"tool_name\": \"catalog_get_product_details\",\n \"arguments\": {\n \"catalogId\": \"1234567890\"\n },\n \"strategy\": \"first_healthy\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/tools/execute", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "tools", "execute" ] }, "description": "Routes and executes a known approved tool in one API call. This example represents a deterministic product-details widget mapped by a protected BFF to fixed allowlisted catalog_get_product_details. Browser/mobile input must never control tool_name, strategy, or MCP server IDs. ACP selects the eligible server from the discovered tool registry when server IDs are omitted. The response is a raw routed-tool envelope, not RENDER_PRODUCT_DETAILS. Use `/runtime/ai/chat` without flow_id for natural-language details, or `/runtime/execute` with a protected product-details Flow when an ACP action envelope is required." }, "response": [] }, { "name": "Execute Tools in Parallel", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"executions\": [\n {\n \"mcp_server_id\": \"{{mcp_server_id}}\",\n \"tool_name\": \"search_products\",\n \"arguments\": {\n \"query\": \"black shoes\",\n \"limit\": 10\n }\n },\n {\n \"mcp_server_id\": \"{{secondary_mcp_server_id}}\",\n \"tool_name\": \"search_products\",\n \"arguments\": {\n \"query\": \"black shoes\",\n \"limit\": 10\n }\n }\n ],\n \"aggregation\": {\n \"mode\": \"merge_by_sku\",\n \"max_results\": 20\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/tools/execute-parallel", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "tools", "execute-parallel" ] }, "description": "Executes multiple tool calls across one or more MCP servers and returns an aggregated response. This is useful for multi-product search, cross-platform availability checks, or comparing results across customer systems.\n\nThe `aggregation` object controls how results are merged, ranked, deduplicated, and limited.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Aggregate Tool Results", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"session_id\": \"{{session_id}}\",\n \"mode\": \"merge_by_sku\",\n \"results\": [\n {\n \"source\": \"agentic_commerce_platform\",\n \"items\": []\n },\n {\n \"source\": \"merchant_services_platform\",\n \"items\": []\n }\n ],\n \"ranking\": {\n \"sort_by\": \"relevance\",\n \"deduplicate\": true\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/tools/aggregate", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "tools", "aggregate" ] }, "description": "Aggregates tool responses into a normalized result set for AI or frontend rendering.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Get MCP Session Context", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/sessions/:session_id/context", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "sessions", ":session_id", "context" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Returns MCP tool selection context, selected servers, recent tool calls, and cached results for a session.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update MCP Session Context", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"selected_mcp_server_ids\": [\n \"{{mcp_server_id}}\"\n ],\n \"active_flow_id\": \"{{flow_id}}\",\n \"metadata\": {\n \"channel\": \"web\",\n \"locale\": \"en-US\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/mcp/sessions/:session_id/context", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "mcp", "sessions", ":session_id", "context" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Updates session-level MCP context for subsequent routing decisions.\n\nExpected result: routing configuration, selected route details, execution output, aggregated results, or route trace data. Use these requests to validate how ACP Engine chooses tools and MCP servers.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] } ] }, { "name": "Runtime - Flows", "description": "# Runtime - Flows\n\nFlows are domain-neutral, realm-scoped capability modules. A Flow combines a semantic routing manifest, a bounded system-instruction fragment, approved tools and output actions, and deterministic or adaptive execution steps. Commerce, support, operations, HR, banking, and other approved use cases share the same runtime contract.\n\n## Recommended Usage\n1. Configure the realm and Agent system prompt.\n2. Register the MCP servers required by the Flow.\n3. Create a deterministic, adaptive, or hybrid Flow with routing, behavior, permissions, runtime limits, and visual nodes.\n4. Test, publish, and activate the Flow for its realm.\n5. Execute it through Runtime AI Chat or structured Runtime Execute.\n\n## Request Guide\n- `List Flows`: lists Flows available to a realm.\n- `Create Flow`: creates a Flow and saves `{{flow_id}}` automatically.\n- `Get Flow`: returns its manifest, behavior, permissions, and visual graph.\n- `Update Flow`: creates a reviewed configuration change.\n- `Activate Flow`: marks a published Flow active.\n- `Preview Flow`: validates a Flow plan for an input message.\n- `Execute Flow`: runs bounded orchestration and approved capabilities.\n- `Delete Flow`: removes a Flow definition.\n\n## Flow Design Notes\n- Omit `flow_id` for realm automatic routing; supply it only for deliberate explicit execution.\n- Existing Flows remain deterministic unless their orchestration mode is changed and republished.\n- AI Decision and adaptive Supervisor nodes can select only declared choices or children.\n- Runtime still enforces tools, schemas, approvals, idempotency, outputs, risk, cost, and data-egress policy.", "item": [ { "name": "List Flows", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/flows?realm_id={{realm_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}", "description": "Optional realm filter" } ] }, "description": "Lists runtime flows for a realm.\n\nExpected result: flow definitions or flow execution results that combine AI behavior, assistant backend selection, MCP access, and response generation into one customer journey.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Incident Triage\",\n \"description\": \"Investigates service incidents and proposes safe next actions.\",\n \"config\": {\n \"schema_version\": \"2026-09-25\",\n \"orchestration_mode\": \"hybrid\",\n \"routing\": {\n \"enabled\": true,\n \"when_to_use\": \"Investigate service incidents and operational failures.\",\n \"when_not_to_use\": \"Do not approve access requests.\",\n \"capabilities\": [\"incident.triage\", \"logs.search\"],\n \"allowed_handoffs\": [\"access.request\", \"human.escalation\"],\n \"minimum_confidence\": 0.75\n },\n \"behavior\": {\n \"instructions\": \"Act as an incident specialist and separate evidence from inference.\",\n \"completion_criteria\": [\"Likely cause identified\", \"Safe next action proposed\"]\n },\n \"permissions\": {\n \"allowed_actions\": [\"RESPOND\", \"CLARIFY\", \"ESCALATE\"],\n \"risk_tier\": \"elevated\"\n },\n \"runtime\": {\n \"max_tool_calls\": 3\n },\n \"nodes\": [\n {\n \"id\": \"input\",\n \"type\": \"input\"\n },\n {\n \"id\": \"decide\",\n \"type\": \"ai_decision\",\n \"instructions\": \"Choose whether to investigate or ask for missing context.\",\n \"minimum_confidence\": 0.7,\n \"fallback_choice\": \"clarify\",\n \"choices\": [\n {\"key\": \"investigate\", \"description\": \"Enough context exists to investigate.\"},\n {\"key\": \"clarify\", \"description\": \"Required incident context is missing.\"}\n ]\n },\n {\n \"id\": \"result\",\n \"type\": \"output\",\n \"action\": \"RESPOND\"\n }\n ]\n },\n \"is_active\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows" ] }, "description": "Creates an inactive draft flow. Run fixtures, publish the compatible draft, and activate it through the dedicated lifecycle endpoints. Creating a flow with `is_active: true` returns `409 Conflict`." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Flow created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.id) {", " pm.collectionVariables.set('flow_id', json.id);", " pm.environment.set('flow_id', json.id);", "}" ] } } ], "response": [] }, { "name": "Get Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/flows/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", ":id" ], "variable": [ { "key": "id", "value": "{{flow_id}}" } ] }, "description": "Returns flow details including behavior templates, allowed MCP servers, and execution steps.\n\nExpected result: flow definitions or flow execution results that combine AI behavior, assistant backend selection, MCP access, and response generation into one customer journey.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Incident Triage - Candidate\",\n \"is_active\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", ":id" ], "variable": [ { "key": "id", "value": "{{flow_id}}" } ] }, "description": "Updates flow routing, behavior template, assistant backend, and activation settings.\n\nExpected result: flow definitions or flow execution results that combine AI behavior, assistant backend selection, MCP access, and response generation into one customer journey.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] }, { "name": "Activate Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"make_default\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows/:id/activate", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", ":id", "activate" ], "variable": [ { "key": "id", "value": "{{flow_id}}" } ] }, "description": "Activates a flow and optionally sets it as the realm default.\n\nExpected result: flow definitions or flow execution results that combine AI behavior, assistant backend selection, MCP access, and response generation into one customer journey.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Preview Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"I want a gift for my father.\"\n }\n ],\n \"dry_run\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows/:id/preview", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", ":id", "preview" ], "variable": [ { "key": "id", "value": "{{flow_id}}" } ] }, "description": "Runs the flow planner without committing side effects or executing payment operations.\n\nExpected result: flow definitions or flow execution results that combine AI behavior, assistant backend selection, MCP access, and response generation into one customer journey.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Execute Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"input\": {\n \"message\": \"Find a gift for my father under 100 USD.\"\n },\n \"options\": {\n \"stream\": false,\n \"trace\": true\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows/:id/execute", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", ":id", "execute" ], "variable": [ { "key": "id", "value": "{{flow_id}}" } ] }, "description": "Runs a flow end to end. ACP Engine applies the flow prompt, builds AI context, performs MCP tool selection when tools are needed, aggregates results, and returns the final customer-facing response.\n\nUse this request for deterministic workflow execution when the client wants to select a specific flow instead of relying on default chat behavior.\n\nExpected result: flow definitions or flow execution results that combine AI behavior, assistant backend selection, MCP access, and response generation into one customer journey.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Delete Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/flows/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", ":id" ], "variable": [ { "key": "id", "value": "{{flow_id}}" } ] }, "description": "Deletes a flow definition.\n\nExpected result: flow definitions or flow execution results that combine AI behavior, assistant backend selection, MCP access, and response generation into one customer journey.\n\nOperational note: This request removes a resource. Use it carefully in customer environments." }, "response": [] } ] }, { "name": "Runtime - behavior templates", "description": "# Runtime - behavior templates\n\nbehavior templates control the behavior, tone, domain constraints, and tool-use rules for AI interactions. ACP Engine stores behavior templates as reusable templates that can be assigned to flows and agents.\n\n## Recommended Usage\n1. Create a prompt for each major assistant behavior.\n2. Include variables for locale, channel, customer segment, or brand policy when needed.\n3. Assign active behavior templates to flows or agent configurations.\n4. Update behavior templates through versioned operational changes rather than editing frontend clients.\n\n## Request Guide\n- `List behavior templates`: lists prompt templates available to a realm.\n- `Create behavior template`: creates a prompt and saves `{{prompt_id}}` automatically.\n- `Get behavior template`: returns prompt content, key, variables, and metadata.\n- `Update behavior template`: changes prompt content, variables, or activation state.\n- `Activate behavior template`: activates a prompt and optionally assigns it to a flow.\n- `Delete behavior template`: removes a prompt template.\n\n## Prompt Notes\n- Prompt content should describe when to call MCP tools and when to answer directly.\n- Variables keep behavior templates reusable across brands, locales, and channels.\n- Prompt assignment through flows gives customers centralized behavior control.", "item": [ { "name": "List behavior templates", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/behavior templates?realm_id={{realm_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "prompts" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}", "description": "Optional realm filter" } ] }, "description": "Lists behavior templates available to a realm.\n\nExpected result: prompt templates and assignment metadata. Use these endpoints to manage assistant behavior centrally without changing customer frontend code.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create behavior template", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"name\": \"Commerce Assistant Prompt\",\n \"key\": \"commerce_assistant_v1\",\n \"content\": \"You are a commerce assistant. Understand intent, select the correct tools, and produce concise customer-facing responses.\",\n \"variables\": [\n \"locale\",\n \"channel\",\n \"customer_segment\"\n ],\n \"is_active\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/behavior templates", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "prompts" ] }, "description": "Creates a behavior template template for AI orchestration.\n\nExpected result: prompt templates and assignment metadata. Use these endpoints to manage assistant behavior centrally without changing customer frontend code.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Prompt created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.id) {", " pm.collectionVariables.set('prompt_id', json.id);", " pm.environment.set('prompt_id', json.id);", "}" ] } } ], "response": [] }, { "name": "Get behavior template", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/behavior templates/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "prompts", ":id" ], "variable": [ { "key": "id", "value": "{{prompt_id}}" } ] }, "description": "Returns a behavior template template and metadata.\n\nExpected result: prompt templates and assignment metadata. Use these endpoints to manage assistant behavior centrally without changing customer frontend code.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update behavior template", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Commerce Assistant Prompt - Production\",\n \"content\": \"You are a concise commerce assistant. Use MCP tools when product, cart, checkout, or order information is required.\",\n \"variables\": [\n \"locale\",\n \"channel\",\n \"customer_segment\"\n ],\n \"is_active\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/behavior templates/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "prompts", ":id" ], "variable": [ { "key": "id", "value": "{{prompt_id}}" } ] }, "description": "Updates prompt content and template variables.\n\nExpected result: prompt templates and assignment metadata. Use these endpoints to manage assistant behavior centrally without changing customer frontend code.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] }, { "name": "Activate behavior template", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"assign_to_flow_id\": \"{{flow_id}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/behavior templates/:id/activate", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "prompts", ":id", "activate" ], "variable": [ { "key": "id", "value": "{{prompt_id}}" } ] }, "description": "Activates a behavior template and optionally assigns it to a flow.\n\nExpected result: prompt templates and assignment metadata. Use these endpoints to manage assistant behavior centrally without changing customer frontend code.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Delete behavior template", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/behavior templates/:id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "prompts", ":id" ], "variable": [ { "key": "id", "value": "{{prompt_id}}" } ] }, "description": "Deletes a behavior template template.\n\nExpected result: prompt templates and assignment metadata. Use these endpoints to manage assistant behavior centrally without changing customer frontend code.\n\nOperational note: This request removes a resource. Use it carefully in customer environments." }, "response": [] } ] }, { "name": "Runtime - Agent Configuration", "description": "# Runtime - Agent Configuration\n\nAgent configuration connects a runtime identity to its provider, behavior template, default flow, and allowed MCP servers. This section is useful when a customer has multiple assistants with different responsibilities, permissions, or tool access.\n\n## Recommended Usage\n1. Create an agent in the Realms section.\n2. Configure the agent with a default provider, prompt, flow, and MCP allowlist.\n3. Attach or detach MCP servers as the assistant scope changes.\n4. Select a flow for an agent or session when a specific journey should be used.\n\n## Request Guide\n- `Get Agent Runtime Config`: returns the current runtime configuration for an agent.\n- `Update Agent Runtime Config`: sets provider, prompt, default flow, and allowed MCP servers.\n- `Attach MCP Server to Agent`: adds a server to the agent allowlist.\n- `Detach MCP Server from Agent`: removes a server from the agent allowlist.\n- `Select Agent Flow`: assigns a flow to an agent or a specific session.\n\n## Integration Notes\n- Use allowlists to prevent an assistant from calling unrelated customer systems.\n- Use agent-level defaults for stable production behavior.\n- Use session-level flow selection for temporary campaign, support, or checkout journeys.", "item": [ { "name": "Get Agent Runtime Config", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/agents/:agent_id/config", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "agents", ":agent_id", "config" ], "variable": [ { "key": "agent_id", "value": "{{agent_id}}" } ] }, "description": "Returns provider, prompt, flow, and allowed MCP server settings for an agent.\n\nExpected result: agent-level runtime permissions and defaults. Use these endpoints to control which provider, flow, prompt, and MCP servers an assistant can use.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update Agent Runtime Config", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"system_prompt_id\": \"{{prompt_id}}\",\n \"ai_provider_id\": \"{{provider_id}}\",\n \"default_flow_id\": \"{{flow_id}}\",\n \"allowed_mcp_servers\": [\n \"{{mcp_server_id}}\"\n ],\n \"metadata\": {\n \"owner\": \"commerce-team\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/agents/:agent_id/config", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "agents", ":agent_id", "config" ], "variable": [ { "key": "agent_id", "value": "{{agent_id}}" } ] }, "description": "Updates an agent runtime configuration.\n\nExpected result: agent-level runtime permissions and defaults. Use these endpoints to control which provider, flow, prompt, and MCP servers an assistant can use.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] }, { "name": "Attach MCP Server to Agent", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"mcp_server_id\": \"{{mcp_server_id}}\",\n \"priority\": 100,\n \"enabled\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/agents/:agent_id/mcp-servers", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "agents", ":agent_id", "mcp-servers" ], "variable": [ { "key": "agent_id", "value": "{{agent_id}}" } ] }, "description": "Adds an MCP server to the agent allowlist.\n\nExpected result: agent-level runtime permissions and defaults. Use these endpoints to control which provider, flow, prompt, and MCP servers an assistant can use.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Detach MCP Server from Agent", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "DELETE", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/agents/:agent_id/mcp-servers/:mcp_server_id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "agents", ":agent_id", "mcp-servers", ":mcp_server_id" ], "variable": [ { "key": "agent_id", "value": "{{agent_id}}" }, { "key": "mcp_server_id", "value": "{{mcp_server_id}}" } ] }, "description": "Removes an MCP server from the agent allowlist.\n\nExpected result: agent-level runtime permissions and defaults. Use these endpoints to control which provider, flow, prompt, and MCP servers an assistant can use.\n\nOperational note: This request removes a resource. Use it carefully in customer environments." }, "response": [] }, { "name": "Select Agent Flow", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"session_id\": \"{{session_id}}\",\n \"persist_for_agent\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/agents/:agent_id/flows/:flow_id/select", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "agents", ":agent_id", "flows", ":flow_id", "select" ], "variable": [ { "key": "agent_id", "value": "{{agent_id}}" }, { "key": "flow_id", "value": "{{flow_id}}" } ] }, "description": "Selects a flow for an agent or for a specific session.\n\nExpected result: agent-level runtime permissions and defaults. Use these endpoints to control which provider, flow, prompt, and MCP servers an assistant can use.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] } ] }, { "name": "Runtime - Automatic Flow Routing", "description": "Configure and inspect automatic Flow selection. Published adaptive and hybrid Flows may carry their own semantic manifest; a dedicated routing profile remains an advanced override. Start with `disabled`, use preview and approved evaluations, then move through `shadow` to bounded `enforced` canary rollout. Return to `disabled` for immediate compatibility rollback.", "item": [ { "name": "List Flow Routing Profiles", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/flow-routing-profiles", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flow-routing-profiles" ] }, "description": "Lists realm-scoped Flow routing profiles and their current versions." }, "response": [] }, { "name": "Configure Flow Routing Profile", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"enabled\": true,\n \"description\": \"Searches and recommends catalog products\",\n \"intents\": [\"product_search\", \"product_recommendation\"],\n \"utterance_examples\": [\"I want to buy an iPhone\", \"Show waterproof jackets\"],\n \"negative_examples\": [\"Where is my order?\"],\n \"channels\": [\"web\"],\n \"locales\": [\"en-US\"],\n \"required_client_capabilities\": {\"render_products\": true},\n \"priority\": 100,\n \"minimum_confidence\": 0.75,\n \"fallback_behavior\": \"clarify\",\n \"allowed_handoffs\": [\"cart\", \"support\"],\n \"risk_tier\": \"standard\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows/:flow_id/routing-profile", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", ":flow_id", "routing-profile" ], "variable": [ { "key": "flow_id", "value": "{{flow_id}}" } ] }, "description": "Creates or replaces the advanced routing profile for one published Flow. This profile takes precedence over the Flow's compiled semantic manifest. The Flow must also be active before it can enter the runtime candidate set." }, "response": [] }, { "name": "Get Realm Flow Routing Policy", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/flow-routing-policy", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flow-routing-policy" ] }, "description": "Returns realm routing mode, legacy fallback, version, and canary percentage." }, "response": [] }, { "name": "Enable Shadow Flow Routing", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"mode\": \"shadow\",\n \"legacy_fallback_enabled\": true,\n \"canary_percentage\": 0\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flow-routing-policy", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flow-routing-policy" ] }, "description": "Computes and records automatic proposals while continuing to execute compatibility selection." }, "response": [] }, { "name": "Preview Automatic Flow Routing", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"message\": \"I want to buy an iPhone\",\n \"channel\": \"web\",\n \"locale\": \"en-US\",\n \"client_capabilities\": {\"render_products\": true}\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flow-routing-preview", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flow-routing-preview" ] }, "description": "Previews deterministic eligibility and routing without creating an execution, mutating a session, or calling a model." }, "response": [] } ] }, { "name": "Runtime - Sessions and Chat History", "description": "# Runtime - Sessions and Chat History\n\nCreate one subject-bound session per conversation or purchase journey. Keep both returned `{{session_id}}` and `{{resume_token}}` in protected BFF state. Use the same pair for chat and structured execution until completion, cancellation, or expiry. A session can span multiple product listings and allowed Flow handoffs.\n\nUse `complete` for successful terminal journeys, `cancel` for abandonment, and `reset` only for a deliberate new routing decision in an active session. Never expose the resume token to browser JavaScript or logs.", "item": [ { "name": "Create Runtime Session", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"agent_id\": \"{{agent_id}}\",\n \"subject_type\": \"external\",\n \"subject_id\": \"{{customer_subject_id}}\",\n \"channel\": \"web\",\n \"ttl_seconds\": 86400,\n \"metadata\": {\n \"locale\": \"en-US\",\n \"client_capabilities\": {\n \"actions\": [\n \"RESPOND\",\n \"CLARIFY\",\n \"RENDER_PRODUCTS\",\n \"OFFER_PRODUCT_ALTERNATIVES\",\n \"RENDER_PRODUCT_ALTERNATIVES\",\n \"RENDER_PRODUCT_DETAILS\",\n \"ERROR\"\n ]\n }\n },\n \"transcript_retention\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions" ] }, "description": "Creates a runtime session for chat, routing, and context persistence.\n\nExpected result: conversation state, persisted messages, or user context. Use these endpoints to keep customer conversations consistent across frontend sessions.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Session created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "if (json.id || json.session_id) {", " pm.collectionVariables.set('session_id', json.id || json.session_id);", " pm.environment.set('session_id', json.id || json.session_id);", " pm.collectionVariables.set('resume_token', json.resume_token || '');", " pm.environment.set('resume_token', json.resume_token || '');", "}" ] } } ], "response": [] }, { "name": "Get Runtime Session", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Returns session metadata, active flow, selected MCP servers, and state summary.\n\nExpected result: conversation state, persisted messages, or user context. Use these endpoints to keep customer conversations consistent across frontend sessions.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "List Session Messages", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/messages", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "messages" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Returns persisted chat messages for a session.\n\nExpected result: conversation state, persisted messages, or user context. Use these endpoints to keep customer conversations consistent across frontend sessions.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Append Session Message", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"role\": \"user\",\n \"content\": \"Show me similar products.\",\n \"metadata\": {\n \"source\": \"postman\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/messages", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "messages" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Appends a message to the persisted chat history.\n\nExpected result: conversation state, persisted messages, or user context. Use these endpoints to keep customer conversations consistent across frontend sessions.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Complete Runtime Session", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"resume_token\": \"{{resume_token}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/complete", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "complete" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Marks a successfully finished journey terminal. Requires the matching protected session resume token." }, "response": [] }, { "name": "Cancel Runtime Session", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"resume_token\": \"{{resume_token}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/cancel", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "cancel" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Cancels the journey and rejects further continuation. Requires the matching protected session resume token." }, "response": [] }, { "name": "Reset Runtime Session Routing", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"resume_token\": \"{{resume_token}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/reset", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "reset" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Clears the pinned Flow before a deliberate new routing decision in the same active session. Requires the matching protected session resume token." }, "response": [] }, { "name": "Get User Context", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/users/:user_id/context", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "users", ":user_id", "context" ], "variable": [ { "key": "user_id", "value": "{{user_id}}" } ] }, "description": "Returns persisted user preferences and commerce context.\n\nExpected result: conversation state, persisted messages, or user context. Use these endpoints to keep customer conversations consistent across frontend sessions.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Update User Context", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"preferences\": {\n \"currency\": \"USD\",\n \"locale\": \"en-US\"\n },\n \"commerce\": {\n \"preferred_categories\": [\n \"shoes\",\n \"electronics\"\n ]\n },\n \"metadata\": {\n \"consent\": true\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/users/:user_id/context", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "users", ":user_id", "context" ], "variable": [ { "key": "user_id", "value": "{{user_id}}" } ] }, "description": "Updates user-level context used by flows and routing.\n\nExpected result: conversation state, persisted messages, or user context. Use these endpoints to keep customer conversations consistent across frontend sessions.\n\nOperational note: This request updates an existing resource. Confirm the path variables and body values before running it." }, "response": [] }, { "name": "Get Runtime Session Status", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/status", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "status" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Read-only effective session status for the authenticated realm. Returns 200 for active, expired, completed, or cancelled with session_id, status, expires_at, completed_at, last_activity_at, and updated_at. No resume token required. Unknown ID: 404 SESSION_NOT_FOUND; malformed ID: 400 INVALID_SESSION_ID." }, "response": [] }, { "name": "Refresh Runtime Session Token", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"resume_token\": \"{{resume_token}}\",\n \"ttl_seconds\": 86400,\n \"chat_id\": \"{{chat_id}}\",\n \"metadata\": {\n \"locale\": \"az-AZ\",\n \"client\": \"client-ai\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/resume-token/refresh", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "resume-token", "refresh" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Rotates a session token and optionally updates chat_id and metadata. Omit a field to preserve it; chat_id empty string clears current association; supplied metadata replaces the object. Prior chats, messages, and logs remain. Requires the current valid resume token before expiry." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Session token refreshed\", function () { pm.expect(pm.response.code).to.eql(200); });", "const json = pm.response.json();", "pm.expect(json.session_id).to.eql(pm.variables.replaceIn('{{session_id}}'));", "pm.expect(json.previous_token_invalidated).to.eql(true);", "pm.collectionVariables.set('resume_token', json.resume_token || '');", "pm.environment.set('resume_token', json.resume_token || '');" ] } } ], "response": [] }, { "name": "Recover Runtime Session", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"ttl_seconds\": 86400,\n \"chat_id\": \"{{chat_id}}\",\n \"metadata\": {\n \"locale\": \"az-AZ\",\n \"client\": \"client-ai\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions/:session_id/resume-token/recover", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions", ":session_id", "resume-token", "recover" ], "variable": [ { "key": "session_id", "value": "{{session_id}}" } ] }, "description": "Rotates a session token and optionally updates chat_id and metadata. Omit a field to preserve it; chat_id empty string clears current association; supplied metadata replaces the object. Prior chats, messages, and logs remain. Requires a Realm service bearer token with runtime:session_recover; works before or after expiry without the previous resume token. Completed and cancelled are terminal." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Session recovered\", function () { pm.expect(pm.response.code).to.eql(200); });", "const json = pm.response.json();", "pm.expect(json.session_id).to.eql(pm.variables.replaceIn('{{session_id}}'));", "pm.expect(json.recovered).to.eql(true);", "pm.collectionVariables.set('resume_token', json.resume_token || '');", "pm.environment.set('resume_token', json.resume_token || '');" ] } } ], "response": [] }, { "name": "Create Non-Expiring Runtime Session", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"agent_id\": \"{{agent_id}}\",\n \"subject_type\": \"external\",\n \"subject_id\": \"{{customer_subject_id}}\",\n \"channel\": \"web\",\n \"ttl_seconds\": 0,\n \"metadata\": {\n \"locale\": \"en-US\",\n \"client\": \"client-ai\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/sessions", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "sessions" ] }, "description": "Creates a non-expiring session for an explicitly approved server-to-server integration. Requires runtime:session_non_expiring and returns expires_at=null. Complete or cancel the session explicitly." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test(\"Non-expiring session created\", function () { pm.expect(pm.response.code).to.be.oneOf([200, 201]); });", "const json = pm.response.json();", "pm.expect(json.expires_at).to.eql(null);", "pm.collectionVariables.set('session_id', json.session_id || json.id || '');", "pm.environment.set('session_id', json.session_id || json.id || '');", "pm.collectionVariables.set('resume_token', json.resume_token || '');", "pm.environment.set('resume_token', json.resume_token || '');" ] } } ], "response": [] } ] }, { "name": "Usages and Transactions", "description": "# Usages and Transactions\n\nThis section supports operational reporting, cost tracking, transaction counting, and customer billing exports. ACP Engine records AI usage, MCP tool execution, product listing transactions, payment completion transactions, and other runtime activity.\n\n## Recommended Usage\n1. Use `List Usage Records` to inspect individual records during testing.\n2. Use `Get Usage Summary` for manager totals.\n3. Use `Get Transaction Summary by Tool` to understand which MCP tools are generating activity.\n4. Use `Export Usage Report` for customer billing, audit, or monthly reporting workflows.\n\n## Request Guide\n- `List Usage Records`: returns paginated usage records filtered by realm, agent, session, or transaction type.\n- `Get Usage Summary`: returns total records, total transactions, token totals, and cost totals.\n- `Get Transaction Summary by Tool`: groups transaction and cost metrics by MCP tool name.\n- `Export Usage Report`: creates a report export grouped by fields such as agent, tool, and transaction type.\n\n## Transaction Types\n- `PAYMENT_COMPLETE`: successful payment or checkout completion events.\n- `PRODUCT_LISTING`: product search, listing, recommendation, or product browsing events.\n- `OTHER`: general AI responses, clarification, support, and non-commerce runtime actions.\n\n## Reporting Notes\n- Use ISO-8601 timestamps for `from` and `to` query/body fields.\n- Use `limit` and `offset` for pagination.\n- Use `session_id` for conversation-level investigation and `agent_id` for assistant-level reporting.", "item": [ { "name": "List Usage Records", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/usages?realm_id={{realm_id}}&agent_id={{agent_id}}&session_id={{session_id}}&transaction_type=OTHER&limit=50&offset=0", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "usages" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}", "description": "Optional realm filter" }, { "key": "agent_id", "value": "{{agent_id}}", "description": "Optional agent filter" }, { "key": "session_id", "value": "{{session_id}}", "description": "Optional session filter" }, { "key": "transaction_type", "value": "OTHER", "description": "PAYMENT_COMPLETE, PRODUCT_LISTING, OTHER" }, { "key": "limit", "value": "50", "description": "Page size" }, { "key": "offset", "value": "0", "description": "Page offset" } ] }, "description": "Lists usage and transaction records with filtering and pagination.\n\nExpected result: usage records, summaries, grouped metrics, or export metadata for billing, audit, and operational reporting.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Get Usage Summary", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/usages/summary?realm_id={{realm_id}}&agent_id={{agent_id}}", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "usages", "summary" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}", "description": "Optional realm filter" }, { "key": "agent_id", "value": "{{agent_id}}", "description": "Optional agent filter" } ] }, "description": "Returns total records, transactions, tokens, and cost metrics.\n\nExpected result: usage records, summaries, grouped metrics, or export metadata for billing, audit, and operational reporting.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Get Transaction Summary by Tool", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/usages/tools/summary?realm_id={{realm_id}}&from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "usages", "tools", "summary" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}" }, { "key": "from", "value": "2026-05-01T00:00:00Z" }, { "key": "to", "value": "2026-05-31T23:59:59Z" } ] }, "description": "Returns call count, transaction count, and cost by MCP tool name.\n\nExpected result: usage records, summaries, grouped metrics, or export metadata for billing, audit, and operational reporting.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Export Usage Report", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"from\": \"2026-05-01T00:00:00Z\",\n \"to\": \"2026-05-31T23:59:59Z\",\n \"format\": \"csv\",\n \"group_by\": [\n \"agent_id\",\n \"transaction_type\",\n \"tool_name\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/usages/export", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "usages", "export" ] }, "description": "Creates a usage export for billing, audit, or customer reporting.\n\nExpected result: usage records, summaries, grouped metrics, or export metadata for billing, audit, and operational reporting.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] } ] }, { "name": "Observability", "description": "# Observability\n\nObservability endpoints expose logs, traces, metrics, and alert configuration for ACP Engine operations. They help customer teams understand request behavior across frontend, engine, provider, routing, and MCP layers.\n\n## Recommended Usage\n1. Use `Get Metrics Snapshot` to review latency, error rates, request volume, and MCP performance.\n2. Use `List Request Logs` to inspect structured events for a realm.\n3. Use `Get Trace` when investigating a specific end-to-end request.\n4. Use `Create Alert Rule` to define operational thresholds.\n\n## Request Guide\n- `List Request Logs`: returns API, AI, MCP, routing, and transaction logs.\n- `Get Trace`: returns the end-to-end request path from client to ACP Engine to downstream MCP/provider.\n- `Get Metrics Snapshot`: returns aggregated operational metrics for a time window.\n- `Create Alert Rule`: configures threshold-based alerts for runtime operations.\n\n## Integration Notes\n- Use `trace_id` from responses or logs to correlate behavior across systems.\n- Metrics are useful for customer SLAs and internal support manager views.\n- Alert rules should be aligned with production support ownership and escalation channels.", "item": [ { "name": "List Request Logs", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/observability/logs?realm_id={{realm_id}}&level=info&limit=100", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "observability", "logs" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}" }, { "key": "level", "value": "info" }, { "key": "limit", "value": "100" } ] }, "description": "Returns structured API, AI, MCP, and routing logs.\n\nExpected result: logs, traces, metrics, or alert settings that help customer teams monitor runtime behavior and investigate request paths.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Get Trace", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/observability/traces/:trace_id", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "observability", "traces", ":trace_id" ], "variable": [ { "key": "trace_id", "value": "{{trace_id}}" } ] }, "description": "Returns end-to-end trace data for frontend to platform to MCP calls.\n\nExpected result: logs, traces, metrics, or alert settings that help customer teams monitor runtime behavior and investigate request paths.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Get Metrics Snapshot", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/observability/metrics?realm_id={{realm_id}}&window=1h", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "observability", "metrics" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}" }, { "key": "window", "value": "1h" } ] }, "description": "Returns request counts, latency, error rates, provider usage, and MCP tool performance.\n\nExpected result: logs, traces, metrics, or alert settings that help customer teams monitor runtime behavior and investigate request paths.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create Alert Rule", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"name\": \"MCP Error Rate Alert\",\n \"metric\": \"mcp.error_rate\",\n \"operator\": \">\",\n \"threshold\": 0.05,\n \"window\": \"5m\",\n \"channels\": [\n \"email\"\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/observability/alerts", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "observability", "alerts" ] }, "description": "Creates an operational alert rule for runtime monitoring.\n\nExpected result: logs, traces, metrics, or alert settings that help customer teams monitor runtime behavior and investigate request paths.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] } ] }, { "name": "SDK and Integration", "description": "# SDK and Integration\n\nThis section helps frontend and backend teams bootstrap customer integrations. SDK configuration centralizes public runtime metadata, while integration client endpoints manage customer applications that connect to ACP Engine.\n\n## Recommended Usage\n1. Run `Get SDK Configuration` during frontend initialization to retrieve public runtime metadata.\n2. Create integration clients for customer web, mobile, kiosk, or backend applications.\n3. Rotate integration secrets through the rotation endpoint when credentials need to be refreshed.\n\n## Request Guide\n- `Get SDK Configuration`: returns customer-facing SDK bootstrap settings such as theme, enabled features, default flow, and public integration metadata.\n- `Create Integration Client`: registers a customer frontend or backend application with allowed origins and default flow.\n- `Rotate Integration Client Secret`: issues a new secret for an integration client.\n\n## Integration Notes\n- Web clients should use allowed origins to restrict browser-based usage.\n- Backend clients should use service identities and rotate secrets on a regular schedule.\n- SDK configuration allows frontend teams to avoid hardcoding flow IDs, theme metadata, and feature switches.", "item": [ { "name": "Get SDK Configuration", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/sdk/config?realm_id={{realm_id}}&channel=web", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "sdk", "config" ], "query": [ { "key": "realm_id", "value": "{{realm_id}}" }, { "key": "channel", "value": "web" } ] }, "description": "Returns public configuration needed by a frontend SDK or customer application during startup. This can include default flow, enabled features, theme metadata, channel settings, and integration hints.\n\nUse this request to reduce hardcoded configuration in customer frontends.\n\nExpected result: client bootstrap settings or integration client credentials. Use these endpoints when connecting customer web, mobile, or backend applications to ACP Engine.\n\nOperational note: This is a read-only request and can be used safely during validation or customer demos." }, "response": [] }, { "name": "Create Integration Client", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"realm_id\": \"{{realm_id}}\",\n \"name\": \"Customer Web Frontend\",\n \"type\": \"web\",\n \"allowed_origins\": [\n \"https://customer.example.com\"\n ],\n \"default_flow_id\": \"{{flow_id}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/integrations/clients", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "integrations", "clients" ] }, "description": "Registers a frontend or backend integration client for ACP Engine.\n\nExpected result: client bootstrap settings or integration client credentials. Use these endpoints when connecting customer web, mobile, or backend applications to ACP Engine.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] }, { "name": "Rotate Integration Client Secret", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"reason\": \"scheduled_rotation\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/integrations/clients/:id/rotate-secret", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "integrations", "clients", ":id", "rotate-secret" ], "variable": [ { "key": "id", "value": "{{service_id}}" } ] }, "description": "Rotates an integration client secret and returns the new secret once.\n\nExpected result: client bootstrap settings or integration client credentials. Use these endpoints when connecting customer web, mobile, or backend applications to ACP Engine.\n\nOperational note: This request creates, executes, evaluates, or triggers an operation. Review the JSON body before running it in shared environments." }, "response": [] } ] }, { "name": "Runtime - Durable Execution and Configuration", "description": "Current versioned runtime, portable configuration, anonymous data, trigger, and webhook requests. Prefer these requests for new integrations.", "item": [ { "name": "Execute Runtime Contract", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "Idempotency-Key", "value": "postman-runtime-journey-1", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"version\": \"2026-08-22\",\n \"agent_id\": \"{{agent_id}}\",\n \"session_id\": \"{{session_id}}\",\n \"resume_token\": \"{{resume_token}}\",\n \"channel\": \"server\",\n \"input\": {\n \"message\": \"Find black running shoes under 150 USD.\"\n },\n \"client_capabilities\": {\n \"actions\": [\n \"RESPOND\",\n \"DATA_RESULT\",\n \"APPROVAL_REQUIRED\"\n ]\n },\n \"idempotency_key\": \"postman-runtime-journey-1\",\n \"mode\": \"sync\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/execute", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "execute" ] }, "description": "Runs the versioned structured contract without `flow_id`, so ACP applies the shared automatic Flow resolver. Add `flow_id` only for deliberate explicit execution." }, "response": [] }, { "name": "List Durable Executions", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/executions", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "executions" ] }, "description": "Lists durable executions in the authenticated realm." }, "response": [] }, { "name": "Get Configuration Schema", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/configuration/schema", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "configuration", "schema" ] }, "description": "Reads the versioned portable configuration schema. The caller needs configuration:read." }, "response": [] }, { "name": "Export Realm Configuration", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/runtime/configuration/export", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "configuration", "export" ] }, "description": "Exports a secret-free realm bundle with stable name references. The caller needs configuration:read." }, "response": [] }, { "name": "Plan Configuration Deployment", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"dry_run\": true,\n \"bundle\": {\n \"version\": \"2026-08-22\",\n \"agents\": [],\n \"flows\": [],\n \"prompts\": [],\n \"providers\": [],\n \"mcp_servers\": [],\n \"routing_rules\": []\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/configuration/deploy", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "configuration", "deploy" ] }, "description": "Validates and diffs a portable bundle without changing state. Change dry_run to false only after reviewing the plan; the caller needs configuration:write." }, "response": [] }, { "name": "Record Anonymous Data Event", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event_type\": \"product.search\",\n \"channel\": \"web\",\n \"properties\": {\n \"query_category\": \"running_shoes\",\n \"result_count\": 8\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/data/events", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "data", "events" ] }, "description": "Records an anonymous realm-scoped event after server-side PII removal and identifier pseudonymization. Do not send direct identifiers." }, "response": [] }, { "name": "Query Anonymous Data", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/data/query?event_type=product.search&limit=25", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "data", "query" ], "query": [ { "key": "event_type", "value": "product.search" }, { "key": "limit", "value": "25" } ] }, "description": "Queries anonymous event data within the authenticated realm." }, "response": [] }, { "name": "Publish Flow Draft", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows/{{flow_id}}/publish", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", "{{flow_id}}", "publish" ] }, "description": "Compiles and publishes a compatible draft. If fixtures exist, all fixtures must pass against the current draft before this request succeeds." }, "response": [] }, { "name": "Fire Flow Trigger", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event_id\": \"postman-flow-event-1\",\n \"payload\": {\n \"source\": \"postman\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/v1/runtime/flows/{{flow_id}}/triggers/{{trigger_id}}/fire", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "runtime", "flows", "{{flow_id}}", "triggers", "{{trigger_id}}", "fire" ] }, "description": "Fires an authenticated flow trigger. Reuse the same event_id only when intentionally testing duplicate delivery." }, "response": [] }, { "name": "Send Catalog Webhook", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{merchant_api_key}}", "type": "string" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" }, { "key": "X-Webhook-Event-ID", "value": "postman-catalog-event-1", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"event\": \"product.upserted\",\n \"direction\": \"inbound\",\n \"source\": \"postman\",\n \"product\": {\n \"storeId\": \"{{store_id}}\",\n \"name\": \"Postman Test Product\",\n \"sku\": \"postman-test-product\",\n \"price\": 99.9,\n \"currency\": \"USD\",\n \"status\": \"active\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/webhooks/catalog", "host": [ "{{base_url}}" ], "path": [ "api", "webhooks", "catalog" ] }, "description": "Sends an idempotent Catalog webhook. X-Webhook-Event-ID is required; a repeated event ID for the same key returns 200 with duplicate: true." }, "response": [] } ] } ] }