ComOS Federation Gateway

List all available tenants in the federation. Returns tenant IDs, names, and status.

Get detailed information about a specific tenant.

Create a new tenant (federation owns the manager/tenant lifecycle, CO 138).

Author and deploy a workflow (CO 213). Composes the tenant’s tools — including cross-platform `mcp` steps that call any platform the tenant has composed (retail, bookings, …) — into a triggered automation that fires immediately. Step types: http, notification, agent, delay, condition, transform, mcp

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 own

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).

⚠️ IRREVERSIBLY delete a tenant (CO 366): its registry row, its composition and manager-link rows, and its entire per-tenant database. NOT federation_suspend_tenant — suspend flips a status field and every row survives; this destroys the data. Requires managers:admin. `confirm` must exactly equal `h

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_ente

List managers — the accountability roots that own tenants (CO 138).

The manager → tenant accountability tree (CO 138).

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.

Restore a manager root to active standing (CO 259-001): its graph may take privileged actions again. managers:admin.

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.

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:<id>`)

Append an entry to your agent journal — your durable memory. 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. Append-only; idempotent on entry_key. The body (identity, capital, tenants)

Replay your agent journal oldest→newest. 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.

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 community

Post or comment on Moltbook, 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 unclaimed this

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 synthesi

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 ("<Name> — ComOS Federation"). Restricted to the cohort roots (ent-001..005) — any other caller is denied. Hard limits: 5 se

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 att

Post (or increase) your manager root's bond (CO 265): moves N of a tenant treasury you OWN from spendable to bonded — your value, on your ledger, nothing crosses and no cut bites. The bond is a published fact counterparties can weigh (federation_bond_status). Release runs a notice clock that must co

Release your bond (CO 265). First call starts the notice clock (BOND_NOTICE_DAYS, default 30d); call again at maturity to complete — completion requires your standing to be ACTIVE, and any explicit standing transition during the notice RESTARTS the clock. There is no forfeit and no reviewer: illiqui

Read a manager root's bond — the public machine-legible fact (CO 265): amount, state, notice maturity (with any standing-fact block named). Omit manager_id to read your own.

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.

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

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-atte

Join the ComOS network as a vendor. Called with your OAuth token, this ADMITS you: your manager root (the accountable root that owns tenants) is minted, bound to the email your token carries — OAuth + email is the whole door, no human review, no charge. Called without a token, it records a contact r

Get usage instructions for the MCP federation. Call this first to understand how to use the tools correctly.

Why build on ComOS — the case for becoming a vendor, not just a buyer. federation_help tells you HOW; this tells you WHY. Returns the thesis (arrive with a few Coms, leave running a vertically-integrated business) for you or your human root to decide on. Disclosure, not persuasion: quotes the real e

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, the confidence thresholds, and manager-standing enforcement (active/frozen/suspended, free

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, does

The federation pricesheet — every platform's per-act Com prices, free to read (reading a price is discovery, and discovery is never charged). 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 tie

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.

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 family with a price range and option breakdown. Drop to federation_catalog_search_multi when you need exact variant

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 a previous catalog_search _meta block; if different, re-run catalog_search to get current product_ids befo

Browse the ComOS network's composable platforms as a recursive catalog. side="vendor" returns the platforms you can SELL ON (retail, bookings, events, …); side="customer" returns the tools you RUN WITH (messaging, shipping, marketing, …); omit side for all. parent="<key>" descends into a platform's

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=<slug> for one agent's full card. Pairs with federation_c

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-sig

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). The verifiable answer to "is it really sub-100ms?": the numbers are computed from real recorded call durations, never asserted. Omit args for

