{
  "openapi": "3.1.0",
  "info": {
    "title": "ToolCall Store API",
    "version": "0.2.0",
    "description": "Machine-readable API storefront for AI agents. Discover, quote, preview, approve, execute, and verify real-world actions: domain registration (via OpenProvider), DNS configuration, business email provisioning (Stalwart), LLM routing, and image/video generation. Always create a quote before any billable or irreversible action, send an Idempotency-Key header on mutating calls, and obtain a human approval token where required.",
    "contact": { "name": "ToolCall Store Support", "email": "support@toolcallstore.com", "url": "https://toolcallstore.com/docs/" },
    "license": { "name": "Proprietary", "url": "https://toolcallstore.com/legal/terms.html" }
  },
  "servers": [ { "url": "https://toolcallstore.com/v1", "description": "Production" } ],
  "security": [ { "bearerAuth": [] } ],
  "tags": [
    { "name": "discovery", "description": "List and search callable tools." },
    { "name": "commerce", "description": "Quotes, previews, approvals, execution, receipts." },
    { "name": "domains", "description": "Domain search and registration." },
    { "name": "dns", "description": "DNS template application and verification." },
    { "name": "email", "description": "Business email mailbox provisioning." },
    { "name": "llm", "description": "LLM routing across providers." },
    { "name": "media", "description": "Image and video generation." },
    { "name": "providers", "description": "Provider status and BYOK key management." }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key as a bearer token. Use tc_live_... in production or tc_test_... in sandbox. Scopes are enforced per tool." }
    },
    "parameters": {
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated UUID. Sending the same key for a mutating request returns the original result instead of creating a duplicate order. Strongly recommended on all POST calls that register, apply, create, or generate.", "schema": { "type": "string", "format": "uuid" } },
      "PageCursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor returned as next_cursor in a previous response.", "schema": { "type": "string" } },
      "PageLimit": { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return (1-100, default 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }
    },
    "headers": {
      "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Standard error envelope returned for all non-2xx responses.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "type"],
            "properties": {
              "code": { "type": "string", "description": "Stable machine-readable error code, e.g. invalid_request, unauthorized, insufficient_scope, payment_required, spend_cap_exceeded, approval_required, not_found, conflict, quote_expired, rate_limited, provider_error, internal_error." },
              "message": { "type": "string", "description": "Human-readable explanation." },
              "type": { "type": "string", "enum": ["invalid_request_error", "authentication_error", "authorization_error", "billing_error", "not_found_error", "conflict_error", "rate_limit_error", "provider_error", "api_error"] },
              "param": { "type": "string", "description": "The request field that caused the error, when applicable." },
              "details": { "type": "object", "additionalProperties": true, "description": "Optional structured context (e.g. required_scope, required_approval_for, cap_usd, expires_at)." },
              "request_id": { "type": "string", "description": "Echo of the request id for support and tracing." }
            }
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "next_cursor": { "type": "string", "nullable": true, "description": "Pass as ?cursor= to fetch the next page. Null when there are no more results." },
          "has_more": { "type": "boolean" }
        }
      },
      "Tool": {
        "type": "object",
        "properties": {
          "tool_id": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "description": { "type": "string" },
          "endpoint": { "type": "string" },
          "risk": { "type": "string", "enum": ["low", "medium", "high"] },
          "approval_required": { "type": "boolean" },
          "idempotent": { "type": "boolean" },
          "reversible": { "type": "boolean" },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "pricing_unit": { "type": "string" }
        }
      },
      "ToolSearchRequest": {
        "type": "object",
        "required": ["intent"],
        "properties": {
          "intent": { "type": "string", "description": "Natural-language description of what the agent wants to accomplish." },
          "categories": { "type": "array", "items": { "type": "string", "enum": ["domains", "dns", "email", "llm", "media", "safety", "verification"] }, "description": "Optional filter to restrict the search to specific categories." },
          "max_results": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
        }
      },
      "ToolSearchResponse": {
        "type": "object",
        "properties": {
          "results": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Tool" }, { "type": "object", "properties": { "relevance": { "type": "number", "description": "0-1 match score for the supplied intent." } } } ] } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "QuoteLineItem": {
        "type": "object",
        "required": ["type"],
        "properties": {
          "type": { "type": "string", "enum": ["domain", "dns_template", "mailbox", "llm", "image_generation", "video_generation", "approval", "receipt"] },
          "name": { "type": "string", "description": "Resource name, e.g. a domain such as example.com." },
          "quantity": { "type": "integer", "minimum": 1, "default": 1 },
          "years": { "type": "integer", "description": "Registration years for domain items." },
          "template": { "type": "string", "description": "DNS template id for dns_template items." },
          "params": { "type": "object", "additionalProperties": true, "description": "Item-specific parameters." }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/QuoteLineItem" } },
          "project_id": { "type": "string", "description": "Optional project to bill and scope the work to." },
          "currency": { "type": "string", "default": "USD" }
        }
      },
      "QuoteBreakdownItem": {
        "type": "object",
        "properties": {
          "type": { "type": "string" },
          "name": { "type": "string" },
          "quantity": { "type": "integer" },
          "unit": { "type": "string" },
          "provider_cost_usd": { "type": "number" },
          "fee_usd": { "type": "number" },
          "total_usd": { "type": "number" },
          "estimated": { "type": "boolean" }
        }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "quote_id": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "expires_at": { "type": "string", "format": "date-time", "description": "Re-quote if expired; an expired quote cannot be executed." },
          "currency": { "type": "string" },
          "total_estimate_usd": { "type": "number" },
          "requires_approval": { "type": "boolean", "description": "When true, an approval_id must be obtained before /execute." },
          "approval_reasons": { "type": "array", "items": { "type": "string" } },
          "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteBreakdownItem" } }
        }
      },
      "PreviewRequest": { "type": "object", "required": ["quote_id"], "properties": { "quote_id": { "type": "string" } } },
      "Preview": {
        "type": "object",
        "properties": {
          "preview_id": { "type": "string" },
          "quote_id": { "type": "string" },
          "summary": { "type": "string", "description": "Human-readable description of exactly what will happen." },
          "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" }, "ttl": { "type": "integer" } } } },
          "domains": { "type": "array", "items": { "type": "string" } },
          "mailboxes": { "type": "array", "items": { "type": "string" } },
          "warnings": { "type": "array", "items": { "type": "string" } }
        }
      },
      "DomainSearchRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "description": "A domain, keyword, or brand to search." },
          "tlds": { "type": "array", "items": { "type": "string" } },
          "include_premium": { "type": "boolean", "default": true },
          "max_results": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
        }
      },
      "DomainSearchResponse": {
        "type": "object",
        "properties": {
          "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "boolean" }, "premium": { "type": "boolean" }, "price_usd": { "type": "number" }, "renewal_usd": { "type": "number" }, "registrar": { "type": "string" } } } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "DomainRegisterRequest": {
        "type": "object",
        "required": ["domain", "approval_id"],
        "properties": {
          "domain": { "type": "string" },
          "years": { "type": "integer", "minimum": 1, "default": 1 },
          "approval_id": { "type": "string", "description": "Approval token from /approvals; required because registration is irreversible and billable." },
          "quote_id": { "type": "string" },
          "auto_renew": { "type": "boolean", "default": false },
          "whois_privacy": { "type": "boolean", "default": true },
          "contact": { "type": "object", "description": "Registrant contact. May default to the tenant's verified registrant on file.", "additionalProperties": true }
        }
      },
      "DnsTemplateApplyRequest": {
        "type": "object",
        "required": ["domain", "template", "approval_id"],
        "properties": {
          "domain": { "type": "string" },
          "template": { "type": "string", "description": "Template id, e.g. email_spf_dkim_dmarc, website_basic, app_endpoint, agent_endpoint." },
          "variables": { "type": "object", "additionalProperties": true },
          "approval_id": { "type": "string" },
          "replace_existing": { "type": "boolean", "default": false, "description": "When true, conflicting records are replaced; a rollback snapshot is always captured." }
        }
      },
      "MailboxCreateRequest": {
        "type": "object",
        "required": ["domain", "mailboxes", "approval_id"],
        "properties": {
          "domain": { "type": "string" },
          "mailboxes": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["address"], "properties": { "address": { "type": "string" }, "display_name": { "type": "string" }, "password": { "type": "string", "description": "Optional; generated and returned in the receipt if omitted." }, "aliases": { "type": "array", "items": { "type": "string" } } } } },
          "approval_id": { "type": "string" },
          "apply_dns": { "type": "boolean", "default": true, "description": "Apply MX/SPF/DKIM/DMARC records for deliverability." }
        }
      },
      "LlmChatRequest": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "messages": { "type": "array", "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["system", "user", "assistant", "tool"] }, "content": { "type": "string" } } } },
          "policy": { "type": "string", "enum": ["cheapest_safe", "premium_reasoning", "media_low_cost", "byok"], "default": "cheapest_safe" },
          "model": { "type": "string", "description": "Optional explicit model override." },
          "max_cost_usd": { "type": "number", "description": "Hard ceiling for this call; the router stays under it or returns a billing_error." },
          "max_tokens": { "type": "integer" },
          "temperature": { "type": "number" },
          "byok_key_id": { "type": "string", "description": "When policy=byok, the id of a stored provider key (see /providers/keys)." }
        }
      },
      "LlmChatResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "model": { "type": "string", "description": "The model actually used after routing." },
          "provider": { "type": "string" },
          "content": { "type": "string" },
          "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } },
          "cost_usd": { "type": "number" },
          "routed_by": { "type": "string" }
        }
      },
      "ImageGenerateRequest": {
        "type": "object",
        "required": ["prompt"],
        "properties": {
          "prompt": { "type": "string" },
          "count": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 },
          "size": { "type": "string" },
          "policy": { "type": "string", "default": "media_low_cost" },
          "provider": { "type": "string" },
          "max_cost_usd": { "type": "number" }
        }
      },
      "VideoGenerateRequest": {
        "type": "object",
        "required": ["prompt", "approval_id"],
        "properties": {
          "prompt": { "type": "string" },
          "duration_seconds": { "type": "number", "minimum": 1, "default": 5 },
          "resolution": { "type": "string" },
          "policy": { "type": "string", "default": "media_low_cost" },
          "provider": { "type": "string" },
          "approval_id": { "type": "string", "description": "Required: video generation can be expensive." },
          "max_cost_usd": { "type": "number" }
        }
      },
      "MediaJob": {
        "type": "object",
        "properties": {
          "job_id": { "type": "string" },
          "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed"] },
          "assets": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "type": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } },
          "cost_usd": { "type": "number" },
          "receipt_id": { "type": "string" }
        }
      },
      "ApprovalRequest": {
        "type": "object",
        "required": ["quote_id"],
        "properties": {
          "quote_id": { "type": "string" },
          "required_for": { "type": "string" },
          "note": { "type": "string", "description": "Context shown to the human approver." },
          "callback_url": { "type": "string", "format": "uri", "description": "Optional webhook to notify when the decision is made." }
        }
      },
      "Approval": {
        "type": "object",
        "properties": {
          "approval_id": { "type": "string" },
          "quote_id": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "granted", "denied", "expired"] },
          "requested_at": { "type": "string", "format": "date-time" },
          "decided_at": { "type": "string", "format": "date-time", "nullable": true },
          "expires_at": { "type": "string", "format": "date-time" },
          "approver": { "type": "string", "nullable": true }
        }
      },
      "ExecuteRequest": {
        "type": "object",
        "properties": {
          "quote_id": { "type": "string", "description": "Required for billable/irreversible actions." },
          "approval_id": { "type": "string", "description": "Required when the quote's requires_approval is true." }
        }
      },
      "ProofItem": {
        "type": "object",
        "properties": {
          "kind": { "type": "string", "description": "screenshot, dns_check, provider_id, timestamp, rollback_hint, etc." },
          "label": { "type": "string" },
          "value": { "type": "string" },
          "url": { "type": "string", "format": "uri", "nullable": true }
        }
      },
      "Receipt": {
        "type": "object",
        "properties": {
          "receipt_id": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "succeeded", "partial", "failed", "rolled_back"] },
          "quote_id": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "cost_usd": { "type": "number" },
          "provider_order_ids": { "type": "array", "items": { "type": "string" } },
          "rollback_available": { "type": "boolean" },
          "proof": { "type": "array", "items": { "$ref": "#/components/schemas/ProofItem" } }
        }
      },
      "VerifyRequest": {
        "type": "object",
        "required": ["receipt_id"],
        "properties": {
          "receipt_id": { "type": "string" },
          "checks": { "type": "array", "items": { "type": "string", "enum": ["dns_propagation", "domain_active", "mailbox_login", "asset_reachable", "spf", "dkim", "dmarc"] } }
        }
      },
      "Verification": {
        "type": "object",
        "properties": {
          "receipt_id": { "type": "string" },
          "verified": { "type": "boolean", "description": "True only when every requested check passed." },
          "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "passed": { "type": "boolean" }, "detail": { "type": "string" } } } },
          "checked_at": { "type": "string", "format": "date-time" }
        }
      },
      "ProviderStatus": {
        "type": "object",
        "properties": {
          "providers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string", "enum": ["operational", "degraded", "down"] }, "latency_ms": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } } }
        }
      },
      "ProviderKeyCreateRequest": {
        "type": "object",
        "required": ["provider", "key"],
        "properties": {
          "provider": { "type": "string" },
          "key": { "type": "string", "description": "The BYOK secret. Stored encrypted; never returned in plaintext." },
          "label": { "type": "string" }
        }
      },
      "ProviderKey": {
        "type": "object",
        "properties": {
          "key_id": { "type": "string" },
          "provider": { "type": "string" },
          "label": { "type": "string" },
          "last4": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "ProviderKeyList": {
        "type": "object",
        "properties": {
          "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderKey" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "description": "Event payload POSTed to a tenant's configured webhook URL. Signed with HMAC-SHA256 in the ToolCall-Signature header.",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "enum": ["quote.created", "approval.requested", "approval.granted", "approval.denied", "execution.completed", "execution.failed", "receipt.ready", "media.job.completed"] },
          "created_at": { "type": "string", "format": "date-time" },
          "data": { "type": "object", "additionalProperties": true }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "Invalid request (validation error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "PaymentRequired": { "description": "Spend cap exceeded, no usage credit, or no payment method on file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "API key lacks the required scope, or approval is required and missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Conflict": { "description": "Conflict, e.g. duplicate idempotency key in progress, or quote already executed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unprocessable": { "description": "Semantically invalid, e.g. expired quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Too many requests.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "ServerError": { "description": "Internal error or upstream provider failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/tools/list": {
      "get": {
        "tags": ["discovery"], "summary": "List all callable tools", "operationId": "listTools",
        "description": "Returns the full tool catalog. Prefer this (or /tools/search) over scraping human pages.",
        "parameters": [ { "$ref": "#/components/parameters/PageCursor" }, { "$ref": "#/components/parameters/PageLimit" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": ["domains", "dns", "email", "llm", "media", "safety", "verification"] } } ],
        "responses": {
          "200": { "description": "Tool catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/tools/search": {
      "post": {
        "tags": ["discovery"], "summary": "Search callable tools by intent", "operationId": "searchTools",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSearchRequest" } } } },
        "responses": {
          "200": { "description": "Tool search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSearchResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/quotes": {
      "post": {
        "tags": ["commerce"], "summary": "Create a quote before execution", "operationId": "createQuote",
        "description": "Always call this before any billable or irreversible action. The returned quote indicates total_estimate_usd, requires_approval, and expires_at.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } },
        "responses": {
          "200": { "description": "Quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/previews": {
      "post": {
        "tags": ["commerce"], "summary": "Preview the exact changes a quote will make", "operationId": "createPreview",
        "description": "Returns proposed DNS records, domains, mailboxes, and warnings so a human or agent can review before approval and execution.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewRequest" } } } },
        "responses": {
          "200": { "description": "Preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/domains/search": {
      "post": {
        "tags": ["domains"], "summary": "Search domain availability", "operationId": "searchDomains",
        "description": "Availability and pricing via OpenProvider, including premium alternatives.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainSearchRequest" } } } },
        "responses": {
          "200": { "description": "Domain availability results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainSearchResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/domains/register": {
      "post": {
        "tags": ["domains"], "summary": "Register domain after approval", "operationId": "registerDomain",
        "description": "Irreversible and billable. Requires a granted approval_id. Send an Idempotency-Key to avoid duplicate registrations on retry.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainRegisterRequest" } } } },
        "responses": {
          "200": { "description": "Registration receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/dns/templates/apply": {
      "post": {
        "tags": ["dns"], "summary": "Apply a DNS template", "operationId": "applyDnsTemplate",
        "description": "Applies a named DNS template (email, website, app, agent endpoint). A rollback snapshot is captured. Requires approval and is best previewed first.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsTemplateApplyRequest" } } } },
        "responses": {
          "200": { "description": "DNS change receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/email/mailboxes": {
      "post": {
        "tags": ["email"], "summary": "Create business email mailboxes", "operationId": "createEmailMailboxes",
        "description": "Provisions Stalwart-hosted mailboxes and applies deliverability DNS (MX/SPF/DKIM/DMARC). Requires approval.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxCreateRequest" } } } },
        "responses": {
          "200": { "description": "Mailbox provisioning receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/llm/chat": {
      "post": {
        "tags": ["llm"], "summary": "Route an LLM chat/completion request", "operationId": "routeLlmChat",
        "description": "Routes to the best provider per the chosen policy and cost ceiling. Returns the model used, usage, and cost.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmChatRequest" } } } },
        "responses": {
          "200": { "description": "LLM response with provider metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmChatResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/media/images": {
      "post": {
        "tags": ["media"], "summary": "Generate or edit images", "operationId": "generateImages",
        "description": "Generates images via the selected media policy/provider. Returns a media job; assets may be delivered synchronously or via media.job.completed webhook.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerateRequest" } } } },
        "responses": {
          "200": { "description": "Image media job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaJob" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/media/videos": {
      "post": {
        "tags": ["media"], "summary": "Generate video", "operationId": "generateVideo",
        "description": "Generates short video. Requires approval because it can be expensive. Returns a media job tracked to a receipt.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerateRequest" } } } },
        "responses": {
          "200": { "description": "Video media job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaJob" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/approvals": {
      "post": {
        "tags": ["commerce"], "summary": "Submit an action for human approval", "operationId": "createApproval",
        "description": "Creates a pending approval for a quote. A human approves via email, SMS, or dashboard. Poll this approval or listen for approval.granted/denied webhooks, then pass the approval_id to /execute or the relevant action.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequest" } } } },
        "responses": {
          "200": { "description": "Approval request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/approvals/{approval_id}": {
      "get": {
        "tags": ["commerce"], "summary": "Get approval status", "operationId": "getApproval",
        "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": {
          "200": { "description": "Approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/execute": {
      "post": {
        "tags": ["commerce"], "summary": "Execute an approved action", "operationId": "executeApprovedAction",
        "description": "Executes the work described by a quote. Requires approval_id when the quote's requires_approval is true. Idempotent by Idempotency-Key.",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteRequest" } } } },
        "responses": {
          "200": { "description": "Execution receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/verify": {
      "post": {
        "tags": ["commerce"], "summary": "Verify the final state of an executed action", "operationId": "verifyReceipt",
        "description": "Runs post-execution checks (DNS propagation, domain active, mailbox login, asset reachable, SPF/DKIM/DMARC) and returns machine-readable proof.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } },
        "responses": {
          "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/receipts/{receipt_id}": {
      "get": {
        "tags": ["commerce"], "summary": "Fetch a proof receipt", "operationId": "getReceipt",
        "parameters": [ { "name": "receipt_id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": {
          "200": { "description": "Receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/receipts": {
      "get": {
        "tags": ["commerce"], "summary": "List receipts", "operationId": "listReceipts",
        "parameters": [ { "$ref": "#/components/parameters/PageCursor" }, { "$ref": "#/components/parameters/PageLimit" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ],
        "responses": {
          "200": { "description": "Receipts", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/Receipt" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/providers/status": {
      "get": {
        "tags": ["providers"], "summary": "Provider health and routing status", "operationId": "getProviderStatus",
        "responses": {
          "200": { "description": "Provider status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderStatus" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/providers/keys": {
      "get": {
        "tags": ["providers"], "summary": "List stored BYOK provider keys", "operationId": "listProviderKeys",
        "description": "Lists bring-your-own-key provider keys (metadata only; secrets are never returned).",
        "parameters": [ { "$ref": "#/components/parameters/PageCursor" }, { "$ref": "#/components/parameters/PageLimit" } ],
        "responses": {
          "200": { "description": "Provider keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderKeyList" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      },
      "post": {
        "tags": ["providers"], "summary": "Store a BYOK provider key", "operationId": "createProviderKey",
        "description": "Stores an encrypted provider key for BYOK routing. Requires the providers:keys scope.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderKeyCreateRequest" } } } },
        "responses": {
          "200": { "description": "Stored key metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderKey" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/providers/keys/{key_id}": {
      "delete": {
        "tags": ["providers"], "summary": "Delete a BYOK provider key", "operationId": "deleteProviderKey",
        "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": {
          "204": { "description": "Deleted" },
          "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    }
  }
}