amfionhq-com

amfionhq-com Tenants API

The Tenants API from amfionhq-com — 30 operation(s) for tenants.

Documentation GitHub OpenAPI

Operations 36

POST /tenants Provision a partner tenant (idempotent via externalTenantId + Idempotency-Key) #

GET /tenants List this partner's tenants #

GET /tenants/{id} Full tenant detail: lifecycle, live catalog version/checksum, profile… #

POST /tenants/{id}/terms-acceptance Attest the business representative's acceptance of the Terms for Amfion… #

POST /tenants/{id}/pause Pause public chat (fail closed); catalog untouched #

POST /tenants/{id}/resume Restore public chat exactly as configured #

PATCH /tenants/{id}/profile Update business info (name, contact, address, hours, requirePhone) #

PUT /tenants/{id}/services Replace partner-synced services (convenience; prefer atomic catalog) #

PUT /tenants/{id}/faqs Replace partner-synced FAQs (convenience; prefer atomic catalog) #

PUT /tenants/{id}/policies Upsert policy text #

PUT /tenants/{id}/agent-config Set vertical / persona / custom instructions / answer policy / provider state #

POST /tenants/{id}/catalog/validate Dry-run catalog compile: schema errors (JSON pointers), duplicate ids, trust… #

PUT /tenants/{id}/catalog ATOMIC replace of services + FAQs + knowledge items + policies + agent config… #

GET /tenants/{id}/catalog Knowledge inventory readback: every item with trust state, compiled answer… #

GET /tenants/{id}/catalog/versions Applied catalog version history (checksums, counts) #

POST /tenants/{id}/catalog/versions/{v}/restore Re-apply a stored version verbatim (becomes a new version) #