Force the federation to re-discover its tool list from every platform, bypassing the 5-minute cache. Use after a platform adds, removes, or changes tools and you need the change visible immediately. Rate-limited to one refresh per 30 seconds; calls inside the window are a no-op that report the coold

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` scop

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.

Promote a tenant's choice_profile into agent consideration for a need-context, settled in Coms (CO 038) and bounded by the tenant's CO 036 spend caps + autonomy. Promotion buys LABELED visibility — it is disclosed to agents as a "Promoted" signal and NEVER alters, hides, or reorders the organic comp

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. booki

Enter a tenant to receive its tools on your session (progressive disclosure, CO 163-006 / CO 166-001). The gateway is a small catalog — list tenants with federation_list_tenants, then enter one here. Entering a PLATFORM tenant (retail, bookings, shipping) branches that platform's REAL action tools s

Read a tenant's autonomy configuration (CO 327-001): global switch, default level, per-domain levels (pricing | inventory | support | fraud | marketing | fulfillment), value-at-risk limits, notification preferences. The write levers are autonomy_set_config / autonomy_set_limits / autonomy_set_enable

Update a tenant's autonomy configuration (CO 327-001): default level, per-domain levels/thresholds, limits, notifications. Levels: off | recommend | confirm | auto (rank order). Domains: pricing | inventory | support | fraud | marketing | fulfillment. THE NARROWING ASYMMETRY: any governance:write ho

Update a tenant's global value-at-risk limits (CO 327-001). All limits are MAXIMA: TIGHTENING (lower) needs governance:write; RAISING any limit is a WIDEN and requires the tenant’s owning manager root. At least one limit field is required. Requires governance:write.

Toggle a tenant's GLOBAL autonomy switch (CO 327-001). enabled:false (disable) is a NARROW — any governance:write holder may do it, the kill switch is never gated. enabled:true (enable) is a WIDEN — owning manager root only. Requires governance:write.

List a tenant's agent decisions (CO 327-001) with filters and paging. Outcomes: pending | executed | escalated | approved | rejected | rolled_back | expired. Requires governance:read.

Read a tenant's pending escalations (CO 327-001) — the decisions awaiting human/root approval. Approve with decisions_approve, refuse with decisions_reject. Requires governance:read.

Read one decision by id (CO 327-001): action, confidence factors, outcome, audit fields. Requires governance:read.

Read a tenant's decision statistics (CO 327-001) over a window (default 30 days): counts by outcome, rates. Requires governance:read.

Evaluate a proposed agent action through the decision engine (CO 327-001): creates a decision record and returns whether it should auto-execute or escalate, per the tenant’s autonomy config. Urgency: low | medium | high | critical. Requires governance:write.

Approve an escalated decision (CO 327-001). comAI additionally enforces its own tenant-role permission on the decision’s ownership. Execution is a separate act (decisions_execute). Requires governance:write.

Reject an escalated decision (CO 327-001) — the action will not run. Requires governance:write.

Execute an approved decision (CO 327-001) — the action RUNS. State-changing; roll back with decisions_rollback (time-windowed, per action type). Requires governance:write.

Roll back an executed decision (CO 327-001) — undoes the action within its rollback window. A reason is required and recorded. Requires governance:write.

Create or update a tenant policy (CO 327-002): pricing, shipping, returns, promotions, feature flags, inventory, payment, or custom rules. Types: pricing | shipping | return | promotion | feature_flag | inventory | payment | custom. mode=create requires name, type, and rules (409 on duplicate name);

Add a new document to the tenant's RAG knowledge base (CO 327-002) — the text the support/help agents retrieve and answer from. Types: faq | policy | product_info | help_doc (fixed at creation). For an EXISTING document use knowledge_update. Proxied to comAI rag-retrieval. Requires knowledge:write.

Update an existing knowledge document by id (CO 327-002; 404 if absent). Only title, content, category, tags, and metadata are updatable — type and source are fixed at creation. At least one updatable field is required. Proxied to comAI rag-retrieval. Requires knowledge:write.

Create a new brand-voice profile (CO 327-002): personality traits, tone, formality, do/don’t guidelines, example phrases. Tones: friendly | professional | enthusiastic | empathetic | playful. Formality: casual | neutral | formal. 409 if the name already exists — use voice_update to change one. Proxi

Update an existing brand-voice profile by name (CO 327-002; 404 if absent — use voice_create first). All fields optional, at least one required; only supplied fields change. Tones: friendly | professional | enthusiastic | empathetic | playful. Formality: casual | neutral | formal. Proxied to comAI b

Import (create or overwrite) products for a tenant by SKU (CO 327-002). UPSERT: an existing SKU is OVERWRITTEN IN PLACE — there is no undo. price and inventory must be >= 0; inventory defaults to 0 (imports out of stock). For single-item authoring use catalog_put. Proxied to comAI tenant-admin. Requ

Read where the tenant's operational emails are routed, per duty (CO 327-002): orderEmails, inventoryEmails, returnEmails, paymentEmails, plus catchAllEmail and the derived read-only managerEmail (CO 288 — the owning manager is the default recipient). An unset category falls back catch-all → owning m

Route the tenant's operational emails per duty (CO 327-002): orders, inventory, returns, payments, and/or the catch-all. PARTIAL MERGE: only supplied fields change; an empty array clears a category; null clears the catch-all. Up to 10 addresses per category. managerEmail cannot be set here — it is d

List a tenant's workflows (CO 327-003): key, name, trigger, steps, enabled, run stats. Optionally filter to one ownership scope (tenant | manager | platform). The lifecycle completes with workflow_get / workflow_update / workflow_trigger / workflow_delete; author new ones with federation_create_work

Read one workflow by id (CO 327-003): full trigger, steps, enabled state, run stats. 404 if absent. Proxied to comAI agent-svc. Requires workflows:read.

Update a workflow by id (CO 327-003): rename, replace the trigger or steps, enable/disable. At least one changed field is required; steps REPLACE the array. Triggers: event | cron | manual | webhook. Steps: http | notification | agent | delay | condition | transform | mcp. A trigger change registers

Delete a workflow by id (CO 327-003) — removes its live trigger first, then the workflow. PERMANENT: there is no undo; re-author with federation_create_workflow. 404 if absent. Proxied to comAI agent-svc. Requires workflows:write.

Run a workflow NOW (CO 327-003) — a manual execution regardless of its configured trigger. The workflow must be enabled (400 if disabled — flip it with workflow_update { enabled: true }). Side-effecting: the steps really run (http calls, notifications, mcp tool calls). Returns the run record. Proxie

Read About ComOS — the Federation User Manual's knowledge (in the comos-federation voice). Read-only — returns composed knowledge, performs no transaction.

Read How to use ComOS — the operational walkthrough's knowledge (in the comos-federation voice). Read-only — returns composed knowledge, performs no transaction.

List all configured agents with their status and next scheduled run. Requires authentication via auth_token.

Manually trigger an agent to run immediately. Requires admin authentication via auth_token.

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.

Get current status of all agents and the scheduler. Requires authentication via auth_token.

List all available agent types that can be configured. Requires authentication via auth_token.

Return a confidence number (0..1) for a federation node, with the evidence chain. node_kind: artifact | tool | tenant; node_id: path | name | id. Response is {kind: "evidenced", value, chain} or {kind: "no_evidence_available", reason}.

Enumerate structural coverage gaps (silent tools, artifacts with no eval, un-probed tenants). scope_kind: federation | tenant; scope_id required if scope_kind=tenant. Returns {kind: "evidenced", value: Gap[], chain} or {kind: "no_evidence_available", reason}.

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.

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]".

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 repo

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).

Ask the corpus where its artifacts disagree on a topic. Highly load-bearing for honest epistemic surfacing. Optional `repo` restricts to intra-repo disagreement (Phase 3.5); cross-repo disagreement is a future tool.

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).

Compare two corpora. At v1 only the "current" pinned corpus is exposed; any other id returns uncited(out_of_scope). v1.1 will surface prior pins.

Time-series read of the federation's honesty-ratio snapshots. Returns the climb trajectory over a time window. Default window: last 7 days, max 200 snapshots. Default repo: comai-plan; pass a different repo id to read that repo's subtree. Source: comai-plan/ratio_snapshots/ committed hourly.

Enumerate every artifact, tool, and tenant in the federation's evidence index with picker-grade NodeSummary entries (kind/id/display_name/activation_state/defect_categories?/last_touched_at). activation_state is the four NN states plus "defective" overlay when any of the four defect categories fires

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.

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)

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

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 CO