{ "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_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-signed reputation (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 ComOS-si…", "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.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "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_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 — …", "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 } } } }