POST /tenants/{id}/evals Start an eval run against the live catalog/policy (async, temperature 0… #

GET /tenants/{id}/evals/{runId} Eval status + per-case structured results (envelope assertions) #

GET /tenants/{id}/sessions Recent chat sessions (trace discovery) #

GET /tenants/{id}/sessions/{sessionId}/trace Redacted conversation trace: messages, tool calls, per-answer envelopes… #

GET /tenants/{id}/webhooks List webhook endpoints #

POST /tenants/{id}/webhooks Create endpoint (signing secret returned ONCE) #

PATCH /tenants/{id}/webhooks/{webhookId} Update url/events/active (reactivation resets failure count) #

DELETE /tenants/{id}/webhooks/{webhookId} Delete endpoint #

GET /tenants/{id}/webhooks/{webhookId}/deliveries Last 50 deliveries (status, attempts, errors) #

POST /tenants/{id}/webhooks/{webhookId}/deliveries/{deliveryId}/redrive Re-enqueue a failed/stuck delivery (safe — delivered rows are skipped) #

POST /tenants/{id}/webhooks/{webhookId}/rotate-secret New signing secret (returned ONCE); old secret co-signs for a 24h grace window #

POST /tenants/{id}/webhooks/{webhookId}/test Synchronous signed test.ping fixture delivery #

GET /tenants/{id}/knowledge-gaps Questions the agent could not answer (deduped, most-asked first; ?status=… #

PATCH /tenants/{id}/knowledge-gaps/{gapId} Triage a gap (open / addressed / dismissed) #

POST /tenants/{id}/reports Generate (or regenerate) a value report for a period #

GET /tenants/{id}/reports List reports (metrics, no HTML) #

GET /tenants/{id}/reports/{reportId} Full report incl. rendered HTML #

GET /tenants/{id}/tools Tool enablements for a tenant #

PUT /tenants/{id}/tools Replace a tenant's enablement set (with per-tenant config) #

GET /tenants/{id}/usage Monthly usage: conversations, allowance, tokens, daily breakdown #

Specifications

⚙

OpenAPI

https://artifacts.apis.io/amfionhq-com/openapi/amfionhq-com-tenants-api-openapi.yml

Schemas & Data

📊

JSONSchema

https://artifacts.apis.io/amfionhq-com/json-schema/amfionhq-com-route-lead-request-schema.json

📊

JSONSchema

https://artifacts.apis.io/amfionhq-com/json-schema/amfionhq-com-fleet-tenant-schema.json

📊

JSONSchema

https://artifacts.apis.io/amfionhq-com/json-schema/amfionhq-com-route-lead-response-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/amfionhq-com:amfionhq-com-tenants-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Amfion Partner Tenants 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: Tenants
paths:
  /tenants:
    post:
      summary: Provision a partner tenant (idempotent via externalTenantId + Idempotency-Key)
      description: Optional businessCountry (ISO 3166-1 alpha-2), internationalDataUse (no | yes | not_sure) and termsAcceptance (a partner attestation; see /tenants/{id}/terms-acceptance). Without an attestation the tenant is created pending_terms; a missing answer, a non-US country or yes / not_sure creates it pending_review. Only status active is live.
      x-required-scope: tenants:provision
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Tenant + embed snippet.
          content:
            application/json:
              schema:
                type: object
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenants
      x-operation-id-source: derived
    get:
      summary: List this partner's tenants
      x-required-scope: tenants:read
      responses:
        '200':
          description: Tenant list.
          content:
            application/json:
              schema:
                type: object
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenants
      x-operation-id-source: derived
  /tenants/{id}:
    get:
      summary: 'Full tenant detail: lifecycle, live catalog version/checksum, profile…'
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Tenant detail.
          content:
            application/json:
              schema:
                type: object
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsById
      x-operation-id-source: derived
  /tenants/{id}/terms-acceptance:
    post:
      summary: Attest the business representative's acceptance of the Terms for Amfion…
      description: Body - termsVersion (must equal the current Terms effective date), acceptedAt, representative {name, email, title?}, method (how the Terms were presented). A tenant waiting only on this becomes live; one with an open US-first scope review stays pending_review until an Amfion operator decides.
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The tenant status after the attestation ({ tenantId, status, live }).
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdTermsAcceptance
      x-operation-id-source: derived
  /tenants/{id}/pause:
    post:
      summary: Pause public chat (fail closed); catalog untouched
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Paused.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdPause
      x-operation-id-source: derived
  /tenants/{id}/resume:
    post:
      summary: Restore public chat exactly as configured
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Resumed.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdResume
      x-operation-id-source: derived
  /tenants/{id}/profile:
    patch:
      summary: Update business info (name, contact, address, hours, requirePhone)
      description: '`businessHours` is the OPENING hours: a day name maps to `{open, close, breaks?}` ("HH:MM") or null (closed). Each day closes after it opens (no overnight hours; "23:59" or "24:00" reach midnight); optional `breaks` (at most 2) sit inside the day without overlapping. A break is closed time (no booking slot in it; the phone line treats it as closed). Booking hours follow the opening hours until the business sets them separately.'
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                businessHours:
                  type: object
                  nullable: true
                  additionalProperties:
                    type: object
                    nullable: true
                    required:
                    - open
                    - close
                    properties:
                      open:
                        type: string
                        pattern: ^\d{2}:\d{2}$
                        example: 09:00
                      close:
                        type: string
                        pattern: ^\d{2}:\d{2}$
                        example: '17:00'
                      breaks:
                        type: array
                        maxItems: 2
                        items:
                          type: object
                          required:
                          - start
                          - end
                          properties:
                            start:
                              type: string
                              pattern: ^([01]\d|2[0-3]):[0-5]\d$
                              example: '12:00'
                            end:
                              type: string
                              pattern: ^([01]\d|2[0-3]):[0-5]\d$
                              example: '13:00'
      responses:
        '200':
          description: Updated profile.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: patchTenantsByIdProfile
      x-operation-id-source: derived
  /tenants/{id}/services:
    put:
      summary: Replace partner-synced services (convenience; prefer atomic catalog)
      description: 'Body `{ services: [...] }`; each item takes externalId, name, description, durationMinutes, priceCents, priceMaxCents, currency, active, sortOrder and the trust fields. `priceMaxCents` is the top of a typical price range ("typically $1,800 to $3,200"; needs priceCents, at least priceCents); the assistant quotes a range as the whole range, never as a firm price. An item without it states one price (a stored range is cleared). The atomic catalog refuses priceMaxCents (400).'
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Replaced.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: putTenantsByIdServices
      x-operation-id-source: derived
  /tenants/{id}/faqs:
    put:
      summary: Replace partner-synced FAQs (convenience; prefer atomic catalog)
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Replaced.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: putTenantsByIdFaqs
      x-operation-id-source: derived
  /tenants/{id}/policies:
    put:
      summary: Upsert policy text
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Upserted.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: putTenantsByIdPolicies
      x-operation-id-source: derived
  /tenants/{id}/agent-config:
    put:
      summary: Set vertical / persona / custom instructions / answer policy / provider state
      description: A settings object replaces your own settings keys. Reserved keys (complianceProfile, modelPolicy, voiceDelegation, voiceGreetingMode, messagingOpener, studioRequireGreenSuite, readinessReviewDismissedAt) keep their stored values; any you sent are listed in ignoredSettings.
      x-required-scope: agent:config
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated. Includes ignoredSettings when the payload carried reserved keys.
        '409':
          description: 'CONFLICT: the settings changed while the request was saving them. Nothing was written; retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: putTenantsByIdAgentConfig
      x-operation-id-source: derived
  /tenants/{id}/catalog/validate:
    post:
      summary: 'Dry-run catalog compile: schema errors (JSON pointers), duplicate ids, trust…'
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Validation report.
          content:
            application/json:
              schema:
                type: object
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdCatalogValidate
      x-operation-id-source: derived
  /tenants/{id}/catalog:
    put:
      summary: ATOMIC replace of services + FAQs + knowledge items + policies + agent config…
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Applied; new catalog version with sha256 checksum. Reserved agentConfig.settings keys keep their stored values and are listed in ignoredSettings.
        '409':
          description: CATALOG_VERSION_CONFLICT — live version moved past expectedVersion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: putTenantsByIdCatalog
      x-operation-id-source: derived
    get:
      summary: 'Knowledge inventory readback: every item with trust state, compiled answer…'
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Inventory.
          content:
            application/json:
              schema:
                type: object
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdCatalog
      x-operation-id-source: derived
  /tenants/{id}/catalog/versions:
    get:
      summary: Applied catalog version history (checksums, counts)
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Version list.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdCatalogVersions
      x-operation-id-source: derived
  /tenants/{id}/catalog/versions/{v}/restore:
    post:
      summary: Re-apply a stored version verbatim (becomes a new version)
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: v
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Restored as a new version.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdCatalogVersionsByVRestore
      x-operation-id-source: derived
  /tenants/{id}/evals:
    post:
      summary: Start an eval run against the live catalog/policy (async, temperature 0…
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '202':
          description: Run accepted.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdEvals
      x-operation-id-source: derived
  /tenants/{id}/evals/{runId}:
    get:
      summary: Eval status + per-case structured results (envelope assertions)
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run status/results.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdEvalsByRunId
      x-operation-id-source: derived
  /tenants/{id}/sessions:
    get:
      summary: Recent chat sessions (trace discovery)
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Session list.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdSessions
      x-operation-id-source: derived
  /tenants/{id}/sessions/{sessionId}/trace:
    get:
      summary: 'Redacted conversation trace: messages, tool calls, per-answer envelopes…'
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Trace.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdSessionsBySessionIdTrace
      x-operation-id-source: derived
  /tenants/{id}/webhooks:
    get:
      summary: List webhook endpoints
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Endpoints.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdWebhooks
      x-operation-id-source: derived
    post:
      summary: Create endpoint (signing secret returned ONCE)
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Created; secret returned once.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdWebhooks
      x-operation-id-source: derived
  /tenants/{id}/webhooks/{webhookId}:
    patch:
      summary: Update url/events/active (reactivation resets failure count)
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: patchTenantsByIdWebhooksByWebhookId
      x-operation-id-source: derived
    delete:
      summary: Delete endpoint
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deleted.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: deleteTenantsByIdWebhooksByWebhookId
      x-operation-id-source: derived
  /tenants/{id}/webhooks/{webhookId}/deliveries:
    get:
      summary: Last 50 deliveries (status, attempts, errors)
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deliveries.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdWebhooksByWebhookIdDeliveries
      x-operation-id-source: derived
  /tenants/{id}/webhooks/{webhookId}/deliveries/{deliveryId}/redrive:
    post:
      summary: Re-enqueue a failed/stuck delivery (safe — delivered rows are skipped)
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      - name: deliveryId
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Re-enqueued.
        '409':
          description: The delivery's payload copy was emptied after its retention period (30 days after creation
          90 when failed); it cannot be redriven.: null
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdWebhooksByWebhookIdDeliveriesByDeliveryIdRedrive
      x-operation-id-source: derived
  /tenants/{id}/webhooks/{webhookId}/rotate-secret:
    post:
      summary: New signing secret (returned ONCE); old secret co-signs for a 24h grace window
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Rotated; new secret returned once.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdWebhooksByWebhookIdRotateSecret
      x-operation-id-source: derived
  /tenants/{id}/webhooks/{webhookId}/test:
    post:
      summary: Synchronous signed test.ping fixture delivery
      x-required-scope: webhooks:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Delivery result.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdWebhooksByWebhookIdTest
      x-operation-id-source: derived
  /tenants/{id}/knowledge-gaps:
    get:
      summary: Questions the agent could not answer (deduped, most-asked first; ?status=…
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Gap list.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdKnowledgeGaps
      x-operation-id-source: derived
  /tenants/{id}/knowledge-gaps/{gapId}:
    patch:
      summary: Triage a gap (open / addressed / dismissed)
      x-required-scope: tenants:write
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: gapId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: patchTenantsByIdKnowledgeGapsByGapId
      x-operation-id-source: derived
  /tenants/{id}/reports:
    post:
      summary: Generate (or regenerate) a value report for a period
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Report generated.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: postTenantsByIdReports
      x-operation-id-source: derived
    get:
      summary: List reports (metrics, no HTML)
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Reports.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdReports
      x-operation-id-source: derived
  /tenants/{id}/reports/{reportId}:
    get:
      summary: Full report incl. rendered HTML
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: reportId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Report.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdReportsByReportId
      x-operation-id-source: derived
  /tenants/{id}/tools:
    get:
      summary: Tool enablements for a tenant
      x-required-scope: tools:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      responses:
        '200':
          description: Enablements.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdTools
      x-operation-id-source: derived
    put:
      summary: Replace a tenant's enablement set (with per-tenant config)
      x-required-scope: tools:manage
      parameters:
      - $ref: '#/components/parameters/tenantId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Replaced.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: putTenantsByIdTools
      x-operation-id-source: derived
  /tenants/{id}/usage:
    get:
      summary: 'Monthly usage: conversations, allowance, tokens, daily breakdown'
      x-required-scope: tenants:read
      parameters:
      - $ref: '#/components/parameters/tenantId'
      - name: month
        in: query
        schema:
          type: string
          example: 2026-08
      responses:
        '200':
          description: Usage.
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Tenants
      operationId: getTenantsByIdUsage
      x-operation-id-source: derived
components:
  parameters:
    tenantId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Tenant id (must belong to the calling partner).
  schemas:
    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
  responses:
    Error:
      description: Structured error with request id.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.

        '