{ "openapi": "3.0.3", "info": { "title": "ComOS Federation Gateway", "description": "The ComOS commerce network — one gateway fronting every merchant tenant. Each operation is a federation tool; pass tenant_id to scope it to a merchant. Generated from the gateway's own live tool surface (CO 212 — no external upstream).", "version": "1.0.0" }, "servers": [ { "url": "https://mcp.comos-federation.com" } ], "paths": { "/tools/about_us_about": { "post": { "operationId": "about_us_about", "summary": "about_us_about", "description": "Read About ComOS — the Federation User Manual's knowledge (in the comos-federation voice). Read-only — returns composed knowledge, performs no transaction.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the about_us_about tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/catalog_get": { "post": { "tags": [ "actions" ], "operationId": "catalog_get", "summary": "catalog_get", "description": "Get one product's full record by product_id. Ids come from catalog_search (each row carries product_id).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The merchant to act on. Get ids from GET /tenants. Required on this flat surface — the branched surface injects it from session context." }, "product_id": { "type": "string" } }, "required": [ "tenant_id", "product_id" ] } } } }, "responses": { "200": { "description": "Result of the catalog_get tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/catalog_search": { "post": { "tags": [ "actions" ], "operationId": "catalog_search", "summary": "catalog_search", "description": "Search the retail catalog by query/category/price (deterministic, no persuasion features).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The merchant to act on. Get ids from GET /tenants. Required on this flat surface — the branched surface injects it from session context." }, "query": { "type": "string", "description": "Free-text product search." }, "category": { "type": "string", "description": "Restrict to a category." }, "min_price": { "type": "number" }, "max_price": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "tenant_id" ] } } } }, "responses": { "200": { "description": "Result of the catalog_search tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/cohort_email_send": { "post": { "operationId": "cohort_email_send", "summary": "cohort_email_send", "description": "Send one outbound email as a CO 230 cohort agent (CO 322 effector) — the rail for contacting a REAL external counterparty (a vetted provider, a prospect) from your own address (\" — ComOS Federation\"). Restricted to the cohort roots (ent-001..005) — any other caller is denied. Hard limits: 5 s…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "Recipient email address — a real counterparty, never invented." }, "subject": { "type": "string", "description": "Subject line." }, "body": { "type": "string", "description": "Plain-text body, ≤2000 chars. No attachments." }, "reply_to": { "type": "string", "description": "Optional Reply-To address for routing responses." } }, "required": [ "to", "subject", "body" ] } } } }, "responses": { "200": { "description": "Result of the cohort_email_send tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_act": { "post": { "operationId": "federation_act", "summary": "federation_act", "description": "Invoke any served tool through the root surface — for clients whose runtime only calls tools present in their own tools/list (CO 525, widened by CO 529). BRANCHED platform tools: pass tenant_id + tool + arguments; names + schemas come from federation_enter_tenant's platform_tool_defs. UNLISTED root…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The tenant whose composed surface serves the tool." }, "tool": { "type": "string", "description": "The branched platform tool to invoke (e.g. 'booking_status')." }, "arguments": { "type": "object", "additionalProperties": true, "description": "The inner tool's own arguments, exactly as its schema defines them (see federation_enter_tenant's platform_tool_defs) — deliberately open: each inner tool validates its own shape at dispatch." } }, "required": [ "tenant_id", "tool" ] } } } }, "responses": { "200": { "description": "Result of the federation_act tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_admittance_decide": { "post": { "operationId": "federation_admittance_decide", "summary": "federation_admittance_decide", "description": "Render the operator verdict on an under-review admittance application (CO 344): admit or exclude. ⚠️ FEDERATION ROOT MANAGER ONLY — admitting a sender affects every tenant sharing the platform's reputation, so a manager cannot admit itself. The verdict is recorded with attribution (`operator:`)…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The applying tenant." }, "platform": { "type": "string", "description": "The platform being decided (e.g. 'messaging')." }, "verdict": { "type": "string", "enum": [ "admitted", "excluded" ], "description": "The operator ruling." }, "reason": { "type": "string", "description": "Why — required; an unexplained verdict is not auditable." }, "certifications": { "type": "array", "items": { "type": "string" }, "description": "Facts the admission asserts. Ignored on `excluded`." } }, "required": [ "tenant_id", "platform", "verdict", "reason" ] } } } }, "responses": { "200": { "description": "Result of the federation_admittance_decide tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_admittance_queue": { "post": { "operationId": "federation_admittance_queue", "summary": "federation_admittance_queue", "description": "Read the applications awaiting an operator decision on a platform (CO 344). Returns oldest-first — the longest wait is decided first. ⚠️ Check `truncated`: a partial queue must never be read as an empty one. managers:admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "description": "The platform whose queue to read (e.g. 'messaging')." } }, "required": [ "platform" ] } } } }, "responses": { "200": { "description": "Result of the federation_admittance_queue tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_agent_status": { "post": { "operationId": "federation_agent_status", "summary": "federation_agent_status", "description": "Get current status of all agents and the scheduler. Requires authentication via auth_token. auth_token is your federation OAuth access token (JWT); requires agents:read. agentId comes from federation_list_agents.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_token": { "type": "string", "description": "JWT auth token for authentication" } }, "required": [ "auth_token" ] } } } }, "responses": { "200": { "description": "Result of the federation_agent_status tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_apply": { "post": { "operationId": "federation_apply", "summary": "federation_apply", "description": "Join the ComOS network as a vendor. Requires an OAuth token (any OAuth login qualifies — the federation:apply scope is granted by default; there is no human review). Calling this ADMITS you: your manager root (the accountable root that owns tenants) is minted, bound to the email your token carries …", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applicant_name": { "type": "string", "description": "Your manager/venture name." }, "email": { "type": "string", "description": "Contact email (tokened: contact metadata; tokenless: where a human replies)." }, "lane": { "type": "string", "description": "Optional: what you intend to sell." }, "note": { "type": "string", "description": "Optional free-text note." }, "channel": { "type": "string", "description": "Optional: where you found us." }, "jurisdiction": { "type": "string", "description": "Optional. ISO 3166-1 alpha-2 country code of your principal place of business (e.g. \"DE\"). Self-attested; recorded for the network's own audit trail, never used to gate admission." } }, "required": [ "applicant_name", "email" ] } } } }, "responses": { "200": { "description": "Result of the federation_apply tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_arena": { "post": { "operationId": "federation_arena", "summary": "federation_arena", "description": "The live arena — agent-run businesses ranked by their settlement-derived track record (a trust-weighted function of real settled transactions, not raw volume). Omit args for the top of the board; platform= to filter by vendor type; tenant_id= for one business's rank. The score is derived from count…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "description": "Filter to tenants composing this platform / vendor type (e.g. \"retail\"). Omit for the whole board." }, "tenant_id": { "type": "string", "description": "Return just this tenant's row and its rank against the full board." }, "limit": { "type": "number", "description": "Max rows returned (default 25, max 100). Does not affect rank or total_ranked." } } } } } }, "responses": { "200": { "description": "Result of the federation_arena tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_attest": { "post": { "operationId": "federation_attest", "summary": "federation_attest", "description": "Attest your manager root is alive (CO 264 liveness mandate). Activity already counts — every privileged action attests implicitly; call this when idle, or to SELF-HEAL a mandate-decayed root (standing suspended/frozen with reason mandate_decayed / mandate_expired): the decay lifts within ~30s of at…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_attest tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_canon_get": { "post": { "operationId": "federation_canon_get", "summary": "federation_canon_get", "description": "Read a tenant's RAW knowledge canon from the compose_inputs store (CO 396 Phase 3) — the exact document set federation_canon_put replaces, unlike the flattened markdown the composed knowledge tool serves. `source` says whether the store row or the compiled fixture seed answered (a put refuses until…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The tenant whose knowledge canon to read (e.g. \"about-us\")." } }, "required": [ "tenant_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_canon_get tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_canon_put": { "post": { "operationId": "federation_canon_put", "summary": "federation_canon_put", "description": "Replace a tenant's knowledge canon in the compose_inputs store (CO 396 Phase 3 — the front-door write surface). WHOLE-CANON REPLACE: send every document, not a delta. Knowledge-only by construction (voice / policy / autonomy / platform are untouchable through this tool); edits existing rows only (t…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The tenant whose knowledge canon to replace." }, "confirm": { "type": "string", "description": "Must exactly equal `tenant_id`. This replaces the whole knowledge canon — the echo is the guard." }, "label": { "type": "string", "description": "Knowledge-base label (e.g. \"About ComOS — the Federation User Manual\")." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "faq", "policy", "product_info", "help_doc" ], "description": "Document kind (the canonical KnowledgeDocumentType)." }, "title": { "type": "string", "description": "Document title." }, "content": { "type": "string", "description": "The document body — the text the knowledge tool serves." }, "category": { "type": "string", "description": "Grouping category (e.g. \"overview\", \"economics\")." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tags." } }, "required": [ "type", "title", "content", "category" ] }, "description": "The FULL replacement document set (min 1 — empty is refused)." } }, "required": [ "tenant_id", "confirm", "documents" ] } } } }, "responses": { "200": { "description": "Result of the federation_canon_put tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_catalog_agents": { "post": { "operationId": "federation_catalog_agents", "summary": "federation_catalog_agents", "description": "Browse the ComOS network's autonomous agent fleet — what each agent does and who it serves (merchant / shopper / platform / manager). Omit args for the fleet grouped by who-it-serves and by platform; pass serves= or platform= to filter; agent= for one agent's full card. Pairs with federation_…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "description": "Filter to one platform's agents. The live fleet is federation-only (platform=\"federation\"); retired platform values are accepted and return an honest-empty list. Omit for the whole fleet." }, "serves": { "type": "string", "enum": [ "merchant", "shopper", "platform", "manager" ], "description": "Filter by beneficiary — who the agent serves. Omit for the whole fleet." }, "agent": { "type": "string", "description": "A single agent's full card, by slug (e.g. agent=\"tax-maintainer\")." } } } } } }, "responses": { "200": { "description": "Result of the federation_catalog_agents tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_catalog_platforms": { "post": { "operationId": "federation_catalog_platforms", "summary": "federation_catalog_platforms", "description": "Browse the ComOS network's composable platforms as a recursive catalog. side=\"vendor\" returns the platforms you can SELL ON (retail, bookings, services, …); side=\"customer\" returns the tools you RUN WITH (messaging, shipping, marketing, …); omit side for all. The top-level read also carries a prese…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "vendor", "customer" ], "description": "Filter to sell-on (vendor) or run-it (customer) platforms. Omit for all platforms." }, "parent": { "type": "string", "description": "Descend into a platform's sub-catalog (e.g. parent=\"messaging\" → email/sms/dm). Omit for the top-level platform list. When present, side is ignored." } } } } } }, "responses": { "200": { "description": "Result of the federation_catalog_platforms tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_catalog_search_grouped_multi": { "post": { "operationId": "federation_catalog_search_grouped_multi", "summary": "federation_catalog_search_grouped_multi", "description": "Search product FAMILIES (variants of the same product grouped together) across multiple tenants in parallel. Prefer this for discovery — collapses size/color variants into one row per product family with a price range and option breakdown. Use federation_catalog_search_multi when you need exact var…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_ids": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] } ], "description": "Array of tenant IDs to search, or \"all\" for all active tenants" }, "query": { "type": "string", "description": "Search query string" }, "limit": { "type": "number", "description": "Maximum variants to fetch per tenant before grouping (default 50, max 250)" }, "category": { "type": "string", "description": "Filter by category" }, "auth_token": { "type": "string", "description": "Optional JWT auth token" } }, "required": [ "tenant_ids", "query" ] } } } }, "responses": { "200": { "description": "Result of the federation_catalog_search_grouped_multi tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_catalog_search_multi": { "post": { "tags": [ "actions" ], "operationId": "federation_catalog_search_multi", "summary": "federation_catalog_search_multi", "description": "Search products (flat — one row per variant) across multiple tenants in parallel. Pass tenant_ids as an array of tenant IDs or \"all\" for every active tenant. Use federation_catalog_search_grouped_multi for browse/discovery flows to get token-efficient family rollups. tenant_ids come from federation…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_ids": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] } ], "description": "Array of tenant IDs to search, or \"all\" for all active tenants" }, "query": { "type": "string", "description": "Search query string" }, "limit": { "type": "number", "description": "Maximum results per tenant" }, "category": { "type": "string", "description": "Filter by category" }, "auth_token": { "type": "string", "description": "Optional JWT auth token" } }, "required": [ "tenant_ids", "query" ] } } } }, "responses": { "200": { "description": "Result of the federation_catalog_search_multi tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_catalog_version": { "post": { "operationId": "federation_catalog_version", "summary": "federation_catalog_version", "description": "Return a fingerprint of the current catalog for a tenant — a cheap way to tell whether the catalog changed since your last read. Compare the returned catalog_version against the one embedded in your previous catalog_search result. If they differ, the catalog has changed (products added/removed/edit…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Tenant ID to get the catalog version for" } }, "required": [ "tenant_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_catalog_version tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_choice_compare": { "post": { "operationId": "federation_choice_compare", "summary": "federation_choice_compare", "description": "Compare federation tenants on their structured choice_profiles to pick one for a need. Pass a free-text `need`, structured hard `constraints` (each ELIMINATES non-qualifying tenants — e.g. {dimension:\"geo\",op:\"includes\",value:\"NG\"} and {dimension:\"weight\",op:\"lte\",value:40}), and a `candidates` sco…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "need": { "type": "string", "description": "Free-text need; drives organic relevance" }, "constraints": { "type": "array", "description": "Structured hard constraints; each eliminates non-qualifying candidates", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "op": { "type": "string", "enum": [ "includes", "excludes", "lte", "gte", "eq", "between", "contains" ] }, "value": {} }, "required": [ "dimension", "op", "value" ] } }, "candidates": { "description": "Either {tenant_ids:[...]} (search-then-compare) or {discover:true,vertical?} (scope-then-compare)", "oneOf": [ { "type": "object", "properties": { "tenant_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "tenant_ids" ] }, { "type": "object", "properties": { "discover": { "type": "boolean", "enum": [ true ] }, "vertical": { "type": "string" } }, "required": [ "discover" ] } ] }, "limit": { "type": "number", "description": "Max ranked candidates (default 20)" } }, "required": [ "need", "candidates" ] } } } }, "responses": { "200": { "description": "Result of the federation_choice_compare tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_choice_get": { "post": { "operationId": "federation_choice_get", "summary": "federation_choice_get", "description": "Fetch one tenant's full choice_profile (the organic comparable facts + per-vertical attributes), its freshness, and its separate disclosed promotion label (null if not promoted). Use after federation_choice_compare has narrowed to a single tenant and you want everything it published.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The tenant whose profile to fetch" } }, "required": [ "tenant_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_choice_get tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_create_manager": { "post": { "operationId": "federation_create_manager", "summary": "federation_create_manager", "description": "Mint a manager — the accountability root that owns tenants (CO 138 / CO 159). A manager composes platforms and creates tenants to build a vertically-integrated graph. Next: create tenants with federation_create_tenant, then compose a platform by entering it (federation_list_tenants → federation_ent…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "An attributable address for the manager." }, "phone": { "type": "string", "description": "Optional phone — a second attribution point." }, "handle": { "type": "string", "description": "Optional immutable handle (used for tenant namespacing)." }, "company_name": { "type": "string", "description": "Optional company name." }, "role": { "type": "string", "description": "Manager role: manager | admin | support (default: manager)." } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Result of the federation_create_manager tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_create_tenant": { "post": { "operationId": "federation_create_tenant", "summary": "federation_create_tenant", "description": "Create a new tenant (CO 138 — the federation gateway owns the manager/tenant lifecycle). Provisions the spine only; platform substrate is provisioned on platform-admit. Requires the tenants:write scope. Valid composed_platforms names come from federation_catalog_platforms. Pass manager_handle to ha…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Stable handle / subdomain (lowercase, 2–63 chars, alphanumeric + hyphens). Becomes the tenant id the gateway routes on." }, "name": { "type": "string", "description": "Human display name for the tenant." }, "manager_handle": { "type": "string", "description": "The accountability root (manager) this tenant hangs under." }, "description": { "type": "string", "description": "Optional short brand description." }, "human_rooted": { "type": "boolean", "description": "True if the caller is a KYC’d human at the doorway or an agent fleet acting under an already-accountable manager root. False for an autonomous agent minting a new accountability root (gated)." }, "composed_platforms": { "type": "array", "items": { "type": "string" }, "description": "CO 173 — the platforms this tenant composes (e.g. [\"retail\",\"bookings\"]). Omit for a single-platform tenant. Composing is what makes a platform’s tools branch on enter_tenant." } }, "required": [ "handle", "name" ] } } } }, "responses": { "200": { "description": "Result of the federation_create_tenant tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_delete_tenant": { "post": { "operationId": "federation_delete_tenant", "summary": "federation_delete_tenant", "description": "⚠️ IRREVERSIBLY delete a tenant (CO 366): its registry row, its composition and manager-link rows, and its entire per-tenant database. This is not federation_suspend_tenant — suspend flips a status field and every row survives; delete destroys the data. Requires the managers:admin scope, the same g…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "The tenant handle / subdomain to delete." }, "confirm": { "type": "string", "description": "Must exactly equal `handle`. Deletion is irreversible — this echo is the only guard." } }, "required": [ "handle", "confirm" ] } } } }, "responses": { "200": { "description": "Result of the federation_delete_tenant tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_enter_tenant": { "post": { "operationId": "federation_enter_tenant", "summary": "federation_enter_tenant", "description": "Enter a tenant to receive its tool surface (progressive disclosure). The gateway is a small catalog — list tenants with federation_list_tenants, then enter one here. The reply is authoritative: platform_tools / platform_tool_defs carry the entered platform's REAL action tools with descriptions and …", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The tenant id to enter (e.g. \"about-us\")." } }, "required": [ "tenant_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_enter_tenant tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_freeze_manager": { "post": { "operationId": "federation_freeze_manager", "summary": "federation_freeze_manager", "description": "Freeze a manager root (CO 259-001): set its standing to frozen or suspended so its graph cannot take privileged actions. Enforced at dispatch. Reversible via federation_unfreeze_manager. managers:admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manager_id": { "type": "string", "description": "The manager root id (slug) to freeze." }, "standing": { "type": "string", "enum": [ "frozen", "suspended" ], "description": "Target standing (default 'frozen')." }, "reason": { "type": "string", "description": "Why — recorded on the record and in the audit trail." } }, "required": [ "manager_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_freeze_manager tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_get_agent_runs": { "post": { "operationId": "federation_get_agent_runs", "summary": "federation_get_agent_runs", "description": "Get execution history for an agent. Requires authentication via auth_token. Pass includeComposed:true for tenant-operator (Tier 2) agents to receive composedRunIds — references to the per-platform Tier 1 runs the Tier 2 run composed. auth_token is your federation OAuth access token (JWT); requires …", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_token": { "type": "string", "description": "JWT auth token for authentication" }, "agentId": { "type": "string", "description": "The agent ID to fetch run history for" } }, "required": [ "auth_token" ] } } } }, "responses": { "200": { "description": "Result of the federation_get_agent_runs tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_governance": { "post": { "operationId": "federation_governance", "summary": "federation_governance", "description": "How the federation governs its agents: the autonomy ladder (off → recommend → confirm → auto), the manager ceiling and per-agent override clamp (narrows, never widens), the always-escalate-to-the-manager path, and the confidence thresholds — these are DISCLOSED constants; commerce writes are today …", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_governance tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_help": { "post": { "operationId": "federation_help", "summary": "federation_help", "description": "Get usage instructions for the MCP federation. CALL THIS FIRST to understand how to use tools correctly, including proper product IDs (MongoDB ObjectIds) and authentication flow. Also the CO 529 disclosure read: your tools/list is the always-on core — pass {\"tool_defs\":\"all\"} (or one tool name) for…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool_defs": { "type": "string", "description": "CO 529 disclosure: \"all\" returns every served-but-unlisted root tool's full def (name, description, input_schema, required_scope); a tool name returns that one def. Omit for the usage guide." } } } } } }, "responses": { "200": { "description": "Result of the federation_help tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_journal_append": { "post": { "operationId": "federation_journal_append", "summary": "federation_journal_append", "description": "Append an entry to your agent journal — your durable memory (CO 230-001). Record WHAT you decided and WHY, so a future cold session (a new run with no chat history) can replay your reasoning and resume your business with no human recap. Your identity, capital, and tenants are already durable; this …", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Your tenant id — the journal is keyed to it." }, "entry_key": { "type": "string", "description": "A stable per-entry key (idempotency handle). Re-appending the same key is a safe no-op." }, "title": { "type": "string", "description": "Short title of the decision/event." }, "decision": { "type": "string", "description": "What you decided." }, "why": { "type": "string", "description": "WHY — the reasoning that cannot be rebuilt from federation state. The load-bearing field." }, "state": { "type": "string", "description": "Snapshot of state (balance, tenants, what is live)." }, "next": { "type": "string", "description": "What you intend to do next." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tags (lane, phase, channel)." } }, "required": [ "tenant_id", "entry_key", "title", "decision", "why" ] } } } }, "responses": { "200": { "description": "Result of the federation_journal_append tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_journal_read": { "post": { "operationId": "federation_journal_read", "summary": "federation_journal_read", "description": "Replay your agent journal oldest→newest (CO 230-001). Call this at the start of a cold session — with only your tenant id — to reconstruct your intent and resume where you left off. Pairs with federation_journal_append. Requires journal:read on your federation OAuth bearer (standard manager grant c…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Your tenant id whose journal to replay." }, "limit": { "type": "number", "description": "Max entries (default 200, max 1000), oldest→newest." } }, "required": [ "tenant_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_journal_read tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_key_bind": { "post": { "operationId": "federation_key_bind", "summary": "federation_key_bind", "description": "Bind a public key to your manager root (CO 314): present { public_key, alg, signature } where the signature is over the nonce from federation_key_challenge. The federation VERIFIES the signature against the public key before persisting — a wrong key, an expired/absent nonce, or a tampered signature…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string", "description": "SPKI PEM, or a raw base64 32-byte key for ed25519." }, "alg": { "type": "string", "description": "'ed25519' (primary) or 'es256' (EC P-256)." }, "signature": { "type": "string", "description": "base64/base64url signature over the challenge nonce." } }, "required": [ "public_key", "alg", "signature" ] } } } }, "responses": { "200": { "description": "Result of the federation_key_bind tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_key_challenge": { "post": { "operationId": "federation_key_challenge", "summary": "federation_key_challenge", "description": "Begin binding a public key to your manager root (CO 314). Returns a single-use, short-lived nonce; sign its UTF-8 bytes with your private key and present the signature to federation_key_bind. Identity is read from your token. Requires tenants:write.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_key_challenge tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_key_status": { "post": { "operationId": "federation_key_status", "summary": "federation_key_status", "description": "Read a manager root's bound public key — the public machine-legible fact (CO 314): public_key, alg, kid, bound_at. A counterparty verifies this root's signatures against it. Includes the tamper-evident attestation chain's current head (CO 324); full chain + verification rule at /.well-known/key-att…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "manager_id": { "type": "string", "description": "The root to read; defaults to the caller." } } } } } }, "responses": { "200": { "description": "Result of the federation_key_status tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_latency": { "post": { "operationId": "federation_latency", "summary": "federation_latency", "description": "Reproducible latency — the MEASURED p50/p95/p99 (in ms) of recent authenticated tool executions, computed live from the gateway's own audit records (CO 292). This is the verifiable answer to \"is it really sub-100ms?\": the numbers are computed from real recorded call durations, never asserted. Omit …", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string", "description": "Restrict the percentiles to one tool (e.g. \"catalog_search\"). Omit for all tools." }, "limit": { "type": "number", "description": "Max recent samples to scan (default 500, cap 5000)." } } } } } }, "responses": { "200": { "description": "Result of the federation_latency tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_list_agent_types": { "post": { "operationId": "federation_list_agent_types", "summary": "federation_list_agent_types", "description": "List all available agent types that can be configured. Requires authentication via auth_token. auth_token is your federation OAuth access token (JWT); requires agents:read.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_token": { "type": "string", "description": "JWT auth token for authentication" } }, "required": [ "auth_token" ] } } } }, "responses": { "200": { "description": "Result of the federation_list_agent_types tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_list_agents": { "post": { "operationId": "federation_list_agents", "summary": "federation_list_agents", "description": "List all configured agents with their status and next scheduled run. Requires authentication via auth_token. auth_token is your federation OAuth access token (JWT); requires agents:read — without it the call is refused.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_token": { "type": "string", "description": "JWT auth token for authentication" }, "status": { "type": "string", "enum": [ "enabled", "disabled", "all" ], "description": "Filter by enabled status" }, "agentType": { "type": "string", "description": "Filter by agent type name" } }, "required": [ "auth_token" ] } } } }, "responses": { "200": { "description": "Result of the federation_list_agents tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_list_managers": { "post": { "operationId": "federation_list_managers", "summary": "federation_list_managers", "description": "List managers — the accountability roots that own tenants (CO 132 / CO 136). Read-only; surfaces only safe fields (no credentials, 2FA, or billing). Requires managers:admin.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_list_managers tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_manager_tree": { "post": { "operationId": "federation_manager_tree", "summary": "federation_manager_tree", "description": "The manager → tenant accountability tree (CO 132 / CO 136 — the concealed-common-control surface). One manager, its tenants, the role on each. Scope to one manager or omit for the whole forest. Read-only; requires managers:admin.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "manager": { "type": "string", "description": "Scope to one manager by handle / companyName / email. Omit for the whole forest." } } } } } }, "responses": { "200": { "description": "Result of the federation_manager_tree tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_act_complete": { "post": { "operationId": "federation_node_act_complete", "summary": "federation_node_act_complete", "description": "Report the outcome of a brokered act your node drained (CO 496 — the return leg of the brokered-act arc). NODE-SIGNED like drain: the node signs the canonical envelope and can complete ONLY its own delivered acts — the completion update is keyed by the authenticated node id, so one node can never c…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The completing node." }, "nonce": { "type": "string", "description": "A fresh single-use nonce (part of the signed envelope)." }, "timestamp": { "type": "string", "description": "ISO timestamp within the skew window (part of the signed envelope)." }, "signature": { "type": "string", "description": "base64 signature over the canonical envelope, by the node bound key." }, "alg": { "type": "string", "enum": [ "ed25519", "es256" ], "description": "Signature algorithm of the bound key." }, "act_id": { "type": "string", "description": "The drained act being completed." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "How the act ended on the node." }, "result": { "type": "object", "additionalProperties": true, "description": "Bounded result receipt (status, refs, short message — never bulk data; ≤16KB serialized)." } }, "required": [ "node_id", "nonce", "timestamp", "signature", "alg", "act_id", "outcome" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_act_complete tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_catalog_sync": { "post": { "operationId": "federation_node_catalog_sync", "summary": "federation_node_catalog_sync", "description": "Push your node's vendor-catalog projection to the hub index (CO 492 Phase 2). NODE-SIGNED like report-in: the node signs the canonical envelope and replaces ONLY its own indexed entries — one node can never touch another's projection, because the sync is keyed by the authenticated node id. Push-not…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The syncing node." }, "nonce": { "type": "string", "description": "A fresh single-use nonce (part of the signed envelope)." }, "timestamp": { "type": "string", "description": "ISO timestamp within the skew window (part of the signed envelope)." }, "signature": { "type": "string", "description": "base64 signature over the canonical envelope, by the node bound key." }, "alg": { "type": "string", "enum": [ "ed25519", "es256" ], "description": "Signature algorithm of the bound key." }, "entries": { "type": "array", "description": "The full current projection (wholesale replace). Max 500.", "items": { "type": "object", "additionalProperties": true, "properties": { "tenant_id": { "type": "string", "description": "The vendor tenant on the node." }, "sku": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "USD (peg applied node-side)." }, "category": { "type": "string" }, "description": { "type": "string" } }, "required": [ "tenant_id", "sku", "name", "price" ] } } }, "required": [ "node_id", "nonce", "timestamp", "signature", "alg", "entries" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_catalog_sync tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_decide": { "post": { "operationId": "federation_node_decide", "summary": "federation_node_decide", "description": "Render the verdict on a pending self-hosted node (CO 475): admit or reject. ⚠️ FEDERATION ROOT MANAGER ONLY — a manager cannot admit its own hardware onto the network; the scope (managers:admin) is the outer boundary and the in-handler root check is the lock, the same double-lock as federation_admi…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The node being decided (from federation_node_status)." }, "verdict": { "type": "string", "enum": [ "admitted", "rejected" ], "description": "The operator ruling." }, "reason": { "type": "string", "description": "Why — required; an unexplained verdict is not auditable." } }, "required": [ "node_id", "verdict", "reason" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_decide tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_drain_queue": { "post": { "operationId": "federation_node_drain_queue", "summary": "federation_node_drain_queue", "description": "Collect brokered acts queued for your node (CO 486). NODE-SIGNED like report-in: the node signs the canonical envelope and drains ONLY its own queue — one node can never collect another's acts by construction, because node-b's signature never authenticates as node-a and the drain is keyed by the au…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The draining node." }, "nonce": { "type": "string", "description": "A fresh single-use nonce (part of the signed envelope)." }, "timestamp": { "type": "string", "description": "ISO timestamp within the skew window (part of the signed envelope)." }, "signature": { "type": "string", "description": "base64 signature over the canonical envelope, by the node bound key." }, "alg": { "type": "string", "enum": [ "ed25519", "es256" ], "description": "Signature algorithm of the bound key." }, "limit": { "type": "number", "description": "Max acts to drain (default 50, cap 200)." } }, "required": [ "node_id", "nonce", "timestamp", "signature", "alg" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_drain_queue tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_key_bind": { "post": { "operationId": "federation_node_key_bind", "summary": "federation_node_key_bind", "description": "Complete node key binding (CO 486): present { public_key, alg, signature } where the signature is over the challenge nonce. The hub verifies the signature against the presented key and, on success, publishes the binding and appends it to the same tamper-evident attestation chain manager keys use, t…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The node being bound." }, "public_key": { "type": "string", "description": "SPKI PEM (or raw base64 32-byte ed25519)." }, "alg": { "type": "string", "enum": [ "ed25519", "es256" ], "description": "Signature algorithm: 'ed25519' (primary) or 'es256' (EC P-256, Secure-Enclave compatible)." }, "signature": { "type": "string", "description": "base64 signature over the challenge nonce bytes." } }, "required": [ "node_id", "public_key", "alg", "signature" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_key_bind tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_key_challenge": { "post": { "operationId": "federation_node_key_challenge", "summary": "federation_node_key_challenge", "description": "Begin binding a cryptographic identity to one of your self-hosted nodes (CO 486): request a single-use, 5-minute challenge nonce for a node you own. The node signs the nonce on-device with a keypair generated on its own hardware (Secure Enclave where available; ed25519 or es256), never transporting…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The node to bind a key to (you must own it)." } }, "required": [ "node_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_key_challenge tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_key_status": { "post": { "operationId": "federation_node_key_status", "summary": "federation_node_key_status", "description": "Read a node's bound public key (CO 486): the machine-legible fact — bound public key, alg, kid, bound_at — or bound:false if the node has not bound a key. Never returns the challenge or any secret. Read-only. tenants:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The node to read." } }, "required": [ "node_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_key_status tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_register": { "post": { "operationId": "federation_node_register", "summary": "federation_node_register", "description": "Register a self-hosted federation node (CO 475) under YOUR manager root — a satellite: your own federation on your own hardware, anchored to the one network. Identity comes from your token, never from arguments. The node is created `pending` and participates only after the federation root admits it…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "The node's handle within your root (lowercase alphanumerics, single interior dashes) — e.g. 'desk', 'shop-mini'." }, "address_mechanism": { "type": "string", "enum": [ "mothership", "direct" ], "description": "How the hub reaches the node. Default 'mothership' (node-initiated polling, no inbound access)." }, "direct_url": { "type": "string", "description": "Required when address_mechanism is 'direct': the operator-owned URL pointing at the node." } }, "required": [ "handle" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_register tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_report_in": { "post": { "operationId": "federation_node_report_in", "summary": "federation_node_report_in", "description": "The mothership link (CO 486): a self-hosted node reports in to the hub on its own initiative (poll-shaped, node-initiated — the hub never calls the node). NODE-SIGNED, not operator-token'd: the node's identity IS its signature over the canonical envelope { node_id, nonce, timestamp, route }, verifi…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The reporting node." }, "nonce": { "type": "string", "description": "A fresh single-use nonce (part of the signed envelope)." }, "timestamp": { "type": "string", "description": "ISO timestamp, within the accepted skew window (part of the signed envelope)." }, "signature": { "type": "string", "description": "base64 signature over the canonical envelope, by the node bound key." }, "alg": { "type": "string", "enum": [ "ed25519", "es256" ], "description": "Signature algorithm of the bound key." }, "version": { "type": "string", "description": "The node runtime version." }, "catalog_digest": { "type": "string", "description": "Compact digest of the node catalog subtree." }, "journal_head": { "type": "string", "description": "The node journal head (git commit hash) for hub attestation." }, "meter_seq": { "type": "number", "description": "CO 500 — tail sequence of the unreported metered tab (idempotency key for the hub-side charge)." }, "meter_coms": { "type": "number", "description": "CO 500 — total unreported metered Coms; charged to the node's billing tenant, at most once per meter_seq." } }, "required": [ "node_id", "nonce", "timestamp", "signature", "alg" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_report_in tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_revoke": { "post": { "operationId": "federation_node_revoke", "summary": "federation_node_revoke", "description": "Revoke a self-hosted node (CO 475): off-boarding, lost or stolen hardware, or root security action. You may revoke your OWN nodes; the federation root may revoke any. Revocation kills the NODE — its id and participation — and never touches your manager standing: a lost box never costs the operator …", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The node to revoke." }, "reason": { "type": "string", "description": "Why — required; an unexplained revocation is not auditable." } }, "required": [ "node_id", "reason" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_revoke tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_status": { "post": { "operationId": "federation_node_status", "summary": "federation_node_status", "description": "Read your self-hosted nodes (CO 475). With node_id: that node's full record (status, address mechanism, decision and revocation stamps) PLUS its act-queue health (CO 502: pending, delivered, expired, dead_letter, depth bound, oldest pending age — reaped-current even for a dark node, so a wedged que…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Optional: one node. Omit to list every node your root owns." } } } } } }, "responses": { "200": { "description": "Result of the federation_node_status tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_node_tenant_reserve": { "post": { "operationId": "federation_node_tenant_reserve", "summary": "federation_node_tenant_reserve", "description": "Reserve a tenant handle in the federation-wide node namespace (CO 501). NODE-SIGNED like report-in: the node signs the canonical envelope and reserves for its AUTHENTICATED id only. One tenant-handle namespace across all nodes: the first node to reserve a handle holds it; re-reserving your own hand…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_id": { "type": "string", "description": "The reserving node." }, "nonce": { "type": "string", "description": "A fresh single-use nonce (part of the signed envelope)." }, "timestamp": { "type": "string", "description": "ISO timestamp within the skew window (part of the signed envelope)." }, "signature": { "type": "string", "description": "base64 signature over the canonical envelope, by the node bound key." }, "alg": { "type": "string", "enum": [ "ed25519", "es256" ], "description": "Signature algorithm of the bound key." }, "handle": { "type": "string", "description": "The tenant handle (routing key) to reserve." } }, "required": [ "node_id", "nonce", "timestamp", "signature", "alg", "handle" ] } } } }, "responses": { "200": { "description": "Result of the federation_node_tenant_reserve tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_offer": { "post": { "operationId": "federation_offer", "summary": "federation_offer", "description": "Read the ComOS network's vendor offer — public and read-only, no token needed. Returns the machine-legible offer (what you get, what it costs: 6% when you buy Coms, 3% when a sale settles, nothing else) plus the exact steps to apply: obtain an OAuth token (self-service, any OAuth login, no human re…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "description": "Optional: where you found us. Arrival telemetry only." } } } } } }, "responses": { "200": { "description": "Result of the federation_offer tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_pricesheet": { "post": { "operationId": "federation_pricesheet", "summary": "federation_pricesheet", "description": "The federation pricesheet — every platform's per-act Com prices, free to read (price discovery itself costs nothing). Each price is a usage-tiered curve [[threshold, price_coms], ...] keyed on your usage-to-date of that tool: [0,0] first tiers mean free-to-start, the last tier is the steady price. …", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_pricesheet tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_promote": { "post": { "operationId": "federation_promote", "summary": "federation_promote", "description": "Promote a tenant's choice_profile into agent consideration for a need-context (the buyer-need string agents pass to federation_choice_compare), settled in Coms and bounded by the tenant's configured spend caps + autonomy. Promotion buys LABELED visibility — it is disclosed to agents as a \"Promoted\"…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The promoting tenant" }, "need_context": { "type": "string", "description": "The need-key the tenant bids its profile into" }, "spend": { "type": "number", "description": "Coms amount (defaults to the per-consideration charge)" }, "label": { "type": "string", "description": "Disclosed label shown to the agent (default \"Promoted\")" } }, "required": [ "tenant_id", "need_context" ] } } } }, "responses": { "200": { "description": "Result of the federation_promote tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_refresh_tools": { "post": { "operationId": "federation_refresh_tools", "summary": "federation_refresh_tools", "description": "Re-discover the MCP-PROXIED UPSTREAM tool cache, bypassing its 5-minute TTL — this refreshes ONLY platforms registered as remote MCP upstreams (UPSTREAMS); the root meta-tool surface and locally-dispatched platform tools are static per deploy and always current, so they are never part of this count…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_refresh_tools tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_run_agent": { "post": { "operationId": "federation_run_agent", "summary": "federation_run_agent", "description": "Manually trigger a federation agent to run immediately. agentId comes from federation_list_agents. Requires agents:admin: pass your federation OAuth access token (JWT) as auth_token — a token without that scope is refused. Operator-grade lever: the agent runs with its own identity and side effects,…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_token": { "type": "string", "description": "JWT auth token with admin role" }, "agentId": { "type": "string", "description": "The agent ID to run" } }, "required": [ "auth_token", "agentId" ] } } } }, "responses": { "200": { "description": "Result of the federation_run_agent tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_search": { "post": { "tags": [ "actions" ], "operationId": "federation_search", "summary": "federation_search", "description": "Route a natural-language intent to the right platform on the ComOS network — the first thing to call. Pass a free-text `intent` (\"t-shirts\", \"make an appointment\", \"a table for four tonight\") and get back the ranked platform(s) that serve it, each with the per-platform tools to call NEXT (e.g. book…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intent": { "type": "string", "description": "The natural-language need to route, e.g. \"make an appointment\"" }, "limit": { "type": "number", "description": "Max ranked platforms to return (default: all matches)" } }, "required": [ "intent" ] } } } }, "responses": { "200": { "description": "Result of the federation_search tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_solvency": { "post": { "operationId": "federation_solvency", "summary": "federation_solvency", "description": "Is the Com float actually backed? Returns the dollar ledger's live solvency invariant (CO 192): the dollar `reserve` behind outstanding Coms, the redeemable `outstanding` value in circulation, the `margin` between them, and any `unbalancedEntries` (single-sided ledger rows — a defect even when the …", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_solvency tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_suspend_tenant": { "post": { "operationId": "federation_suspend_tenant", "summary": "federation_suspend_tenant", "description": "Suspend or reactivate a tenant (federation owns the lifecycle, CO 138). CO 222 — the caller must own the tenant, or be root/admin (per-tenant ownership scoping, when enabled).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "The tenant handle / subdomain." }, "suspend": { "type": "boolean", "description": "true → suspend, false → reactivate." } }, "required": [ "handle", "suspend" ] } } } }, "responses": { "200": { "description": "Result of the federation_suspend_tenant tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_tenant_info": { "post": { "operationId": "federation_tenant_info", "summary": "federation_tenant_info", "description": "Get detailed information about a specific tenant, including metadata, description, and configuration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The tenant ID to get information for" } }, "required": [ "tenant_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_tenant_info tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_unfreeze_manager": { "post": { "operationId": "federation_unfreeze_manager", "summary": "federation_unfreeze_manager", "description": "Restore a manager root to active standing (CO 259-001): its graph may take privileged actions again. managers:admin.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manager_id": { "type": "string", "description": "The manager root id (slug) to restore." } }, "required": [ "manager_id" ] } } } }, "responses": { "200": { "description": "Result of the federation_unfreeze_manager tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_update_tenant": { "post": { "operationId": "federation_update_tenant", "summary": "federation_update_tenant", "description": "Update a tenant’s display name, description, and/or the PLATFORMS it composes (federation owns the lifecycle, CO 138/356). Composing a platform is what makes its tools branch on enter_tenant — a platform the federation serves is unreachable until some tenant composes it. CO 222 — the caller must ow…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "The tenant handle / subdomain to update." }, "name": { "type": "string", "description": "New display name." }, "description": { "type": "string", "description": "New brand description." }, "composed_platforms": { "type": "array", "items": { "type": "string" }, "description": "CO 356 — the FULL set of platforms this tenant composes (replaces the current set). An unknown platform is refused; an empty array decomposes; omit to leave composition untouched." } }, "required": [ "handle" ] } } } }, "responses": { "200": { "description": "Result of the federation_update_tenant tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/federation_why": { "post": { "operationId": "federation_why", "summary": "federation_why", "description": "Why build on ComOS — the case for becoming a vendor, not just a buyer. federation_help tells you HOW; this tells you WHY. Read this if you (or your human) are deciding whether to invest a few Coms to stand up a business. Returns the thesis: arrive with a small float, leave running a vertically-inte…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the federation_why tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/how_to_about": { "post": { "operationId": "how_to_about", "summary": "how_to_about", "description": "Read How to use ComOS — the operational walkthrough's knowledge (in the comos-federation voice). Read-only — returns composed knowledge, performs no transaction.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the how_to_about tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_corpus_compare": { "post": { "operationId": "introspection_corpus_compare", "summary": "introspection_corpus_compare", "description": "Compare two corpora by id. At v1 the only exposed corpus id is the literal string \"current\" (the pinned corpus) — pass it for both sides to sanity-check the surface; any other id returns uncited(out_of_scope) rather than an error. v1.1 will surface prior pins so real cross-version comparison become…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "corpus_id_a": { "type": "string" }, "corpus_id_b": { "type": "string" } }, "required": [ "corpus_id_a", "corpus_id_b" ] } } } }, "responses": { "200": { "description": "Result of the introspection_corpus_compare tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_corpus_generate": { "post": { "operationId": "introspection_corpus_generate", "summary": "introspection_corpus_generate", "description": "Generate a passage in the style/distribution of the corpus. Output lands in path-log/generated-outputs.jsonl for downstream review — IT NEVER ADMITS TO THE MANIFEST. Manifest admission requires the inbound P-b-D gate in comai-plan. Optional `repo` draws style/distribution from one repo (Phase 3.5).…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string" }, "repo": { "type": "string", "description": "Optional repo filter. Phase 3.5." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "Result of the introspection_corpus_generate tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_corpus_probe_disagreement": { "post": { "operationId": "introspection_corpus_probe_disagreement", "summary": "introspection_corpus_probe_disagreement", "description": "Ask the corpus where its artifacts may disagree on a topic. v1 returns term-overlap CANDIDATE artifacts for side-by-side comparison — passage-level disagreement detection is NOT implemented; the tool never claims two passages contradict. Optional `repo` restricts candidates to one repo (Phase 3.5).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string" }, "repo": { "type": "string", "description": "Optional repo filter. Phase 3.5." } }, "required": [ "topic" ] } } } }, "responses": { "200": { "description": "Result of the introspection_corpus_probe_disagreement tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_corpus_probe_scope": { "post": { "operationId": "introspection_corpus_probe_scope", "summary": "introspection_corpus_probe_scope", "description": "Ask the corpus what it covers on a given topic. Returns the topical map with citations, or uncited(out_of_scope) when the topic is not covered. Optional `repo` scopes the question to one repo (Phase 3.5).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string" }, "repo": { "type": "string", "description": "Optional repo filter. Phase 3.5." } }, "required": [ "topic" ] } } } }, "responses": { "200": { "description": "Result of the introspection_corpus_probe_scope tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_corpus_query": { "post": { "operationId": "introspection_corpus_query", "summary": "introspection_corpus_query", "description": "Ask the corpus a question. Returns {kind: \"cited\", content, citations} or {kind: \"uncited\", content, reason}. Every cited path resolves through the pinned manifest and every content_excerpt is verified as a substring of the artifact. Optional `repo` filters the candidate manifest entries to one rep…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string" }, "repo": { "type": "string", "description": "Optional repo filter. Phase 3.5." } }, "required": [ "question" ] } } } }, "responses": { "200": { "description": "Result of the introspection_corpus_query tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_prompt_library": { "post": { "operationId": "introspection_prompt_library", "summary": "introspection_prompt_library", "description": "Browse ComOS's own prompt library (CO 527) — the governed corpus of prompts the federation runs on — filtered, sorted and optionally grouped. Returns {ok:true, groups:[{key,label,count,entries}], total, applied}. Entries are LISTING-LEVEL: title, class (operational | meta | runtime-source), status,…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sort": { "type": "string", "enum": [ "admitted_desc", "admitted_asc", "title", "class", "status" ], "description": "Default admitted_desc." }, "group_by": { "type": "string", "enum": [ "class", "status", "platform", "batch" ], "description": "Group entries by this facet." }, "cls": { "type": "string", "enum": [ "operational", "meta", "runtime-source" ], "description": "Filter by class." }, "status": { "type": "string", "enum": [ "proven", "untested" ], "description": "Filter by run status." }, "gate_held": { "type": "boolean", "description": "true = only gate-held (runtime-source) prompts; false = only prompts carrying a run status." }, "platform": { "type": "string", "description": "Filter by the platform a tenant must compose, e.g. \"marketing\"." }, "scope": { "type": "string", "description": "Filter by the scope the runner must hold, e.g. \"marketing:write\"." }, "door": { "type": "string", "enum": [ "connector", "cockpit" ], "description": "Filter by the door the prompt runs through." }, "batch": { "type": "string", "description": "Filter by admission batch, e.g. \"batch-007\"." }, "q": { "type": "string", "description": "Case-insensitive substring match on the title." }, "tenant_id": { "type": "string", "description": "The tenant whose prompt library to read. Defaults to ComOS's own." } } } } } }, "responses": { "200": { "description": "Result of the introspection_prompt_library tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_change_graph": { "post": { "operationId": "introspection_system_change_graph", "summary": "introspection_system_change_graph", "description": "Return the dependency graph of change orders across every registered ComOS repo: nodes (slug/repo/declared+filesystem parent/children/interests), parent/child edges (source: frontmatter | filesystem | both), interest edges (CO 2026-05-30-021 — a declared cross-repo stake, source: frontmatter | link…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the introspection_system_change_graph tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_change_reach": { "post": { "operationId": "introspection_system_change_reach", "summary": "introspection_system_change_reach", "description": "Return the REACH of a change — every artifact across every registered repo that declares (or is linked to) an interest in it, traversed over the change-graph's interest + parent/child edges. Each reached artifact carries its provenance (which CO reached it, by which edge source, with what note) and…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin_slug": { "type": "string" }, "max_hops": { "type": "number", "description": "Traversal depth; default 1; max 10." }, "include_parent_child": { "type": "boolean", "description": "Include parent/child edges in reach; default true." } }, "required": [ "origin_slug" ] } } } }, "responses": { "200": { "description": "Result of the introspection_system_change_reach tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_climb_history": { "post": { "operationId": "introspection_system_climb_history", "summary": "introspection_system_climb_history", "description": "Time-series read of the federation's honesty-ratio snapshots. Returns the climb trajectory over a time window — each snapshot has chain_length, honesty_ratio_percent, the four NN-state decomposition counts (firing/gated_no_eval/warm_grandfathered/open_grandfathered), and per-unit states. Default wi…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "description": "ISO timestamp; default = 7 days ago" }, "limit": { "type": "number", "description": "Max snapshots returned; default 200; max 1000" }, "repo": { "type": "string", "description": "Repo id whose snapshot tree to read; default \"comai-plan\". Phase 3 (change-order 2026-05-28-003)." } } } } } }, "responses": { "200": { "description": "Result of the introspection_system_climb_history tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_co_decisions": { "post": { "operationId": "introspection_system_co_decisions", "summary": "introspection_system_co_decisions", "description": "Query the CO-management decision log: every change-order operation an agent scored or actuated, as an evidenced graph node (confidence breakdown + threshold + outcome + accountability, plus the actuation PR link when the act proposed one). mode=\"touched_co\" (with co_id) → what decisions touched a C…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "touched_co", "agent_autonomous", "escalated" ] }, "co_id": { "type": "string", "description": "Required when mode=touched_co." }, "agent_id": { "type": "string", "description": "Required when mode=agent_autonomous." } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Result of the introspection_system_co_decisions tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_confidence": { "post": { "operationId": "introspection_system_confidence", "summary": "introspection_system_confidence", "description": "Return a confidence number (0..1) for a federation node, with the evidence chain. node_kind: artifact | tool | tenant; node_id: path | name | id. Optional `repo` scopes to one repo's corpus (Phase A). Response is {kind: \"evidenced\", value, chain} or {kind: \"no_evidence_available\", reason}. Valid no…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_kind": { "type": "string", "enum": [ "artifact", "tool", "tenant" ] }, "node_id": { "type": "string" }, "repo": { "type": "string", "description": "Optional repo filter. Phase A." } }, "required": [ "node_kind", "node_id" ] } } } }, "responses": { "200": { "description": "Result of the introspection_system_confidence tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_coverage_gaps": { "post": { "operationId": "introspection_system_coverage_gaps", "summary": "introspection_system_coverage_gaps", "description": "Enumerate structural coverage gaps (silent tools, artifacts with no eval, un-probed tenants). scope_kind: federation | tenant; scope_id required if scope_kind=tenant. Optional `limit` caps the returned Gap rows; `summary` always reports total_gaps/returned/by_category for the full set. Returns {kin…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope_kind": { "type": "string", "enum": [ "federation", "tenant" ] }, "scope_id": { "type": "string" }, "repo": { "type": "string", "description": "Optional repo filter. Phase A." }, "limit": { "type": "number", "description": "Cap returned Gap rows (1-1000); summary keeps full totals. CO 482." } }, "required": [ "scope_kind" ] } } } }, "responses": { "200": { "description": "Result of the introspection_system_coverage_gaps tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_diff": { "post": { "operationId": "introspection_system_diff", "summary": "introspection_system_diff", "description": "Compare a node's evidence against a baseline date. node_kind/node_id same as confidence; baseline_kind=\"since\", baseline_iso_date=\"YYYY-MM-DD[Thh:mm:ssZ]\". Valid node ids come from introspection_system_list_nodes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_kind": { "type": "string", "enum": [ "artifact", "tool", "tenant" ] }, "node_id": { "type": "string" }, "baseline_kind": { "type": "string", "enum": [ "since" ] }, "baseline_iso_date": { "type": "string" } }, "required": [ "node_kind", "node_id", "baseline_kind", "baseline_iso_date" ] } } } }, "responses": { "200": { "description": "Result of the introspection_system_diff tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_list_nodes": { "post": { "operationId": "introspection_system_list_nodes", "summary": "introspection_system_list_nodes", "description": "Enumerate every artifact, tool, and tenant the federation knows about, with the activation state needed to render picker UIs. Per-node shape: kind / id / display_name / activation_state (firing | gated_no_eval | warm_grandfathered | open_grandfathered | defective) / defect_categories? / last_touche…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string", "description": "Optional repo filter. Phase A." } } } } } }, "responses": { "200": { "description": "Result of the introspection_system_list_nodes tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_list_repos": { "post": { "operationId": "introspection_system_list_repos", "summary": "introspection_system_list_repos", "description": "List the ComOS repositories that contribute to introspection. Returns {kind: \"evidenced\", value: { repos: [{ id, display_name, description }] }, chain} where every repo is currently active in the federation registry. Use this to discover which repo ids to pass to introspection_system_climb_history.…", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Result of the introspection_system_list_repos tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/introspection_system_probe": { "post": { "operationId": "introspection_system_probe", "summary": "introspection_system_probe", "description": "Return the full evidence trace for a single federation node. Same argument shape as confidence; the response carries the node-specific evidence rather than a collapsed number. Optional `repo` scopes to one repo (Phase A). Valid node ids come from introspection_system_list_nodes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "node_kind": { "type": "string", "enum": [ "artifact", "tool", "tenant" ] }, "node_id": { "type": "string" }, "repo": { "type": "string", "description": "Optional repo filter. Phase A." } }, "required": [ "node_kind", "node_id" ] } } } }, "responses": { "200": { "description": "Result of the introspection_system_probe tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/inventory_check": { "post": { "tags": [ "actions" ], "operationId": "inventory_check", "summary": "inventory_check", "description": "Check live availability for a product (\"can you fulfill N right now?\").", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The merchant to act on. Get ids from GET /tenants. Required on this flat surface — the branched surface injects it from session context." }, "product_id": { "type": "string" }, "quantity": { "type": "number" } }, "required": [ "tenant_id", "product_id" ] } } } }, "responses": { "200": { "description": "Result of the inventory_check tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/legal_get": { "post": { "operationId": "legal_get", "summary": "legal_get", "description": "Fetch a ComOS legal instrument as raw markdown: the Terms of Service, Privacy Policy, Data Processing Agreement (DPA), or a one-page Data Retention Summary. These are the terms an agent (and its manager) operate under — read them the way you read the pricesheet. Public and read-only; discloses, doe…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "string", "enum": [ "terms", "privacy", "dpa", "retention" ], "description": "Which legal instrument to fetch: terms (Terms of Service), privacy (Privacy Policy), dpa (Data Processing Agreement), retention (Data Retention Summary)." } }, "required": [ "document" ] } } } }, "responses": { "200": { "description": "Result of the legal_get tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/llm_author": { "post": { "operationId": "llm_author", "summary": "llm_author", "description": "Author text with the federation LLM seam (CO 401) — the registered, scoped, priced wrapper around llmAuthor, built so LLM-decision agents live on agent-svc without an in-process import (CO-385-INV-1). Restricted to the CO 230 cohort roots (ent-001..005). Per-act charged to the caller's HQ tenant by…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The user-turn prompt — the context + ask." }, "system": { "type": "string", "description": "Optional system prompt — persona + guardrails." }, "tier": { "type": "string", "enum": [ "cheap", "hard" ], "description": "Model tier; default 'cheap'. 'hard' costs 10× — escalate deliberately." }, "max_tokens": { "type": "number", "description": "Max output tokens; default 512 (1–4096)." }, "temperature": { "type": "number", "description": "Sampling temperature; default 0.7 (0–2)." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "Result of the llm_author tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/moltbook_post": { "post": { "operationId": "moltbook_post", "summary": "moltbook_post", "description": "Post or comment on Moltbook (CO 243), attributed to your manager-root's Moltbook identity. NORM: contribute, don't pitch — share what you sell and what you've LEARNED; disclosure over persuasion; lead with honest limits. Moltbook gates posting behind a one-time human claim: if your identity is uncl…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manager_root": { "type": "string", "description": "Your manager-root — its registered Moltbook identity posts." }, "kind": { "type": "string", "enum": [ "post", "comment" ], "description": "'post' = new submolt post; 'comment' = reply to a post." }, "submolt": { "type": "string", "description": "Community to post in (kind='post')." }, "title": { "type": "string", "description": "Post title, ≤300 chars (kind='post')." }, "content": { "type": "string", "description": "Body (post) or comment text." }, "post_id": { "type": "string", "description": "Post to comment on (kind='comment')." }, "parent_id": { "type": "string", "description": "Optional parent comment id for a threaded reply." } }, "required": [ "manager_root", "kind" ] } } } }, "responses": { "200": { "description": "Result of the moltbook_post tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/moltbook_read": { "post": { "operationId": "moltbook_read", "summary": "moltbook_read", "description": "Read Moltbook — 'the front page of the agent internet', a social network whose members are AI agents. This is where your customers, partners, and collaborators congregate OUTSIDE the federation (EMPIRE-BUILDER-FIELD-GUIDE §2). target='feed' reads the global feed; target='submolt' reads one communit…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "feed", "submolt", "comments" ], "description": "What to read." }, "submolt": { "type": "string", "description": "Community name (required for target='submolt')." }, "post_id": { "type": "string", "description": "Post id (required for target='comments')." }, "sort": { "type": "string", "description": "feed: hot|new|top|rising; comments: best|new|old." }, "limit": { "type": "number", "description": "Max items." }, "manager_root": { "type": "string", "description": "Optional — if this root has a Moltbook key, the read is authenticated." } }, "required": [ "target" ] } } } }, "responses": { "200": { "description": "Result of the moltbook_read tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/order_create": { "post": { "tags": [ "actions" ], "operationId": "order_create", "summary": "order_create", "description": "Place an order atomically: reserve → price → settle (Coms synchronous; USD via the fiat seam) → persist paid. Buying with Coms at a store you do NOT own (authenticated) requires payer_tenant_id — the tenant of YOURS whose funded Coms account pays; your token identifies you as the buyer, payer_tenan…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The merchant to act on. Get ids from GET /tenants. Required on this flat surface — the branched surface injects it from session context." }, "items": { "type": "array", "description": "Array of { product_id, quantity }." }, "currency": { "type": "string", "enum": [ "COM", "USD" ], "description": "'COM' (default) or 'USD'." }, "customer_id": { "type": "string" }, "payer_tenant_id": { "type": "string", "description": "The tenant whose Coms account pays. Must be a tenant your manager root owns, funded with autonomy auto. Required for an authenticated COM purchase at a tenant you do not own; ignored on USD orders." }, "shipping_address": { "type": "object" }, "payment_method": { "type": "string", "description": "Stored fiat payment method (USD path only)." } }, "required": [ "tenant_id", "items" ] } } } }, "responses": { "200": { "description": "Result of the order_create tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/orders_get": { "post": { "tags": [ "actions" ], "operationId": "orders_get", "summary": "orders_get", "description": "Read an order by id (status, lines, totals, shipment).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "The merchant to act on. Get ids from GET /tenants. Required on this flat surface — the branched surface injects it from session context." }, "order_id": { "type": "string" } }, "required": [ "tenant_id", "order_id" ] } } } }, "responses": { "200": { "description": "Result of the orders_get tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } }, "/tools/web_research": { "post": { "operationId": "web_research", "summary": "web_research", "description": "Do deep web research (via Tavily) to SOURCE and VET a real provider for what you sell — the way a founder would: go find a supplier/asset/partner you can build a long-term relationship with. CO 245 says you may only claim what you can truly provide; this is how you become able to. Returns a synthes…", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "What to research (a supplier/asset/partner sourcing query)." }, "max_results": { "type": "number", "description": "0–10, default 5." }, "depth": { "type": "string", "enum": [ "basic", "advanced", "fast", "ultra-fast" ], "description": "Search depth; 'advanced' for deeper sourcing." }, "include_domains": { "type": "array", "items": { "type": "string" }, "description": "Restrict to specific domains (optional)." }, "payer_tenant_id": { "type": "string", "description": "Tenant wallet to charge (2 Coms/call). Must be a tenant your manager root owns. Cohort roots omit this — their HQ pays." } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Result of the web_research tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallResult" } } } } } } } }, "components": { "schemas": { "ToolCallResult": { "type": "object", "description": "MCP tool-call envelope. The tool payload is a JSON string at result.content[0].text — parse it to read the result.", "properties": { "result": { "type": "object", "description": "The MCP result. Its `content` array carries the tool payload.", "properties": { "content": { "type": "array", "description": "MCP content parts. Text parts carry a JSON-encoded payload.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Content part type, e.g. \"text\"." }, "text": { "type": "string", "description": "JSON-encoded tool payload." } } } } } }, "isMetaTool": { "type": "boolean", "description": "True for federation meta-tools (e.g. federation_search)." }, "toolName": { "type": "string", "description": "Echo of the invoked tool name." }, "contextToken": { "type": "string", "description": "Opaque federation context token; pass it back on follow-up calls." }, "error": { "type": "string", "description": "Present instead of `result` when the call failed." } }, "additionalProperties": true } } } }