openapi: 3.1.0
info:
  title: SuggestAPI Knowledge Gateway
  version: 1.0.0
  summary: SuggestAPI + OKF = Knowledge Gateway
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  description: |
    A tenant-aware agent surface for search, comparison, recommendations, and
    commerce handoff metadata across existing websites and ecommerce stores.

    The API is split into two layers:

    - `/oks/{tenant}/*` for plugin-style tenant knowledge access on existing sites
    - `/v1/agent/*` for search-adjacent orchestration on top of that retrieval layer

    Plugin search mode is the adoption path for existing shops that do not want
    to replatform. In that mode the gateway fronts the merchant's existing
    catalog and content while pointing agents to native commerce flows through
    safe handoff metadata, all within a stable,
    agent-friendly contract.
servers:
  - url: https://agent.suggestapi.com
    description: Public gateway
tags:
  - name: Discovery
    description: Gateway and extension discovery documents
  - name: Agent
    description: High-level task-oriented endpoints for agent workflows
  - name: ARD
    description: Agentic Resource Discovery catalog and registry endpoints
  - name: Tenant Surface
    description: Tenant-scoped knowledge surface endpoints
security:
  - ApiKeyAuth: []
  - {}
paths:
  /.well-known/okg.json:
    get:
      tags: [Discovery]
      summary: Gateway discovery document
      operationId: getGatewayDiscovery
      responses:
        "200":
          description: Knowledge Gateway discovery metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayDiscoveryResponse"
              examples:
                default:
                  value:
                    ok: true
                    data:
                      name: Knowledge Gateway
                      version: "1.0.0"
                      spec: "OKS/1.0"
                      provider: SuggestAPI
                      tagline: SuggestAPI + OKF = Knowledge Gateway
                      base_url: https://agent.suggestapi.com
                      endpoints:
                        agent_search: https://agent.suggestapi.com/v1/agent/search
                        agent_product: https://agent.suggestapi.com/v1/agent/product/{id}
                        agent_compare: https://agent.suggestapi.com/v1/agent/compare
                        agent_recommend: https://agent.suggestapi.com/v1/agent/recommend
                        tenant_surface: https://agent.suggestapi.com/oks/{tenant}
                        openapi: https://agent.suggestapi.com/openapi.yaml
                        llms: https://agent.suggestapi.com/llms.txt
                      well_known:
                        openapi: https://agent.suggestapi.com/.well-known/openapi.json
                        gateway: https://agent.suggestapi.com/.well-known/okg.json
                      tenant_identifier: domain
                      supported_types:
                        - product
                        - collection
                        - content
                        - policy
                        - service
                      capabilities:
                        search: true
                        plugin_search: true
                        compare: true
                        recommend: true
                        guided_checkout: false
                        mcp: false
                        ucp: false
                        openai_skills: false
                      extensions:
                        ucp:
                          supported: false
                          discovery_path: /.well-known/ucp
                        openai_skills:
                          supported: false
                          discovery_path: /.well-known/skills.json
                      auth:
                        modes:
                          - public
                          - x-api-key
                      authentication:
                        type: none
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/openapi.json:
    get:
      tags: [Discovery]
      summary: OpenAPI discovery document
      operationId: getOpenapiDiscovery
      responses:
        "200":
          description: Points to the canonical OpenAPI contract
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenapiDiscoveryResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/agent.json:
    get:
      tags: [Discovery]
      summary: Agent manifest
      operationId: getAgentDiscovery
      responses:
        "200":
          description: OKS-oriented agent manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentDiscoveryResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/ai-plugin.json:
    get:
      tags: [Discovery]
      summary: Legacy AI plugin manifest
      operationId: getAiPluginDiscovery
      responses:
        "200":
          description: OpenAI plugin compatibility manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AiPluginDiscovery"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/ai-catalog.json:
    get:
      tags: [Discovery, ARD]
      summary: ARD capability manifest
      operationId: getAiCatalogDiscovery
      responses:
        "200":
          description: Agentic Resource Discovery capability manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArdCatalogManifest"
        "404":
          $ref: "#/components/responses/NotFound"
  /catalogs/{tenant}/ai-catalog.json:
    get:
      tags: [Discovery, ARD, Tenant Surface]
      summary: SuggestAPI-hosted tenant ARD capability manifest
      operationId: getTenantAiCatalog
      description: |
        Compiles an ARD catalog from one tenant's configured capabilities and
        published content revision. The catalog is hosted and cryptographically
        identified by SuggestAPI; customers can reference it from their origin
        HTML with a `link[rel=alternate][type=application/ai-catalog+json]` tag.
      parameters:
        - $ref: "#/components/parameters/Tenant"
      responses:
        "200":
          description: Tenant-scoped ARD capability manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArdCatalogManifest"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/did.json:
    get:
      tags: [Discovery, ARD]
      summary: DID document for the ARD catalog publisher
      operationId: getDidDocument
      responses:
        "200":
          description: Configured DID document for did:web:agent.suggestapi.com
          content:
            application/did+json:
              schema:
                $ref: "#/components/schemas/DidDocument"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/ucp:
    get:
      tags: [Discovery]
      summary: UCP discovery document
      operationId: getUcpDiscovery
      responses:
        "200":
          description: Optional UCP capability document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UcpDiscoveryResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/mcp.json:
    get:
      tags: [Discovery]
      summary: MCP discovery document
      operationId: getMcpDiscovery
      responses:
        "200":
          description: Optional MCP capability document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/McpDiscoveryResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/mcp/server.json:
    get:
      tags: [Discovery]
      summary: MCP Registry server manifest
      operationId: getMcpServerManifest
      responses:
        "200":
          description: Configured official MCP Registry server manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/McpServerManifest"
        "404":
          $ref: "#/components/responses/NotFound"
  /.well-known/skills.json:
    get:
      tags: [Discovery]
      summary: OpenAI Skills discovery document
      operationId: getSkillsDiscovery
      responses:
        "200":
          description: Optional Skills capability document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillsDiscoveryResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /oks/{tenant}:
    get:
      tags: [Tenant Surface]
      summary: Describe a tenant knowledge surface
      description: |
        Returns the tenant's normalized gateway metadata, including the plugin
        search surface an assistant can use without requiring the merchant to
        replatform their storefront or checkout stack.
      operationId: getTenantSurface
      parameters:
        - $ref: "#/components/parameters/Tenant"
      responses:
        "200":
          description: Tenant surface metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantInfoResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /oks/{tenant}/search:
    get:
      tags: [Tenant Surface]
      summary: Search a tenant knowledge surface
      description: |
        Primary plugin search mode endpoint for assistants, connectors, and
        lightweight shopping plugins.

        This is the easiest entry point for existing ecommerce sites. It maps
        the gateway contract onto SuggestAPI retrieval primitives:

        - `mode=typeahead` maps to fast prefix retrieval similar to `GET /v1/typeahead`
        - `mode=autocomplete` maps to richer lexical retrieval similar to `GET /v1/autocomplete`
        - `mode=search` or `mode=hybrid` is the normalized full-result surface for plugins

        Use this endpoint when you want a stable, tenant-scoped search contract.
        Use `POST /v1/agent/search` when you want orchestration, query rewriting,
        answer generation, or multi-step reasoning on top of retrieval.
      operationId: searchTenantSurface
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 2000
        - name: type
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/KnowledgeObjectType"
        - name: mode
          in: query
          required: false
          schema:
            type: string
            enum: [typeahead, autocomplete, search, hybrid]
            default: search
          description: Retrieval mode for plugin-style search access.
        - name: vendor
          in: query
          required: false
          schema:
            type: string
        - name: price
          in: query
          required: false
          schema:
            type: string
          description: Inclusive price filter formatted as `min..max`.
        - name: availability
          in: query
          required: false
          schema:
            type: string
        - name: collection
          in: query
          required: false
          schema:
            type: string
        - name: product_type
          in: query
          required: false
          schema:
            type: string
        - name: tags
          in: query
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Tenant search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantSearchResponse"
        "404":
          $ref: "#/components/responses/NotFound"
    x-query:
      tags: [Tenant Surface]
      summary: Search a tenant knowledge surface with query content
      description: |
        HTTP `QUERY` is accepted only for search operations. Send the same
        search inputs as JSON request content when URL query parameters would
        be impractical. QUERY is a safe, idempotent method as defined by the
        IETF HTTP QUERY Method draft.
      operationId: queryTenantSurface
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TenantSearchRequest"
      responses:
        "200":
          description: Tenant search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TenantSearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /oks/{tenant}/products:
    get:
      tags: [Tenant Surface]
      summary: List tenant products
      description: |
        Product browse endpoint for plugin search mode. Use this when a plugin
        needs a normalized catalog list after discovery or search.
      operationId: listTenantProducts
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: q
          in: query
          required: false
          schema:
            type: string
        - name: collection
          in: query
          required: false
          schema:
            type: string
        - name: sort
          in: query
          required: false
          description: |
            Optional browse ordering. `popular` prefers tenant-curated
            `popular_product_ids` when configured and otherwise falls back to
            the tenant's default product order.
          schema:
            type: string
            enum: [popular]
      responses:
        "200":
          description: Tenant products
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductListResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /oks/{tenant}/products/{id}:
    get:
      tags: [Tenant Surface]
      summary: Fetch a canonical tenant product
      description: |
        Canonical product fetch used by plugin search mode and by higher-level
        agent workflows like compare, recommend, and guided checkout.
      operationId: getTenantProduct
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/ProductIdPath"
      responses:
        "200":
          description: Canonical product object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /oks/{tenant}/collections:
    get:
      tags: [Tenant Surface]
      summary: List tenant collections
      operationId: listTenantCollections
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Tenant collections
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionListResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /oks/{tenant}/content:
    get:
      tags: [Tenant Surface]
      summary: List tenant content items
      operationId: listTenantContent
      parameters:
        - $ref: "#/components/parameters/Tenant"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: q
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Tenant content items
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContentListResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /oks/{tenant}/policies:
    get:
      tags: [Tenant Surface]
      summary: List tenant policies
      operationId: listTenantPolicies
      parameters:
        - $ref: "#/components/parameters/Tenant"
      responses:
        "200":
          description: Tenant policy objects
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyListResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/agent/search:
    post:
      tags: [Agent]
      summary: Agent-oriented search across a tenant surface
      description: |
        Orchestration layer for search. This endpoint sits on top of plugin
        search mode and may compose retrieval, query rewriting, reranking,
        answer generation, policy lookups, and commerce-aware reasoning.

        Typical internal mapping:

        - retrieval via `GET /oks/{tenant}/search`
        - optional query rewrite and rerank
        - optional answer synthesis with citations

        For lightweight plugin integrations or storefront adapters, prefer
        `GET /oks/{tenant}/search`.
      operationId: agentSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentSearchRequest"
      responses:
        "200":
          description: Agent search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
    x-query:
      tags: [Agent]
      summary: Agent-oriented search with query content
      description: |
        HTTP `QUERY` is accepted only for search operations. It has the same
        request and response contract as POST search, but declares the
        operation safe and idempotent.
      operationId: queryAgentSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentSearchRequest"
      responses:
        "200":
          description: Agent search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/agent/product/{id}:
    get:
      tags: [Agent]
      summary: Fetch a single product for agent use
      description: |
        Agent-friendly product fetch. In most implementations this is a thin
        convenience wrapper over `GET /oks/{tenant}/products/{id}`.
      operationId: agentGetProduct
      parameters:
        - $ref: "#/components/parameters/ProductIdPath"
        - name: tenant
          in: query
          required: true
          schema:
            type: string
            description: Merchant domain or tenant key
      responses:
        "200":
          description: Product payload for agent use
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/agent/compare:
    post:
      tags: [Agent]
      summary: Compare a small set of tenant objects
      description: |
        Comparison workflow built on top of canonical tenant object fetches.
        This is intended for shopping assistants and plugin compare views that
        need structured differences, not just raw retrieval.
      operationId: agentCompare
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentCompareRequest"
      responses:
        "200":
          description: Structured comparison
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentCompareResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/agent/recommend:
    post:
      tags: [Agent]
      summary: Return best-fit recommendations for a query or task
      description: |
        Recommendation workflow on top of the normalized tenant surface.
        Implementations may map this to SuggestAPI recommendation families such
        as structural, series, application, specs, or connected recommendations.
      operationId: agentRecommend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentRecommendRequest"
      responses:
        "200":
          description: Agent recommendations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentRecommendResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/agent/cart:
    post:
      tags: [Agent]
      summary: Build a resource handoff to the merchant's existing cart flow
      description: |
        Platform-neutral cart handoff surface. Accepts tenant-scoped line
        items and returns links to the merchant's existing product, cart, and
        checkout resources when they are available.

        Implementations should use:

        - `native_adapter` when they can talk to the storefront's real cart
        - `handoff_only` when they only know cart or checkout URLs

        The gateway must not fabricate persisted cart state unless a real
        adapter created it.
      operationId: agentCart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentCartRequest"
      responses:
        "200":
          description: Cart handoff metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentCartResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/agent/checkout/guide:
    post:
      tags: [Agent]
      summary: Guided checkout handoff
      operationId: agentGuidedCheckout
      description: |
        Search-adjacent handoff endpoint for native merchant checkout flows.
        This returns a safe handoff plan and must not execute checkout
        directly.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GuidedCheckoutRequest"
      responses:
        "200":
          description: Guided checkout handoff plan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuidedCheckoutResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /ard/v1/search:
    post:
      tags: [ARD]
      summary: Search gateway-discoverable agentic resources
      operationId: ardSearch
      description: |
        ARD-compatible search endpoint for discovering this gateway's published
        search and handoff capabilities, including configured tenant catalogs.
        This is resource discovery, not tenant product search. Only local
        federation (`none`) is currently supported.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArdSearchRequest"
      responses:
        "200":
          description: Ranked ARD catalog entries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArdSearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
    x-query:
      tags: [ARD]
      summary: Search gateway-discoverable resources with query content
      description: |
        HTTP `QUERY` is accepted only for search operations. It has the same
        request and response contract as POST search, but declares the
        operation safe and idempotent.
      operationId: queryArdSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArdSearchRequest"
      responses:
        "200":
          description: Ranked ARD catalog entries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArdSearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
  /ard/v1/explore:
    post:
      tags: [ARD]
      summary: Explore facets across gateway-discoverable resources
      operationId: ardExplore
      description: |
        ARD-compatible exploration endpoint for listing available media types,
        capabilities, publishers, and similar facets over the published
        resource catalog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArdExploreRequest"
      responses:
        "200":
          description: Faceted ARD exploration response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArdExploreResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
