amfionhq-com Fleet API

openapi: 3.2.0
info:
  title: Amfion Partner Fleet API
  version: '2026-08-01'
  description: 'Machine-to-machine API for partners operating fleets of Amfion tenants: provisioning, atomic versioned catalog sync, trust/verification states, pause/resume, evals, conversation traces, webhooks, custom tools, usage, and fleet directory search with idempotent lead routing.'
  contact:
    url: https://amfionhq.com/docs
servers:
- url: https://api.amfionhq.com/v1/partner
security:
- partnerKey: []
tags:
- name: Fleet
paths:
  /fleet/tenants:
    get:
      summary: Light directory of active tenants with their machine surfaces (MCP endpoint…
      x-required-scope: tenants:read
      responses:
        '200':
          description: Fleet tenants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tenants:
                    type: array
                    items:
                      $ref: '#/components/schemas/FleetTenant'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Fleet
      operationId: getFleetTenants
      x-operation-id-source: derived
  /fleet/services:
    get:
      summary: Trust-ranked directory search across the fleet (policy-hidden services are…
      x-required-scope: tenants:read
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Free text; deterministic token scoring — relevance only
        never facts.: null
      - name: instantOnly
        in: query
        schema:
          type: boolean
      - name: maxPriceCents
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 50
          default: 20
      responses:
        '200':
          description: 'Ranked results: score desc, trust desc, price asc, name asc.'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Fleet
      operationId: getFleetServices
      x-operation-id-source: derived
  /fleet/route-lead:
    post:
      summary: Deliver a lead to the right fleet tenant (explicit tenantId or serviceQuery…
      description: Rides the exact capture_lead command chat and the MCP gateway use — validation, per-email daily caps, owner notification, customer upsert, and the lead.created webhook apply identically. The routed target is pinned on the command record, so a retried auto-routed delivery lands on the tenant the original execution chose.
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteLeadRequest'
      responses:
        '201':
          description: Lead delivered (or replayed for a completed key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteLeadResponse'
        '400':
          description: Missing Idempotency-Key
          invalid body: null
          or no service match.: null
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: IDEMPOTENCY_CONFLICT (same key
          different body) or IDEMPOTENCY_IN_PROGRESS.: null
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: IDEMPOTENCY_UNAVAILABLE — retry with the SAME key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Fleet
      operationId: postFleetRouteLead
      x-operation-id-source: derived
components:
  responses:
    Error:
      description: Structured error with request id.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    RouteLeadResponse:
      type: object
      properties:
        leadId:
          type: string
        tenantId:
          type: string
          format: uuid
        tenantSlug:
          type: string
        service:
          type: object
        routedBy:
          type: string
          enum:
          - explicit
          - auto
        match:
          type: object
          description: Present when auto-routed.
    FleetTenant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        businessName:
          type: string
        timezone:
          type: string
        servicesVisible:
          type: integer
        answerPolicyEnforced:
          type: boolean
        agentGatewayEnabled:
          type: boolean
        mcpEndpoint:
          type: string
          format: uri
        bookingPage:
          type: string
          format: uri
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - requestId
          properties:
            code:
              type: string
              example: CATALOG_VERSION_CONFLICT
            message:
              type: string
            details:
              type: object
            requestId:
              type: string
              example: req_abc123
    RouteLeadRequest:
      type: object
      description: A lead needs customerEmail or customerPhone (at least one; a phone needs at least 7 digits).
      required:
      - customerName
      - preferredTimes
      properties:
        customerName:
          type: string
        customerEmail:
          type: string
          format: email
          description: Required unless customerPhone is given.
        customerPhone:
          type: string
          description: Required unless customerEmail is given.
        preferredTimes:
          type: string
        notes:
          type: string
        tenantId:
          type: string
          format: uuid
          description: Explicit routing target. Mutually exclusive with serviceQuery.
        serviceId:
          type: string
          description: Optional with tenantId; must be policy-visible.
        serviceQuery:
          type: string
          description: Auto-routing — fleet search picks the top match; 400 when nothing matches.
  parameters:
    idempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        maxLength: 200
      description: 'Reserved BEFORE execution. Completed → stored response replays; same key + different body → 409 IDEMPOTENCY_CONFLICT; winner still executing → 409 IDEMPOTENCY_IN_PROGRESS; replay store unavailable → 503 IDEMPOTENCY_UNAVAILABLE (retry with the SAME key). A completed key is remembered for 180 days; after that the same key runs again.

        '
  securitySchemes:
    partnerKey:
      type: http
      scheme: bearer
      bearerFormat: amf_<48 hex chars>
      description: 'Partner API key. Keys carry scopes; each operation lists its required scope in `x-required-scope`. Suspending a partner blocks all its keys immediately.

        '