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

openapi: 3.0.0
info:
  title: Scope3 Storefront API
  version: 2.0.0
  description: |-
    REST API for partners to manage storefronts, inventory sources, and billing.

    ## 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/storefront`

    ## For AI Agents

    AI agents can use the MCP endpoint at `/mcp/v2/storefront` 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/storefront
    description: Production server
  - url: https://api.agentic.staging.scope3.com/api/v2/storefront
    description: Staging server
tags:
  - name: Storefront
    description: Manage storefront and inventory sources
  - name: Storefront Billing
    description: Stripe Connect billing for storefronts
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /:
    servers: &ref_0
      - url: https://api.agentic.scope3.com/mcp/v2/storefront
        description: Production MCP server
      - url: https://api.agentic.staging.scope3.com/mcp/v2/storefront
        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-storefront-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: []
  /readiness:
    get:
      operationId: getStorefrontReadiness
      summary: Get storefront readiness
      description: >-
        Check if the storefront is ready to go live. Returns blocking checks for inventory sources, agent status, and
        agent auth.
      tags:
        - Storefront
      security:
        - bearerAuth: []
      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'
  /inventory-sources:
    get:
      operationId: listInventorySources
      summary: List inventory sources
      description: List all inventory sources for the storefront.
      tags:
        - Storefront
      security:
        - bearerAuth: []
      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:
        - Storefront
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceId:
                  description: >-
                    Unique identifier for this source within the storefront. Defaults to a slugified version of the name
                    if not provided.
                  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:
                - 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'
  /inventory-sources/{sourceId}:
    get:
      operationId: getInventorySource
      summary: Get inventory source
      description: Get a specific inventory source by its source ID.
      tags:
        - Storefront
      security:
        - bearerAuth: []
      parameters:
        - 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:
        - Storefront
      security:
        - bearerAuth: []
      parameters:
        - 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:
        - Storefront
      security:
        - bearerAuth: []
      parameters:
        - 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'
  /billing/connect:
    post:
      operationId: provisionStripeConnect
      summary: Provision Stripe Connect account
      description: Create a Stripe Express account for the storefront and return an onboarding URL.
      tags:
        - Storefront Billing
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Provision Stripe Connect account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisionConnectResponse'
        '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'
  /billing:
    get:
      operationId: getStorefrontBilling
      summary: Get billing config
      description: Get the billing configuration for the storefront.
      tags:
        - Storefront Billing
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Get billing config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBillingResponse'
        '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'
  /billing/status:
    get:
      operationId: getStripeAccountStatus
      summary: Get Stripe account status
      description: Retrieve Stripe Connect account verification status and balance.
      tags:
        - Storefront Billing
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Get Stripe account status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectAccountStatusResponse'
        '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'
  /billing/transactions:
    get:
      operationId: getBalanceTransactions
      summary: Get balance transactions
      description: Cursor-paginated list of balance transactions for the connected Stripe account.
      tags:
        - Storefront Billing
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            description: Maximum number of results (1–100, default 25)
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of results (1–100, default 25)
        - in: query
          name: starting_after
          schema:
            description: Cursor for pagination (ID of last item from previous page)
            type: string
          description: Cursor for pagination (ID of last item from previous page)
      responses:
        '200':
          description: Get balance transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsResponse'
        '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'
  /billing/payouts:
    get:
      operationId: getPayouts
      summary: Get payouts
      description: Cursor-paginated list of payouts for the connected Stripe account.
      tags:
        - Storefront Billing
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            description: Maximum number of results (1–100, default 25)
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of results (1–100, default 25)
        - in: query
          name: starting_after
          schema:
            description: Cursor for pagination (ID of last item from previous page)
            type: string
          description: Cursor for pagination (ID of last item from previous page)
      responses:
        '200':
          description: Get payouts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutsResponse'
        '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'
  /billing/onboard:
    get:
      operationId: getOnboardingUrl
      summary: Get onboarding URL
      description: Get a fresh Stripe onboarding URL. Onboarding links expire after 24 hours.
      tags:
        - Storefront Billing
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Get onboarding URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingUrlResponse'
        '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'
  /api-call:
    servers: *ref_0
    post:
      operationId: mcpApiCall
      summary: Make API call via MCP
      description: |-
        Make REST API calls to any Storefront API endpoint through MCP.

        ## Parameters

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

        ## Example: List Storefronts

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

        ## Example Response

        ```json
        {
          "jsonrpc": "2.0",
          "id": 2,
          "result": {
            "content": [
              {
                "type": "text",
                "text": "{ \"inventory-sources\": [...], \"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: /inventory-sources
                  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 Storefront 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"). Defaults to a slugified version of
            name if not provided.
          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
        publisherDomain:
          description: Publisher domain for Stripe Connect business profile
          example: cvs.com
          type: string
          minLength: 1
          maxLength: 255
        plan:
          description: Storefront plan tier
          default: basic
          type: string
          enum:
            - basic
      required:
        - name
    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
        publisherDomain:
          description: Publisher domain for Stripe Connect
          example: cvs.com
          nullable: true
          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
        - publisherDomain
        - plan
        - enabled
        - createdAt
        - updatedAt
      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
    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
        compliance:
          description: Per-agent compliance results (present on agent_connectivity checks)
          type: array
          items:
            $ref: '#/components/schemas/AgentComplianceResult'
      required:
        - id
        - name
        - description
        - category
        - status
        - isBlocker
      additionalProperties: false
    AgentComplianceResult:
      description: Compliance assessment for a single agent
      type: object
      properties:
        agentId:
          type: string
        agentUrl:
          type: string
        passed:
          type: boolean
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceTrackResult'
        summary:
          description: One-line compliance headline
          type: string
        observations:
          description: Advisory observations from compliance checks
          type: array
          items:
            type: object
            properties:
              category:
                type: string
              severity:
                type: string
                enum:
                  - info
                  - suggestion
                  - warning
                  - error
              message:
                type: string
            required:
              - category
              - severity
              - message
            additionalProperties: false
        durationMs:
          type: number
        error:
          type: string
      required:
        - agentId
        - agentUrl
        - passed
        - tracks
        - summary
        - observations
        - durationMs
      additionalProperties: false
    ComplianceTrackResult:
      description: Result for a single compliance track
      type: object
      properties:
        track:
          description: Compliance track name
          type: string
        status:
          description: Track assessment result
          type: string
          enum:
            - pass
            - fail
            - skip
            - partial
            - expected
        label:
          description: Human-readable track label
          type: string
        durationMs:
          description: Track duration in ms
          type: number
      required:
        - track
        - status
        - label
        - durationMs
      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
    ProvisionConnectResponse:
      type: object
      properties:
        stripeConnectedAccountId:
          type: string
        onboardingUrl:
          type: string
      required:
        - stripeConnectedAccountId
        - onboardingUrl
      additionalProperties: false
    GetBillingResponse:
      type: object
      properties:
        billing:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/StorefrontBillingResponse'
      required:
        - billing
      additionalProperties: false
    StorefrontBillingResponse:
      description: Storefront billing configuration
      type: object
      properties:
        stripeConnectedAccountId:
          description: Stripe Express account ID
          nullable: true
          type: string
        onboardingStatus:
          description: Stripe Connect onboarding status
          type: string
          enum:
            - pending
            - complete
            - restricted
        platformFeePercent:
          description: Platform fee percentage
          nullable: true
          type: number
        fees:
          description: Additional fees
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/BillingFee'
        currency:
          description: ISO 4217 currency code
          nullable: true
          type: string
        defaultNetDays:
          description: Payment terms in days
          nullable: true
          type: number
        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:
        - stripeConnectedAccountId
        - onboardingStatus
        - platformFeePercent
        - fees
        - currency
        - defaultNetDays
        - createdAt
        - updatedAt
      additionalProperties: false
    BillingFee:
      description: An additional billing fee entry
      type: object
      properties:
        name:
          description: Fee label
          type: string
          minLength: 1
          maxLength: 255
        description:
          description: Fee description
          type: string
          maxLength: 500
        feePercent:
          description: Fee percentage (0–100)
          type: number
          minimum: 0
          maximum: 100
      required:
        - name
        - feePercent
      additionalProperties: false
    ConnectAccountStatusResponse:
      description: Stripe Connect account status and balance
      type: object
      properties:
        accountId:
          type: string
        chargesEnabled:
          type: boolean
        payoutsEnabled:
          type: boolean
        requirements:
          type: object
          properties:
            currentlyDue:
              type: array
              items:
                type: string
            eventuallyDue:
              type: array
              items:
                type: string
          required:
            - currentlyDue
            - eventuallyDue
          additionalProperties: false
        balance:
          type: object
          properties:
            available:
              type: array
              items:
                type: object
                properties:
                  amount:
                    type: number
                  currency:
                    type: string
                required:
                  - amount
                  - currency
                additionalProperties: false
            pending:
              type: array
              items:
                type: object
                properties:
                  amount:
                    type: number
                  currency:
                    type: string
                required:
                  - amount
                  - currency
                additionalProperties: false
          required:
            - available
            - pending
          additionalProperties: false
      required:
        - accountId
        - chargesEnabled
        - payoutsEnabled
        - requirements
        - balance
      additionalProperties: false
    TransactionsResponse:
      description: Paginated balance transactions
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BalanceTransactionItem'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      required:
        - data
        - meta
      additionalProperties: false
    BalanceTransactionItem:
      description: A Stripe balance transaction
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        amount:
          type: number
        currency:
          type: string
        created:
          type: number
        description:
          nullable: true
          type: string
        status:
          type: string
        fee:
          type: number
        net:
          type: number
      required:
        - id
        - type
        - amount
        - currency
        - created
        - description
        - status
        - fee
        - net
      additionalProperties: false
    PaginationMeta:
      description: Cursor-based pagination metadata
      type: object
      properties:
        count:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        limit:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        hasMore:
          type: boolean
        cursor:
          nullable: true
          type: string
      required:
        - count
        - limit
        - hasMore
        - cursor
      additionalProperties: false
    PayoutsResponse:
      description: Paginated payouts
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PayoutItem'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
      required:
        - data
        - meta
      additionalProperties: false
    PayoutItem:
      description: A Stripe payout
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
        currency:
          type: string
        created:
          type: number
        arrivalDate:
          type: number
        status:
          type: string
        method:
          type: string
        description:
          nullable: true
          type: string
      required:
        - id
        - amount
        - currency
        - created
        - arrivalDate
        - status
        - method
        - description
      additionalProperties: false
    OnboardingUrlResponse:
      type: object
      properties:
        onboardingUrl:
          type: string
      required:
        - onboardingUrl
      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., "/inventory-sources")
                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