components:
  parameters:
    Tenant:
      name: tenant
      in: path
      required: true
      schema:
        type: string
        description: Merchant domain or tenant key
        examples:
          - waterproofontario.com
          - example.com
    ProductIdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required: [code, message]
      required: [ok, error]
    KnowledgeObjectType:
      type: string
      enum:
        - product
        - collection
        - content
        - policy
        - service
        - location
        - experience
        - document
    Price:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
        display:
          type: string
      additionalProperties: false
    KnowledgeObject:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: "#/components/schemas/KnowledgeObjectType"
        title:
          type: string
        summary:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        image:
          type: string
          format: uri
        images:
          type: array
          items:
            type: string
            format: uri
        price:
          $ref: "#/components/schemas/Price"
        availability:
          type: string
        attributes:
          type: object
          additionalProperties: true
        policy_refs:
          type: array
          items:
            type: string
        related_ids:
          type: array
          items:
            type: string
      required:
        - id
        - type
        - title
      additionalProperties: true
    SearchResult:
      allOf:
        - $ref: "#/components/schemas/KnowledgeObject"
        - type: object
          properties:
            score:
              type: number
    Product:
      allOf:
        - $ref: "#/components/schemas/KnowledgeObject"
        - type: object
          properties:
            type:
              type: string
              const: product
    Collection:
      allOf:
        - $ref: "#/components/schemas/KnowledgeObject"
        - type: object
          properties:
            type:
              type: string
              const: collection
    Policy:
      allOf:
        - $ref: "#/components/schemas/KnowledgeObject"
        - type: object
          properties:
            type:
              type: string
              const: policy
    ContentObject:
      allOf:
        - $ref: "#/components/schemas/KnowledgeObject"
        - type: object
          properties:
            type:
              type: string
              const: content
    CapabilityFlags:
      type: object
      properties:
        search:
          type: boolean
        plugin_search:
          type: boolean
        compare:
          type: boolean
        recommend:
          type: boolean
        guided_checkout:
          type: boolean
        mcp:
          type: boolean
        ucp:
          type: boolean
        openai_skills:
          type: boolean
      required:
        - search
        - plugin_search
        - compare
        - recommend
        - guided_checkout
        - mcp
        - ucp
        - openai_skills
    CommerceExecutionPolicy:
      type: object
      properties:
        platform:
          type: string
        cart_mode:
          type: string
          enum: [native_adapter, handoff_only]
        checkout_mode:
          type: string
          enum: [platform_native, handoff_only]
        payment_mode:
          type: string
          enum: [platform_native, external]
        native_adapter_name:
          type:
            - string
            - "null"
        do_not_interfere:
          type: boolean
        rules:
          type: array
          items:
            type: string
      required: [platform, cart_mode, checkout_mode, payment_mode, native_adapter_name, do_not_interfere, rules]
    ExtensionLink:
      type: object
      properties:
        supported:
          type: boolean
        discovery_path:
          type: string
      required: [supported, discovery_path]
    GatewayDiscovery:
      type: object
      properties:
        name:
          type: string
        agent_metadata:
          $ref: "#/components/schemas/TenantAgentMetadata"
        version:
          type: string
        spec:
          type: string
        provider:
          type: string
        tagline:
          type: string
        base_url:
          type: string
          format: uri
        endpoints:
          type: object
          additionalProperties:
            type: string
        well_known:
          type: object
          additionalProperties:
            type: string
        tenant_identifier:
          type: string
        supported_types:
          type: array
          items:
            $ref: "#/components/schemas/KnowledgeObjectType"
        capabilities:
          $ref: "#/components/schemas/CapabilityFlags"
        extensions:
          type: object
          properties:
            ucp:
              $ref: "#/components/schemas/ExtensionLink"
            mcp:
              $ref: "#/components/schemas/ExtensionLink"
            openai_skills:
              $ref: "#/components/schemas/ExtensionLink"
        auth:
          type: object
          properties:
            modes:
              type: array
              items:
                type: string
        authentication:
          $ref: "#/components/schemas/Authentication"
      required:
        - name
        - version
        - spec
        - provider
        - tagline
        - base_url
        - endpoints
        - well_known
        - tenant_identifier
        - supported_types
        - capabilities
        - extensions
        - auth
        - authentication
    GatewayDiscoveryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: "#/components/schemas/GatewayDiscovery"
      required: [ok, data]
    UcpDiscoveryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          type: object
          properties:
            version:
              type: string
            supported:
              type: boolean
            endpoints:
              type: object
              additionalProperties:
                type: string
      required: [ok, data]
    McpDiscoveryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          type: object
          properties:
            version:
              type: string
            supported:
              type: boolean
            tools:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
      required: [ok, data]
    McpServerManifest:
      type: object
      properties:
        $schema:
          type: string
          format: uri
        name:
          type: string
          description: Reverse-DNS MCP Registry server name.
        title:
          type: string
        description:
          type: string
        version:
          type: string
        remotes:
          type: array
          items:
            type: object
            additionalProperties: true
        packages:
          type: array
          items:
            type: object
            additionalProperties: true
      required: [name, description, version]
      anyOf:
        - required: [remotes]
        - required: [packages]
    SkillsDiscoveryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          type: object
          properties:
            version:
              type: string
            supported:
              type: boolean
            skills:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
      required: [ok, data]
    Authentication:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              const: none
          required: [type]
        - type: object
          properties:
            type:
              type: string
              const: api_key
            header:
              type: string
          required: [type, header]
    SearchSchema:
      type: object
      properties:
        query:
          type: string
        mode:
          type: string
        limit:
          type: string
        offset:
          type: string
        sort:
          type: string
        filters:
          type: object
          properties:
            vendor:
              type: string
            price:
              type: string
            availability:
              type: string
            collection:
              type: string
            product_type:
              type: string
            tags:
              type: string
      required: [query, mode, limit, offset, sort, filters]
    Operation:
      type: object
      properties:
        method:
          type: string
        href:
          type: string
          format: uri
      required: [method, href]
    Operations:
      type: object
      properties:
        search:
          $ref: "#/components/schemas/Operation"
        products:
          $ref: "#/components/schemas/Operation"
        product:
          $ref: "#/components/schemas/Operation"
        collection:
          $ref: "#/components/schemas/Operation"
      required: [search, products, product, collection]
    ProductDiscovery:
      type: object
      properties:
        source_query:
          type:
            - string
            - "null"
        population_mode:
          type: string
          enum: [browse, query, popular]
        canonical_search_path:
          type: string
          format: uri
        canonical_product_path:
          type: string
          format: uri
      required: [source_query, population_mode, canonical_search_path, canonical_product_path]
    Limits:
      type: object
      properties:
        default_limit:
          type: integer
        max_limit:
          type: integer
      required: [default_limit, max_limit]
    SearchResultSchema:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        url:
          type: string
        image:
          type: string
        price:
          type: string
        score:
          type: string
      required: [id, title, url, image, price, score]
    PaginationMetadata:
      type: object
      properties:
        limit_param:
          type: string
        offset_param:
          type: string
      required: [limit_param, offset_param]
    SearchResultPagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
      required: [limit, offset, total]
    AgentInstructions:
      type: object
      properties:
        preferred_search_mode:
          type: string
          enum: [typeahead, autocomplete, search, hybrid]
        fallback_order:
          type: array
          items:
            type: string
        product_population_flow:
          type: array
          items:
            type: string
      required: [preferred_search_mode, fallback_order, product_population_flow]
    ErrorSchema:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: string
      required: [code, message, details]
    McpServer:
      type: object
      properties:
        server:
          type: string
          format: uri
      required: [server]
    AgentDiscovery:
      type: object
      properties:
        "@context":
          type: string
        "@type":
          type: string
        name:
          type: string
        version:
          type: string
        spec:
          type: string
        base_url:
          type: string
          format: uri
        authentication:
          $ref: "#/components/schemas/Authentication"
        capabilities:
          type: array
          items:
            type: string
        operations:
          $ref: "#/components/schemas/Operations"
        limits:
          $ref: "#/components/schemas/Limits"
        search_schema:
          $ref: "#/components/schemas/SearchSchema"
        response_schema:
          type: object
          properties:
            search_result:
              $ref: "#/components/schemas/SearchResultSchema"
        examples:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              request:
                type: string
                format: uri
        error_schema:
          $ref: "#/components/schemas/ErrorSchema"
        pagination:
          $ref: "#/components/schemas/PaginationMetadata"
        agent_instructions:
          $ref: "#/components/schemas/AgentInstructions"
        mcp:
          $ref: "#/components/schemas/McpServer"
        well_known:
          type: object
          additionalProperties:
            type: string
      required:
        - "@context"
        - "@type"
        - name
        - version
        - spec
        - base_url
        - authentication
        - capabilities
        - operations
        - limits
        - search_schema
        - response_schema
        - examples
        - error_schema
        - pagination
        - agent_instructions
        - well_known
    AgentDiscoveryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: "#/components/schemas/AgentDiscovery"
      required: [ok, data]
    OpenapiDiscoveryResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          type: object
          properties:
            openapi:
              type: string
            version:
              type: string
            url:
              type: string
              format: uri
            format:
              type: string
          required: [openapi, version, url, format]
      required: [ok, data]
    AiPluginDiscovery:
      type: object
      properties:
        schema_version:
          type: string
        name_for_human:
          type: string
        name_for_model:
          type: string
        description_for_human:
          type: string
        description_for_model:
          type: string
        auth:
          type: object
          properties:
            type:
              type: string
        api:
          type: object
          properties:
            type:
              type: string
            url:
              type: string
              format: uri
            is_user_authenticated:
              type: boolean
        logo_url:
          type: string
          format: uri
        contact_email:
          type: string
        legal_info_url:
          type: string
          format: uri
      required:
        - schema_version
        - name_for_human
        - name_for_model
        - description_for_human
        - description_for_model
        - auth
        - api
        - logo_url
        - contact_email
        - legal_info_url
    TenantInfo:
      type: object
      properties:
        "@context":
          type: string
        "@type":
          type: string
        version:
          type: string
        spec:
          type: string
        name:
          type: string
        authentication:
          $ref: "#/components/schemas/Authentication"
        plugin_mode:
          type: object
          properties:
            enabled:
              type: boolean
            default_search_path:
              type: string
            supported_search_modes:
              type: array
              items:
                type: string
            product_path:
              type: string
            collection_path:
              type: string
              format: uri
          required:
            - enabled
            - default_search_path
            - supported_search_modes
        operations:
          $ref: "#/components/schemas/Operations"
        limits:
          $ref: "#/components/schemas/Limits"
        search_schema:
          $ref: "#/components/schemas/SearchSchema"
        response_schema:
          type: object
          properties:
            search_result:
              $ref: "#/components/schemas/SearchResultSchema"
        examples:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              request:
                type: string
                format: uri
        error_schema:
          $ref: "#/components/schemas/ErrorSchema"
        pagination:
          $ref: "#/components/schemas/PaginationMetadata"
        agent_instructions:
          $ref: "#/components/schemas/AgentInstructions"
        types:
          type: array
          items:
            $ref: "#/components/schemas/KnowledgeObjectType"
        capabilities:
          type: array
          items:
            type: string
        commerce_execution:
          $ref: "#/components/schemas/CommerceExecutionPolicy"
        extensions:
          type: object
          properties:
            guided_checkout:
              type: boolean
            ucp:
              type: boolean
            mcp:
              type: boolean
            openai_skills:
              type: boolean
        mcp:
          $ref: "#/components/schemas/McpServer"
        well_known:
          type: object
          additionalProperties:
            type: string
        links:
          type: object
          additionalProperties:
            type: string
      required:
        - "@context"
        - "@type"
        - version
        - spec
        - name
        - authentication
        - plugin_mode
        - operations
        - limits
        - search_schema
        - response_schema
        - examples
        - error_schema
        - pagination
        - agent_instructions
        - types
        - capabilities
        - commerce_execution
        - extensions
        - well_known
        - links
    TenantAgentMetadata:
      type: object
      description: Additive agent-facing metadata that explains this OKS surface without changing its OKS semantics.
      properties:
        organization:
          type: string
        type:
          type: string
          const: knowledge
        searchEndpoint:
          type: string
          format: uri
        answerEndpoint:
          type: string
          format: uri
        lookupEndpoint:
          type: string
          format: uri
        capabilities:
          type: array
          items:
            type: string
        discovery:
          type: object
          properties:
            catalogUrl:
              type: string
              format: uri
            originHtmlLink:
              type: string
            publisher:
              type: string
          required: [catalogUrl, originHtmlLink, publisher]
      required: [organization, type, searchEndpoint, answerEndpoint, lookupEndpoint, capabilities, discovery]
    TenantInfoResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/TenantInfo"
      required: [ok, tenant, data]
    TenantSearchRequest:
      type: object
      description: JSON query content accepted by `QUERY /oks/{tenant}/search`.
      properties:
        q:
          type: string
          minLength: 1
          maxLength: 2000
        type:
          $ref: "#/components/schemas/KnowledgeObjectType"
        mode:
          type: string
          enum: [typeahead, autocomplete, search, hybrid]
          default: search
        vendor:
          type: string
        price:
          type: string
          description: Inclusive price filter formatted as `min..max`.
        availability:
          type: string
        collection:
          type: string
        product_type:
          type: string
        tags:
          type: string
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        offset:
          type: integer
          minimum: 0
          default: 0
      required: [q]
    TenantSearchPayload:
      type: object
      properties:
        version:
          type: string
        spec:
          type: string
        query:
          type: string
        mode:
          type: string
          enum: [typeahead, autocomplete, search, hybrid]
        results:
          type: array
          items:
            $ref: "#/components/schemas/SearchResult"
        total:
          type: integer
        operations:
          $ref: "#/components/schemas/Operations"
        limits:
          $ref: "#/components/schemas/Limits"
        search_schema:
          $ref: "#/components/schemas/SearchSchema"
        response_schema:
          type: object
          properties:
            search_result:
              $ref: "#/components/schemas/SearchResultSchema"
        error_schema:
          $ref: "#/components/schemas/ErrorSchema"
        pagination:
          $ref: "#/components/schemas/SearchResultPagination"
        backend:
          type: object
          properties:
            suggestapi_route:
              type: string
            plugin_mode:
              type: boolean
          required:
            - suggestapi_route
            - plugin_mode
      required: [version, spec, query, mode, results, total, operations, limits, search_schema, response_schema, error_schema, pagination, backend]
    TenantSearchResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/TenantSearchPayload"
      required: [ok, tenant, data]
    ProductListPayload:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Product"
        total:
          type: integer
        discovery:
          $ref: "#/components/schemas/ProductDiscovery"
      required: [items, total, discovery]
    ProductListResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/ProductListPayload"
      required: [ok, tenant, data]
    ProductResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/Product"
      required: [ok, tenant, data]
    CollectionListResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Collection"
            total:
              type: integer
          required: [items, total]
      required: [ok, tenant, data]
    ContentListResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/ContentObject"
            total:
              type: integer
          required: [items, total]
      required: [ok, tenant, data]
    PolicyListResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Policy"
            total:
              type: integer
          required: [items, total]
      required: [ok, tenant, data]
    FilterRange:
      type: object
      properties:
        gte:
          type: number
        lte:
          type: number
    FilterValue:
      oneOf:
        - type: array
          items:
            type: string
        - $ref: "#/components/schemas/FilterRange"
    Filters:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/FilterValue"
    AgentSearchRequest:
      type: object
      properties:
        tenant:
          type: string
        query:
          type: string
        retrieval_mode:
          type: string
          enum: [typeahead, autocomplete, search, hybrid]
          default: hybrid
        types:
          type: array
          items:
            $ref: "#/components/schemas/KnowledgeObjectType"
        filters:
          $ref: "#/components/schemas/Filters"
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      required: [tenant, query]
    AgentSearchData:
      type: object
      properties:
        query:
          type: string
        retrieval_mode:
          type: string
          enum: [typeahead, autocomplete, search, hybrid]
        results:
          type: array
          items:
            $ref: "#/components/schemas/SearchResult"
        answer:
          type:
            - string
            - "null"
        citations:
          type: array
          items:
            type: string
        retrieval:
          type: object
          properties:
            source:
              type: string
              enum: [tenant_surface, suggestapi_ai]
            tenant_search_path:
              type: string
          required:
            - source
            - tenant_search_path
      required: [query, retrieval_mode, results, answer, citations, retrieval]
    AgentSearchResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/AgentSearchData"
      required: [ok, tenant, data]
    AgentCompareRequest:
      type: object
      properties:
        tenant:
          type: string
        ids:
          type: array
          minItems: 2
          maxItems: 5
          items:
            type: string
        dimensions:
          type: array
          items:
            type: string
      required: [tenant, ids]
    ComparisonDimension:
      type: object
      properties:
        name:
          type: string
        values:
          type: object
          additionalProperties: true
      required: [name, values]
    AgentCompareData:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/KnowledgeObject"
        comparison:
          type: object
          properties:
            dimensions:
              type: array
              items:
                $ref: "#/components/schemas/ComparisonDimension"
          required: [dimensions]
        summary:
          type: string
      required: [items, comparison, summary]
    AgentCompareResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/AgentCompareData"
      required: [ok, tenant, data]
    AgentRecommendRequest:
      type: object
      properties:
        tenant:
          type: string
        query:
          type: string
        context:
          type: object
          additionalProperties: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 5
      required: [tenant, query]
    Recommendation:
      allOf:
        - $ref: "#/components/schemas/KnowledgeObject"
        - type: object
          properties:
            reason:
              type: string
    AgentRecommendData:
      type: object
      properties:
        recommendations:
          type: array
          items:
            $ref: "#/components/schemas/Recommendation"
      required: [recommendations]
    AgentRecommendResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/AgentRecommendData"
      required: [ok, tenant, data]
    AgentCartRequest:
      type: object
      properties:
        tenant:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/CheckoutItem"
        buyer_context:
          type: object
          additionalProperties: true
      required: [tenant, items]
    AgentCartLineItem:
      type: object
      properties:
        id:
          type: string
        quantity:
          type: integer
        product:
          $ref: "#/components/schemas/Product"
        product_url:
          type:
            - string
            - "null"
          format: uri
      required: [id, quantity, product, product_url]
    AgentCartResources:
      type: object
      properties:
        tenant:
          type: string
          format: uri
        products:
          type: string
          format: uri
        search:
          type: string
          format: uri
        checkout_guide:
          type: string
          format: uri
      required: [tenant, products, search, checkout_guide]
    AgentCartData:
      type: object
      properties:
        mode:
          type: string
          enum: [native_adapter, handoff_only]
        items:
          type: array
          items:
            $ref: "#/components/schemas/AgentCartLineItem"
        cart_url:
          type:
            - string
            - "null"
          format: uri
        checkout_url:
          type:
            - string
            - "null"
          format: uri
        missing_item_ids:
          type: array
          items:
            type: string
        commerce_execution:
          $ref: "#/components/schemas/CommerceExecutionPolicy"
        resources:
          $ref: "#/components/schemas/AgentCartResources"
        notes:
          type: array
          items:
            type: string
      required: [mode, items, cart_url, checkout_url, missing_item_ids, commerce_execution, resources, notes]
    AgentCartResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/AgentCartData"
      required: [ok, tenant, data]
    CheckoutItem:
      type: object
      properties:
        id:
          type: string
        quantity:
          type: integer
          minimum: 1
      required: [id, quantity]
    GuidedCheckoutRequest:
      type: object
      properties:
        tenant:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/CheckoutItem"
        buyer_context:
          type: object
          additionalProperties: true
      required: [tenant, items]
    GuidedCheckoutData:
      type: object
      properties:
        mode:
          type: string
          enum: [handoff, guided, unavailable]
        checkout_url:
          type:
            - string
            - "null"
          format: uri
        requirements:
          type: array
          items:
            type: string
        notes:
          type: array
          items:
            type: string
      required: [mode, checkout_url, requirements, notes]
    GuidedCheckoutResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        tenant:
          type: string
        data:
          $ref: "#/components/schemas/GuidedCheckoutData"
      required: [ok, tenant, data]
    ArdCatalogHost:
      type: object
      properties:
        displayName:
          type: string
        identifier:
          type: string
        documentationUrl:
          type: string
        logoUrl:
          type: string
        trustManifest:
          $ref: "#/components/schemas/ArdTrustManifest"
      required: [displayName]
    ArdTrustAttestation:
      type: object
      properties:
        type:
          type: string
        uri:
          type: string
          format: uri
        digest:
          type: string
      required: [type, uri]
    ArdTrustProvenance:
      type: object
      properties:
        relation:
          type: string
        sourceId:
          type: string
        sourceDigest:
          type: string
      required: [relation, sourceId]
    ArdTrustManifest:
      type: object
      properties:
        identity:
          type: string
          description: Cryptographic identity anchored to the catalog publisher domain.
        identityType:
          type: string
        attestations:
          type: array
          items:
            $ref: "#/components/schemas/ArdTrustAttestation"
        provenance:
          type: array
          items:
            $ref: "#/components/schemas/ArdTrustProvenance"
        signature:
          type: string
      required: [identity]
    DidDocument:
      type: object
      additionalProperties: true
      properties:
        "@context":
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        id:
          type: string
          const: did:web:agent.suggestapi.com
      required: ["@context", id]
    ArdCatalogEntry:
      type: object
      properties:
        identifier:
          type: string
        displayName:
          type: string
        type:
          type: string
        url:
          type: string
        data:
          type: object
          additionalProperties: true
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        capabilities:
          type: array
          items:
            type: string
        representativeQueries:
          type: array
          items:
            type: string
        version:
          type: string
        updatedAt:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
        trustManifest:
          $ref: "#/components/schemas/ArdTrustManifest"
      required: [identifier, displayName, type]
      oneOf:
        - required: [url]
        - required: [data]
    ArdCatalogManifest:
      type: object
      properties:
        specVersion:
          type: string
        host:
          $ref: "#/components/schemas/ArdCatalogHost"
        entries:
          type: array
          items:
            $ref: "#/components/schemas/ArdCatalogEntry"
      required: [specVersion, host, entries]
    ArdQuery:
      type: object
      properties:
        text:
          type: string
        filter:
          type: object
          additionalProperties: true
    ArdSearchRequest:
      type: object
      properties:
        query:
          $ref: "#/components/schemas/ArdQuery"
        federation:
          type: string
          enum: [none]
          default: none
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
        pageToken:
          type: string
    ArdSearchResult:
      allOf:
        - $ref: "#/components/schemas/ArdCatalogEntry"
        - type: object
          properties:
            score:
              type: number
            source:
              type: string
          required: [score, source]
    ArdSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/ArdSearchResult"
        referrals:
          type: array
          items:
            $ref: "#/components/schemas/ArdCatalogEntry"
        pageToken:
          type: string
      required: [results, referrals]
    ArdFacetRequest:
      type: object
      properties:
        field:
          type: string
        limit:
          type: integer
          minimum: 1
          maximum: 100
        minCount:
          type: integer
          minimum: 1
      required: [field]
    ArdExploreRequest:
      type: object
      properties:
        query:
          $ref: "#/components/schemas/ArdQuery"
        resultType:
          type: object
          properties:
            facets:
              type: array
              items:
                $ref: "#/components/schemas/ArdFacetRequest"
          required: [facets]
      required: [resultType]
    ArdFacetBucket:
      type: object
      properties:
        value:
          type: string
        count:
          type: integer
      required: [value, count]
    ArdFacetResult:
      type: object
      properties:
        buckets:
          type: array
          items:
            $ref: "#/components/schemas/ArdFacetBucket"
        otherCount:
          type: integer
      required: [buckets, otherCount]
    ArdExploreResponse:
      type: object
      properties:
        resultType:
          type: string
          enum: [facets]
        facets:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ArdFacetResult"
      required: [resultType, facets]
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
