# This OpenAPI specification is auto-generated
# DO NOT EDIT THIS FILE MANUALLY
# API Type: PARTNER
# API Version: V2

openapi: 3.0.0
info:
  title: Scope3 Partner API
  version: 2.0.0
  description: |-
    REST API for partners to manage sales agents and configure authentication.

    ## Authentication

    All endpoints require a Bearer token in the Authorization header:
    ```
    Authorization: Bearer your-api-key
    ```

    ## Base URL

    `https://api.agentic.scope3.com/api/v2/partner`

    ## Key Concepts

    - **Agents** are sales agents with MCP or A2A protocol support

    ## For AI Agents

    AI agents can use the MCP endpoint at `/mcp/v2/partner` with three tools:
    - `initialize`: Start an MCP session
    - `api_call`: Make REST API calls
    - `ask_about_capability`: Learn about API features
servers:
  - url: https://api.agentic.scope3.com/api/v2/partner
    description: Production server
  - url: https://api.agentic.staging.scope3.com/api/v2/partner
    description: Staging server
tags:
  - name: Agents
    description: Manage sales agents
  - name: Storefronts
    description: Manage storefronts and inventory sources
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /agents:
    get:
      operationId: listPartnerAgents
      summary: List agents
      description: List agents with optional filtering by type, status, and relationship.
      tags:
        - Agents
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: type
          schema:
            description: Filter by agent type
            type: string
            enum:
              - SALES
              - SIGNAL
              - CREATIVE
              - OUTCOME
          description: Filter by agent type
        - in: query
          name: status
          schema:
            description: Filter by agent status
            type: string
            enum:
              - PENDING
              - ACTIVE
              - DISABLED
          description: Filter by agent status
        - in: query
          name: relationship
          schema:
            description: 'Filter by relationship: SELF = owned by you, MARKETPLACE = all other marketplace agents'
            type: string
            enum:
              - SELF
              - MARKETPLACE
          description: 'Filter by relationship: SELF = owned by you, MARKETPLACE = all other marketplace agents'
        - in: query
          name: name
          schema:
            description: Filter by agent name (partial match, case-insensitive)
            type: string
          description: Filter by agent name (partial match, case-insensitive)
        - in: query
          name: supportsRegistration
          schema:
            description: When true, return only agents that require operator authentication (require_operator_auth = true)
            type: string
            enum:
              - 'true'
              - 'false'
          description: When true, return only agents that require operator authentication (require_operator_auth = true)
        - in: query
          name: limit
          schema:
            description: 'Maximum number of agents to return per page (default: 10, max: 10)'
            type: integer
            exclusiveMinimum: true
            maximum: 10
          description: 'Maximum number of agents to return per page (default: 10, max: 10)'
        - in: query
          name: offset
          schema:
            description: 'Number of agents to skip for pagination (default: 0)'
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: 'Number of agents to skip for pagination (default: 0)'
      responses:
        '200':
          description: List agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: registerPartnerAgent
      summary: Register agent
      description: >-
        Register a new agent under a partner. Requires type, endpoint URL, protocol, authentication type, and account
        policy.
      tags:
        - Agents
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  description: Agent type
                  type: string
                  enum:
                    - SALES
                    - SIGNAL
                    - CREATIVE
                    - OUTCOME
                name:
                  description: Agent name
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  description: Agent description
                  type: string
                  maxLength: 2000
                endpointUrl:
                  description: Agent endpoint URL
                  type: string
                  maxLength: 2048
                  format: uri
                protocol:
                  description: Agent protocol
                  type: string
                  enum:
                    - MCP
                    - A2A
                authenticationType:
                  description: Authentication method required to connect to this agent
                  type: string
                  enum:
                    - API_KEY
                    - NO_AUTH
                    - JWT
                    - OAUTH
                auth:
                  description: Initial credentials for testing and validation. Required for non-OAUTH agents.
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - jwt
                        privateKey:
                          type: string
                          minLength: 1
                        issuer:
                          type: string
                          minLength: 1
                        subject:
                          type: string
                          minLength: 1
                        keyId:
                          type: string
                          minLength: 1
                        scope:
                          type: string
                          minLength: 1
                        tokenEndpointUrl:
                          type: string
                          format: uri
                        audienceUrl:
                          type: string
                          format: uri
                        algorithm:
                          type: string
                          enum:
                            - ES256
                            - RS256
                        environment:
                          type: string
                      required:
                        - type
                        - privateKey
                        - issuer
                        - subject
                        - keyId
                        - scope
                        - tokenEndpointUrl
                        - audienceUrl
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - bearer
                            - apikey
                            - api_key
                        token:
                          type: string
                          minLength: 1
                      required:
                        - type
                        - token
                    - type: object
                      properties: {}
                reportingType:
                  type: string
                  enum:
                    - WEBHOOK
                    - BUCKET
                    - POLLING
                reportingPollingCadence:
                  type: string
                  enum:
                    - DAILY
                    - MONTHLY
              required:
                - type
                - name
                - endpointUrl
                - protocol
                - authenticationType
      responses:
        '201':
          description: Register agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredAgent'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /agents/{agentId}:
    get:
      operationId: getPartnerAgent
      summary: Get agent
      description: Get details of a specific agent.
      tags:
        - Agents
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: agentId
          schema:
            description: Agent ID
            type: string
            minLength: 1
          required: true
          description: Agent ID
      responses:
        '200':
          description: Get agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDetail'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: updatePartnerAgent
      summary: Update agent
      description: Update an agent. At least one field must be provided.
      tags:
        - Agents
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: agentId
          schema:
            description: Agent ID
            type: string
            minLength: 1
          required: true
          description: Agent ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Agent name
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  description: Agent description
                  type: string
                  maxLength: 2000
                endpointUrl:
                  description: Agent endpoint URL
                  type: string
                  maxLength: 2048
                  format: uri
                protocol:
                  description: Agent protocol
                  type: string
                  enum:
                    - MCP
                    - A2A
                authenticationType:
                  description: Authentication method
                  type: string
                  enum:
                    - API_KEY
                    - NO_AUTH
                    - JWT
                    - OAUTH
                auth:
                  description: >-
                    Authentication configuration. For API_KEY/JWT: provide new credentials. For OAUTH agents: triggers
                    re-authorization and returns a new authorizationUrl.
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - jwt
                        privateKey:
                          type: string
                          minLength: 1
                        issuer:
                          type: string
                          minLength: 1
                        subject:
                          type: string
                          minLength: 1
                        keyId:
                          type: string
                          minLength: 1
                        scope:
                          type: string
                          minLength: 1
                        tokenEndpointUrl:
                          type: string
                          format: uri
                        audienceUrl:
                          type: string
                          format: uri
                        algorithm:
                          type: string
                          enum:
                            - ES256
                            - RS256
                        environment:
                          type: string
                      required:
                        - type
                        - privateKey
                        - issuer
                        - subject
                        - keyId
                        - scope
                        - tokenEndpointUrl
                        - audienceUrl
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - bearer
                            - apikey
                            - api_key
                        token:
                          type: string
                          minLength: 1
                      required:
                        - type
                        - token
                    - type: object
                      properties: {}
                reportingType:
                  description: Reporting type
                  type: string
                  enum:
                    - WEBHOOK
                    - BUCKET
                    - POLLING
                reportingPollingCadence:
                  description: Polling cadence (when reportingType is POLLING)
                  type: string
                  enum:
                    - DAILY
                    - MONTHLY
                status:
                  description: Agent status
                  type: string
                  enum:
                    - PENDING
                    - ACTIVE
                    - DISABLED
      responses:
        '200':
          description: Update agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAgentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /storefronts:
    post:
      operationId: createStorefront
      summary: Create storefront
      description: Create a storefront for the authenticated customer. Each customer may have at most one storefront.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStorefrontBody'
      responses:
        '201':
          description: Create storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: getCustomerStorefront
      summary: Get customer storefront
      description: Get the authenticated customer's storefront.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Get customer storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /storefronts/{platformId}:
    get:
      operationId: getStorefront
      summary: Get storefront by platformId
      description: Get a storefront by its platform ID.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            example: cvs-media
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
      responses:
        '200':
          description: Get storefront by platformId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateStorefront
      summary: Update storefront
      description: Update a storefront configuration.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            example: cvs-media
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Updated display name
                  example: CVS Media Network
                  type: string
                  minLength: 1
                  maxLength: 255
                platformId:
                  description: Updated platform slug
                  type: string
                  minLength: 2
                  maxLength: 100
                  pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
                plan:
                  description: Updated plan tier
                  type: string
                  enum:
                    - basic
                enabled:
                  description: Enable or disable the storefront
                  type: boolean
      responses:
        '200':
          description: Update storefront
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteStorefront
      summary: Delete storefront
      description: Delete a storefront and all its inventory sources. Linked agents are disabled before deletion.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            example: cvs-media
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /storefronts/{platformId}/readiness:
    get:
      operationId: getStorefrontReadiness
      summary: Get storefront readiness
      description: >-
        Check if a storefront is ready to go live. Returns blocking checks for inventory sources, agent status, and
        agent auth.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            example: cvs-media
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
      responses:
        '200':
          description: Get storefront readiness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontReadinessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /storefronts/{platformId}/inventory-sources:
    get:
      operationId: listInventorySources
      summary: List inventory sources
      description: List all inventory sources for a storefront.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            example: cvs-media
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
      responses:
        '200':
          description: List inventory sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventorySourceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createInventorySource
      summary: Create inventory source
      description: Create an inventory source and optionally register an agent for it.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            example: cvs-media
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceId:
                  description: Unique identifier for this source within the storefront
                  example: snap-ads-agent
                  type: string
                  minLength: 1
                  maxLength: 255
                name:
                  description: Display name for the inventory source
                  example: Snap Ads Agent
                  type: string
                  minLength: 1
                  maxLength: 255
                executionType:
                  description: How the source executes requests
                  default: agent
                  type: string
                  enum:
                    - agent
                executionConfig:
                  description: Configuration for the execution type (e.g. agent URL, auth, headers)
                  type: object
                  additionalProperties: {}
                type:
                  description: Agent type — required when executionType is "agent"
                  type: string
                  enum:
                    - SALES
                    - SIGNAL
                    - CREATIVE
                    - OUTCOME
                endpointUrl:
                  description: Agent endpoint URL — required when executionType is "agent"
                  type: string
                  maxLength: 2048
                  format: uri
                protocol:
                  description: Agent protocol — required when executionType is "agent"
                  type: string
                  enum:
                    - MCP
                    - A2A
                authenticationType:
                  description: Auth method for the agent — required when executionType is "agent"
                  type: string
                  enum:
                    - API_KEY
                    - NO_AUTH
                    - JWT
                    - OAUTH
                auth:
                  description: Initial credentials for testing. Required for non-OAUTH agents when executionType is "agent".
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - jwt
                        privateKey:
                          type: string
                          minLength: 1
                        issuer:
                          type: string
                          minLength: 1
                        subject:
                          type: string
                          minLength: 1
                        keyId:
                          type: string
                          minLength: 1
                        scope:
                          type: string
                          minLength: 1
                        tokenEndpointUrl:
                          type: string
                          format: uri
                        audienceUrl:
                          type: string
                          format: uri
                        algorithm:
                          type: string
                          enum:
                            - ES256
                            - RS256
                        environment:
                          type: string
                      required:
                        - type
                        - privateKey
                        - issuer
                        - subject
                        - keyId
                        - scope
                        - tokenEndpointUrl
                        - audienceUrl
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - bearer
                            - apikey
                            - api_key
                        token:
                          type: string
                          minLength: 1
                      required:
                        - type
                        - token
                    - type: object
                      properties: {}
                description:
                  description: Agent description
                  type: string
                  maxLength: 2000
              required:
                - sourceId
                - name
      responses:
        '201':
          description: Create inventory source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventorySourceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /storefronts/{platformId}/inventory-sources/{sourceId}:
    get:
      operationId: getInventorySource
      summary: Get inventory source
      description: Get a specific inventory source by its source ID.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
        - in: path
          name: sourceId
          schema:
            description: Inventory source ID
            type: string
            minLength: 1
          required: true
          description: Inventory source ID
      responses:
        '200':
          description: Get inventory source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventorySourceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateInventorySource
      summary: Update inventory source
      description: Update an inventory source. Status transitions manage the linked agent lifecycle.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
        - in: path
          name: sourceId
          schema:
            description: Inventory source ID
            type: string
            minLength: 1
          required: true
          description: Inventory source ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Updated display name
                  type: string
                  minLength: 1
                  maxLength: 255
                executionType:
                  description: Updated execution type
                  type: string
                  enum:
                    - agent
                executionConfig:
                  description: Updated execution configuration
                  type: object
                  additionalProperties: {}
                status:
                  description: Updated source status (pending → active, active → disabled)
                  type: string
                  enum:
                    - pending
                    - active
                    - disabled
      responses:
        '200':
          description: Update inventory source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventorySourceResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteInventorySource
      summary: Delete inventory source
      description: Delete an inventory source. The linked agent is disabled before removal.
      tags:
        - Storefronts
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: platformId
          schema:
            description: Storefront platform ID slug
            type: string
            minLength: 1
          required: true
          description: Storefront platform ID slug
        - in: path
          name: sourceId
          schema:
            description: Inventory source ID
            type: string
            minLength: 1
          required: true
          description: Inventory source ID
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /:
    servers: &ref_0
      - url: https://api.agentic.scope3.com/mcp/v2/partner
        description: Production MCP server
      - url: https://api.agentic.staging.scope3.com/mcp/v2/partner
        description: Staging MCP server
    post:
      operationId: mcpInitialize
      summary: Initialize MCP session
      description: |-
        Start a new MCP (Model Context Protocol) session. This must be called before using any other MCP tools.

        ## Request Format

        Send a JSON-RPC 2.0 request with:
        - `method`: "initialize"
        - `params.protocolVersion`: "2024-11-05"
        - `params.capabilities`: {} (empty object)
        - `params.clientInfo`: Your agent info

        ## Example Request

        ```json
        {
          "jsonrpc": "2.0",
          "id": 1,
          "method": "initialize",
          "params": {
            "protocolVersion": "2024-11-05",
            "capabilities": {},
            "clientInfo": { "name": "your-agent", "version": "1.0" }
          }
        }
        ```

        ## Example Response

        ```json
        {
          "jsonrpc": "2.0",
          "id": 1,
          "result": {
            "protocolVersion": "2024-11-05",
            "capabilities": { "tools": {} },
            "serverInfo": { "name": "scope3-partner-api", "version": "2.0.0" }
          }
        }
        ```
      tags:
        - MCP
      parameters:
        - name: mcp-session-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: MCP session identifier. Generate a new UUID for this request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpInitializeRequest'
            example:
              jsonrpc: '2.0'
              id: 1
              method: initialize
              params:
                protocolVersion: '2024-11-05'
                capabilities: {}
                clientInfo:
                  name: your-agent
                  version: '1.0'
      responses:
        '200':
          description: Session initialized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpInitializeResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
  /api-call:
    servers: *ref_0
    post:
      operationId: mcpApiCall
      summary: Make API call via MCP
      description: |-
        Make REST API calls to any Partner API endpoint through MCP.

        ## Parameters

        - `method`: HTTP method (GET, POST, PUT, DELETE)
        - `path`: API path (e.g., "/agents", "/campaigns/{id}")
        - `body`: Request body for POST/PUT requests (optional)
        - `query`: Query parameters (optional)

        ## Example: List Agents

        ```json
        {
          "jsonrpc": "2.0",
          "id": 2,
          "method": "tools/call",
          "params": {
            "name": "api_call",
            "arguments": {
              "method": "GET",
              "path": "/agents",
              "query": { "take": 10 }
            }
          }
        }
        ```

        ## Example Response

        ```json
        {
          "jsonrpc": "2.0",
          "id": 2,
          "result": {
            "content": [
              {
                "type": "text",
                "text": "{ \"agents\": [...], \"total\": 5 }"
              }
            ]
          }
        }
        ```
      tags:
        - MCP
      parameters:
        - name: mcp-session-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: MCP session identifier from the initialize call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpApiCallRequest'
            example:
              jsonrpc: '2.0'
              id: 2
              method: tools/call
              params:
                name: api_call
                arguments:
                  method: GET
                  path: /agents
                  query:
                    take: 10
      responses:
        '200':
          description: API call executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpToolResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
  /ask-about-capability:
    servers: *ref_0
    post:
      operationId: mcpAskAboutCapability
      summary: Ask about API capabilities
      description: |-
        Learn about Partner API features and capabilities using natural language questions.

        This tool helps AI agents understand what the API can do without needing to read documentation.

        ## Parameters

        - `question`: A natural language question about API capabilities

        ## Example Questions

        - "How do I create a campaign?"
        - "What can I configure on a campaign?"
        - "What authentication is required?"

        ## Example Request

        ```json
        {
          "jsonrpc": "2.0",
          "id": 4,
          "method": "tools/call",
          "params": {
            "name": "ask_about_capability",
            "arguments": {
              "question": "How do I create a campaign?"
            }
          }
        }
        ```

        ## Example Response

        ```json
        {
          "jsonrpc": "2.0",
          "id": 4,
          "result": {
            "content": [
              {
                "type": "text",
                "text": "To create a campaign, use POST /campaigns with..."
              }
            ]
          }
        }
        ```
      tags:
        - MCP
      parameters:
        - name: mcp-session-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          description: MCP session identifier from the initialize call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpAskCapabilityRequest'
            example:
              jsonrpc: '2.0'
              id: 4
              method: tools/call
              params:
                name: ask_about_capability
                arguments:
                  question: How do I create a campaign?
      responses:
        '200':
          description: Capability information returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpToolResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateStorefrontBody:
      description: Request body for creating a storefront
      type: object
      properties:
        platformId:
          description: Public-facing slug for the storefront (e.g. "snapchat", "cvs-media")
          example: cvs-media
          type: string
          minLength: 2
          maxLength: 100
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
        name:
          description: Display name for the storefront
          example: CVS Media
          type: string
          minLength: 1
          maxLength: 255
        plan:
          description: Storefront plan tier
          default: basic
          type: string
          enum:
            - basic
      required:
        - platformId
        - name
    AgentList:
      description: Paginated list of agents
      type: object
      properties:
        items:
          description: List of agents for the current page
          type: array
          items:
            $ref: '#/components/schemas/Agent'
        total:
          description: Total number of agents matching the query
          type: integer
          minimum: 0
          maximum: 9007199254740991
        hasMore:
          description: Whether there are more items available beyond this page. When true, use nextOffset to fetch the next page.
          type: boolean
        nextOffset:
          description: >-
            The offset to use for the next page of results. Pass this as the offset parameter to get the next page. Null
            when there are no more results.
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - items
        - total
        - hasMore
        - nextOffset
      additionalProperties: false
    Agent:
      description: Agent resource (list view)
      type: object
      properties:
        agentId:
          description: Unique agent identifier
          type: string
        type:
          description: >-
            Agent type: SALES = sales/media agent, SIGNAL = signal/data agent, CREATIVE = creative agent, OUTCOME =
            outcome measurement agent
          type: string
          enum:
            - SALES
            - SIGNAL
            - CREATIVE
            - OUTCOME
        name:
          description: Agent display name
          type: string
        description:
          description: Agent description
          nullable: true
          type: string
        endpointUrl:
          description: Agent endpoint URL (empty string for COMING_SOON agents)
          type: string
        protocol:
          description: Agent protocol
          type: string
          enum:
            - MCP
            - A2A
        authenticationType:
          description: Authentication method
          type: string
          enum:
            - API_KEY
            - NO_AUTH
            - JWT
            - OAUTH
        requiresOperatorAuth:
          description: >-
            Whether the agent requires the operator to provide credentials. When true, buyers must register their own
            credentials.
          type: boolean
        billingOptions:
          description: >-
            Billing arrangement options supported by this partner, from its ADCP capabilities. Null when capabilities
            have not been fetched yet.
          nullable: true
          type: object
          properties:
            default:
              nullable: true
              type: string
            supported:
              type: array
              items:
                type: string
          required:
            - default
            - supported
          additionalProperties: false
        status:
          description: Agent status. COMING_SOON is returned for PENDING agents not owned by the caller.
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
            - COMING_SOON
        relationship:
          description: 'Relationship: SELF = owned by you, MARKETPLACE = all other marketplace agents'
          type: string
          enum:
            - SELF
            - MARKETPLACE
        customerAccounts:
          description: Caller's accounts for this agent (excludes marketplace accounts)
          type: array
          items:
            $ref: '#/components/schemas/CustomerAccountSummary'
        requiresAccount:
          description: True when agent supports per-account registration and caller has no accounts
          type: boolean
        authConfigured:
          description: Whether the agent has working authentication configured
          type: boolean
        capabilities:
          description: Discovered agent capabilities. Null if not yet fetched from the agent.
          nullable: true
          type: object
          properties:
            version:
              description: Detected AdCP version of the agent
              type: string
              enum:
                - v2
                - v3
            protocols:
              description: Supported protocols (e.g. media_buy, signals, governance, creative)
              type: array
              items:
                type: string
            extensions:
              description: Supported extension namespaces (e.g. sandbox, scope3)
              type: array
              items:
                type: string
            features:
              description: Media buy feature flags
              type: object
              properties:
                inlineCreativeManagement:
                  type: boolean
                propertyListFiltering:
                  type: boolean
                contentStandards:
                  type: boolean
                conversionTracking:
                  type: boolean
                audienceManagement:
                  type: boolean
              additionalProperties: false
            sandbox:
              description: Whether the agent declares sandbox support via get_adcp_capabilities
              type: boolean
            publisherDomains:
              description: Publisher domains covered by this agent
              type: array
              items:
                type: string
            channels:
              description: Supported advertising channels
              type: array
              items:
                type: string
            lastUpdated:
              description: When capabilities were last reported by the agent
              type: string
            accounts:
              description: Account capabilities from the ADCP account section (require_operator_auth, supported_billing)
              type: object
              properties:
                requireOperatorAuth:
                  description: Whether the agent requires operator-level credentials (maps to ADCP account.require_operator_auth)
                  type: boolean
                defaultBilling:
                  description: Default billing type (maps to ADCP account.default_billing). Null when not reported.
                  nullable: true
                  type: string
                supportedBillings:
                  description: Supported billing types (maps to ADCP account.supported_billing)
                  type: array
                  items:
                    type: string
              required:
                - requireOperatorAuth
                - defaultBilling
                - supportedBillings
              additionalProperties: false
          required:
            - version
            - protocols
            - extensions
            - features
            - sandbox
            - accounts
          additionalProperties: false
        createdAt:
          description: When the agent was created (ISO 8601)
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        oauth:
          description: Present for owner PENDING OAUTH agents without tokens
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OAuthInfo'
      required:
        - agentId
        - type
        - name
        - endpointUrl
        - protocol
        - authenticationType
        - requiresOperatorAuth
        - status
        - relationship
        - requiresAccount
        - authConfigured
        - createdAt
      additionalProperties: false
    CustomerAccountSummary:
      description: Summary of a customer account for an agent
      type: object
      properties:
        accountIdentifier:
          description: Unique account identifier for this agent
          type: string
        status:
          description: Account status
          type: string
      required:
        - accountIdentifier
        - status
      additionalProperties: false
    OAuthInfo:
      description: OAuth authorization info
      type: object
      properties:
        authorizationUrl:
          description: URL the user must visit to authorize
          type: string
          format: uri
        agentId:
          description: Agent identifier
          type: string
        agentName:
          description: Agent display name
          type: string
      required:
        - authorizationUrl
        - agentId
        - agentName
      additionalProperties: false
    Error:
      description: Standard error response
      type: object
      properties:
        error:
          description: Error type
          type: string
        message:
          description: Human-readable error message
          type: string
      required:
        - error
      additionalProperties: false
    RegisteredAgent:
      description: Response after registering a new agent
      type: object
      properties:
        agentId:
          description: Unique agent identifier
          type: string
        type:
          description: >-
            Agent type: SALES = sales/media agent, SIGNAL = signal/data agent, CREATIVE = creative agent, OUTCOME =
            outcome measurement agent
          type: string
          enum:
            - SALES
            - SIGNAL
            - CREATIVE
            - OUTCOME
        name:
          description: Agent display name
          type: string
        status:
          description: Agent status (always PENDING on creation)
          example: PENDING
          type: string
        endpointUrl:
          description: Agent endpoint URL
          type: string
          format: uri
        protocol:
          description: Agent protocol
          type: string
          enum:
            - MCP
            - A2A
        requiresOperatorAuth:
          description: Whether the agent requires operator credentials (auto-detected from capabilities)
          type: boolean
        authenticationType:
          description: Authentication method
          type: string
          enum:
            - API_KEY
            - NO_AUTH
            - JWT
            - OAUTH
        description:
          description: Agent description
          nullable: true
          type: string
        oauth:
          description: Present for OAUTH agents — authorization URL the user must visit
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OAuthInfo'
        oauthError:
          description: OAuth discovery error, if any
          type: string
      required:
        - agentId
        - type
        - name
        - status
        - endpointUrl
        - protocol
        - requiresOperatorAuth
        - authenticationType
      additionalProperties: false
    AgentDetail:
      description: Detailed agent info including account data
      type: object
      properties:
        agentId:
          description: Unique agent identifier
          type: string
        type:
          description: >-
            Agent type: SALES = sales/media agent, SIGNAL = signal/data agent, CREATIVE = creative agent, OUTCOME =
            outcome measurement agent
          type: string
          enum:
            - SALES
            - SIGNAL
            - CREATIVE
            - OUTCOME
        name:
          description: Agent display name
          type: string
        description:
          description: Agent description
          nullable: true
          type: string
        endpointUrl:
          description: Agent endpoint URL (empty string for COMING_SOON agents)
          type: string
        protocol:
          description: Agent protocol
          type: string
          enum:
            - MCP
            - A2A
        authenticationType:
          description: Authentication method
          type: string
          enum:
            - API_KEY
            - NO_AUTH
            - JWT
            - OAUTH
        requiresOperatorAuth:
          description: >-
            Whether the agent requires the operator to provide credentials. When true, buyers must register their own
            credentials.
          type: boolean
        billingOptions:
          description: >-
            Billing arrangement options supported by this partner, from its ADCP capabilities. Null when capabilities
            have not been fetched yet.
          nullable: true
          type: object
          properties:
            default:
              nullable: true
              type: string
            supported:
              type: array
              items:
                type: string
          required:
            - default
            - supported
          additionalProperties: false
        status:
          description: Agent status. COMING_SOON is returned for PENDING agents not owned by the caller.
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
            - COMING_SOON
        relationship:
          description: 'Relationship: SELF = owned by you, MARKETPLACE = all other marketplace agents'
          type: string
          enum:
            - SELF
            - MARKETPLACE
        customerId:
          description: Owner customer ID
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        reportingType:
          description: Reporting type
          nullable: true
          type: string
          enum:
            - WEBHOOK
            - BUCKET
            - POLLING
        reportingPollingCadence:
          description: Polling cadence (when reportingType is POLLING)
          nullable: true
          type: string
          enum:
            - DAILY
            - MONTHLY
        customerAccountCount:
          description: Number of customer accounts for this agent
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        hasCustomerAccount:
          description: Whether the caller has an account for this agent
          type: boolean
        hasMasterAccount:
          description: Whether a marketplace account exists for this agent
          type: boolean
        customerAccount:
          description: Caller's account details, if any
          type: object
          properties:
            id:
              description: Account ID
              type: string
            accountIdentifier:
              description: Unique account identifier
              type: string
            status:
              description: Account status
              type: string
            registeredBy:
              description: Who registered this account
              nullable: true
              type: string
            createdAt:
              description: When the account was created (ISO 8601)
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - id
            - accountIdentifier
            - status
            - registeredBy
            - createdAt
          additionalProperties: false
        createdAt:
          description: When the agent was created (ISO 8601)
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: When the agent was last updated (ISO 8601)
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        oauth:
          description: Present for owner PENDING OAUTH agents without tokens
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OAuthInfo'
      required:
        - agentId
        - type
        - name
        - endpointUrl
        - protocol
        - authenticationType
        - requiresOperatorAuth
        - status
        - relationship
        - customerId
        - customerAccountCount
        - hasCustomerAccount
        - hasMasterAccount
        - createdAt
        - updatedAt
      additionalProperties: false
    UpdateAgentResponse:
      description: Response after updating an agent
      type: object
      properties:
        agentId:
          description: Unique agent identifier
          type: string
        name:
          description: Agent display name
          type: string
        status:
          description: Current agent status
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
        updatedFields:
          description: List of fields that were updated
          type: array
          items:
            type: string
        oauth:
          description: Present when OAUTH agent re-authorization is triggered — contains the new authorization URL
          allOf:
            - $ref: '#/components/schemas/OAuthInfo'
      required:
        - agentId
        - name
        - status
        - updatedFields
      additionalProperties: false
    StorefrontResponse:
      description: Storefront configuration response
      type: object
      properties:
        platformId:
          description: Public-facing slug
          example: cvs-media
          type: string
        name:
          description: Display name
          example: CVS Media
          type: string
        plan:
          description: Storefront plan tier
          type: string
          enum:
            - basic
        enabled:
          description: Whether the storefront is enabled
          type: boolean
        createdAt:
          description: Creation timestamp (ISO 8601)
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: Last update timestamp (ISO 8601)
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - platformId
        - name
        - plan
        - enabled
        - createdAt
        - updatedAt
      additionalProperties: false
    StorefrontReadinessResponse:
      description: Storefront readiness assessment
      type: object
      properties:
        platformId:
          type: string
        status:
          description: Overall storefront readiness status
          type: string
          enum:
            - ready
            - blocked
        checks:
          type: array
          items:
            $ref: '#/components/schemas/ReadinessCheck'
      required:
        - platformId
        - status
        - checks
      additionalProperties: false
    ReadinessCheck:
      description: Individual readiness check result
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        category:
          type: string
        status:
          description: Status of a readiness check
          type: string
          enum:
            - complete
            - partial
            - missing
        isBlocker:
          type: boolean
        method:
          type: string
        details:
          type: string
      required:
        - id
        - name
        - description
        - category
        - status
        - isBlocker
      additionalProperties: false
    InventorySourceResponse:
      description: Inventory source response
      type: object
      properties:
        sourceId:
          description: Unique identifier within the storefront
          type: string
        name:
          description: Display name
          type: string
        executionType:
          description: Execution type
          type: string
        executionConfig:
          description: Execution configuration
          nullable: true
          type: object
          additionalProperties: {}
        status:
          description: Source lifecycle status
          type: string
          enum:
            - pending
            - active
            - disabled
        agentId:
          description: Linked agent ID (when executionType is agent)
          nullable: true
          type: string
        type:
          description: Agent type
          nullable: true
          type: string
          enum:
            - SALES
            - SIGNAL
            - CREATIVE
            - OUTCOME
        endpointUrl:
          description: Agent endpoint URL
          nullable: true
          type: string
        protocol:
          description: Agent protocol
          nullable: true
          type: string
          enum:
            - MCP
            - A2A
        authenticationType:
          description: Agent authentication type
          nullable: true
          type: string
          enum:
            - API_KEY
            - NO_AUTH
            - JWT
            - OAUTH
        authConfigured:
          description: Whether the agent has authentication configured
          type: boolean
        oauth:
          description: OAuth authorization info (for OAUTH agents)
          type: object
          properties:
            authorizationUrl:
              type: string
            agentId:
              type: string
            agentName:
              type: string
          required:
            - authorizationUrl
            - agentId
            - agentName
          additionalProperties: false
        createdAt:
          description: Creation timestamp (ISO 8601)
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          description: Last update timestamp (ISO 8601)
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - sourceId
        - name
        - executionType
        - executionConfig
        - status
        - agentId
        - createdAt
        - updatedAt
      additionalProperties: false
    McpInitializeRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        id:
          oneOf:
            - type: string
            - type: number
          description: Request ID
        method:
          type: string
          enum:
            - initialize
          description: Method name
        params:
          type: object
          properties:
            protocolVersion:
              type: string
              description: MCP protocol version
              example: '2024-11-05'
            capabilities:
              type: object
              description: Client capabilities
            clientInfo:
              type: object
              properties:
                name:
                  type: string
                  description: Client name
                version:
                  type: string
                  description: Client version
              required:
                - name
                - version
          required:
            - protocolVersion
            - capabilities
            - clientInfo
      required:
        - jsonrpc
        - id
        - method
        - params
    McpInitializeResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          oneOf:
            - type: string
            - type: number
        result:
          type: object
          properties:
            protocolVersion:
              type: string
            capabilities:
              type: object
            serverInfo:
              type: object
              properties:
                name:
                  type: string
                version:
                  type: string
    McpApiCallRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        id:
          oneOf:
            - type: string
            - type: number
          description: Request ID
        method:
          type: string
          enum:
            - tools/call
          description: Method name
        params:
          type: object
          properties:
            name:
              type: string
              enum:
                - api_call
              description: Tool name
            arguments:
              type: object
              properties:
                method:
                  type: string
                  enum:
                    - GET
                    - POST
                    - PUT
                    - DELETE
                  description: HTTP method
                path:
                  type: string
                  description: API path (e.g., "/agents")
                body:
                  type: object
                  description: Request body for POST/PUT
                query:
                  type: object
                  description: Query parameters
              required:
                - method
                - path
          required:
            - name
            - arguments
      required:
        - jsonrpc
        - id
        - method
        - params
    McpAskCapabilityRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        id:
          oneOf:
            - type: string
            - type: number
          description: Request ID
        method:
          type: string
          enum:
            - tools/call
          description: Method name
        params:
          type: object
          properties:
            name:
              type: string
              enum:
                - ask_about_capability
              description: Tool name
            arguments:
              type: object
              properties:
                question:
                  type: string
                  description: Natural language question about API capabilities
              required:
                - question
          required:
            - name
            - arguments
      required:
        - jsonrpc
        - id
        - method
        - params
    McpToolResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          oneOf:
            - type: string
            - type: number
        result:
          type: object
          properties:
            content:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - text
                  text:
                    type: string
                    description: Response content
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token
