comos-gateway-com Actions API

openapi: 3.2.0
info:
  title: ComOS Federation Gateway Actions API
  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
tags:
- name: Actions
paths:
  /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/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_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/inventory_check:
    post:
      tags:
      - Actions
      operationId: inventory_check
      summary: inventory_check
      description: Check live availability for a product ("can you fulfill N right now?"). Pass variant_id to ask about one variant (the product's variants come from catalog_get); without it the answer is the product-level stock an order line without a variant draws on.
      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
                  maxLength: 64
                quantity:
                  type: number
                variant_id:
                  type: string
                  description: CO 624-001 — one variant of the product (from catalog_get variants[].variant_id).
                  maxLength: 64
              required:
              - tenant_id
              - product_id
      responses:
        '200':
          description: Result of the inventory_check 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, variant_id? } — variant_id (from catalog_get variants[]) draws that variant's stock; the unit price is the product price.
                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
                pickup_warehouse_id:
                  type: string
                  description: 'Collect at this store instead of shipping: a location id from location_search (an active, in-person warehouse). Every line''s stock is taken from that store''s shelf; not with shipping_address. The order records pickup { warehouse_id, name, address, timezone } and the tag pickup. Refused pickup_unavailable:<id> for anything else, insufficient_inventory:<product>@<id> when the store is short.'
                  maxLength: 63
                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'
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: Federation context token (carries no credential). Pass it back in the X-Context-Token header, with the same Authorization header, on follow-up calls.
        error:
          type: string
          description: Present instead of `result` when the call failed.
      additionalProperties: true