Scope3 Interchange Buyer API

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

openapi: 3.0.0
info:
  title: Scope3 Buyer API
  version: 2.0.0
  description: |-
    REST API for advertisers to manage advertisers, campaigns, and reporting.

    ## Authentication

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

    ## Base URL

    `https://api.interchange.io/api/v2/buyer`

    ## For AI Agents

    AI agents can use the MCP endpoint at `/mcp/v2/buyer` 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.interchange.io/api/v2/buyer
    description: Production server
tags:
  - name: Signup
    description: Request reviewed access to Interchange
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Asks
    description: What you are waiting on Scope3 for — support, product, and supply asks in one list
  - name: Advertisers
    description: Manage advertisers
  - name: Product Discovery
    description: Discover and select products
  - name: Campaigns
    description: Manage advertising campaigns
  - name: Creatives
    description: Build, manage, and sync campaign creatives via AdCP Creative Protocol
  - name: Reporting
    description: Access performance metrics
  - name: Event Sources
    description: Manage event source configurations and log conversion/marketing events for attribution
  - name: Property Lists
    description: Validate property lists against AAO registry
  - name: Sales Agents
    description: View and connect sales agents
  - name: Measurement
    description: Measurement sources, records, context, and freshness
  - name: Syndication
    description: Syndicate resources to ADCP agents
  - name: Tasks
    description: Track async operation status
  - name: Buyer Billing
    description: Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer.
  - name: MCP
    description: Model Context Protocol endpoints for AI agents
paths:
  /auth/buyer-signup-intake:
    servers:
      - url: https://api.interchange.io
        description: Production signup service
    post:
      operationId: submitBuyerSignupIntake
      summary: Request buyer access
      description: >-
        Submit buyer qualification for human review. This public form does not create an account, grant access, or
        establish organization or email ownership.
      tags:
        - Signup
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  maxLength: 254
                  format: email
                  pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                first_name:
                  type: string
                  minLength: 1
                  maxLength: 80
                last_name:
                  type: string
                  minLength: 1
                  maxLength: 80
                company:
                  type: string
                  minLength: 1
                  maxLength: 200
                role:
                  nullable: true
                  type: string
                  enum:
                    - brand
                    - agency
                intent:
                  nullable: true
                  type: string
                  enum:
                    - self_service
                    - assisted_pilot
                    - evaluate
                    - integration_partnership
                    - campaign_management
                    - agent_connection
                agent_name:
                  nullable: true
                  type: string
                  minLength: 1
                  maxLength: 200
                source:
                  default: agentic-signup
                  type: string
                  enum:
                    - agentic-signup
                    - agentic-login
                    - marketing-site
                use_case:
                  nullable: true
                  type: string
                  maxLength: 1000
                intended_markets:
                  default: []
                  maxItems: 249
                  type: array
                  items:
                    type: string
                    minLength: 2
                    maxLength: 32
                intended_channels:
                  default: []
                  maxItems: 22
                  type: array
                  items:
                    type: string
                    enum:
                      - display
                      - olv
                      - social
                      - search
                      - ctv
                      - linear_tv
                      - radio
                      - streaming_audio
                      - podcast
                      - dooh
                      - ooh
                      - print
                      - cinema
                      - email
                      - gaming
                      - retail_media
                      - influencer
                      - affiliate
                      - product_placement
                      - sponsored_intelligence
                      - audio
                      - other
                pilot_budget:
                  nullable: true
                  type: string
                  minLength: 1
                  maxLength: 100
                pilot_timing:
                  nullable: true
                  type: string
                  enum:
                    - ready_now
                    - one_to_three_months
                    - later
                self_service_experience:
                  nullable: true
                  type: boolean
                prelaunch_slack_consent:
                  nullable: true
                  type: boolean
                website:
                  type: string
                  maxLength: 500
              required:
                - email
                - first_name
                - last_name
                - company
      responses:
        '201':
          description: Request buyer access
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                          - true
                      org_ref:
                        nullable: true
                        type: string
                      qualification_route:
                        type: string
                        enum:
                          - solutions_review
                          - market_nurture
                          - manual_review
                    required:
                      - ok
                      - org_ref
                      - qualification_route
                    additionalProperties: false
                required:
                  - success
                  - data
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers:
    get:
      operationId: listAdvertisers
      summary: List advertisers
      description: List all advertisers with optional filtering and pagination.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: status
          schema:
            description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE.
            default: ACTIVE
            type: string
            enum:
              - ACTIVE
              - ARCHIVED
              - ALL
          description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE.
        - in: query
          name: name
          schema:
            description: Filter by advertiser name (case-insensitive, partial match)
            example: Acme
            type: string
          description: Filter by advertiser name (case-insensitive, partial match)
        - in: query
          name: linkedAccountPartnerId
          schema:
            description: Filter to advertisers linked to at least one account from this partner / sales agent ID.
            example: snap
            type: string
          description: Filter to advertisers linked to at least one account from this partner / sales agent ID.
        - in: query
          name: sandbox
          schema:
            description: >-
              Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers.
              Omit to return all.
            type: boolean
          description: >-
            Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers.
            Omit to return all.
        - in: query
          name: includeBrand
          schema:
            description: >-
              When true, include linked brand identity data on advertiser summary rows so creative agents can use brand
              logos, colors, tone, and catalog data.
            type: boolean
          description: >-
            When true, include linked brand identity data on advertiser summary rows so creative agents can use brand
            logos, colors, tone, and catalog data.
        - in: query
          name: limit
          schema:
            description: 'Maximum number of advertisers to return per page (default: 100, max: 100)'
            example: 100
            default: 100
            type: integer
            maximum: 100
            minimum: 1
          description: 'Maximum number of advertisers to return per page (default: 100, max: 100)'
        - in: query
          name: offset
          schema:
            description: 'Number of advertisers to skip for pagination (default: 0)'
            example: 0
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
          description: 'Number of advertisers to skip for pagination (default: 0)'
      responses:
        '200':
          description: List advertisers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvertiserListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createAdvertiser
      summary: Create advertiser
      description: Create a new advertiser. Advertisers are the top-level entity for campaigns.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdvertiserBody'
      responses:
        '201':
          description: Create advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /all-advertisers-home:
    get:
      operationId: listAllAdvertisersHome
      summary: List all advertisers home
      description: >-
        Pre-assembled data for the buyer "All Advertisers Landing" widget: advertiser rows (brand kit, campaign count,
        resumable-draft flag) plus a portfolio summary. Money rollups (`managed`/`tracked`) are always null pending
        AI-5642; `attention`/`nextAction` are omitted pending AI-5643.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List all advertisers home
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio:
                    type: object
                    properties:
                      tracked:
                        type: string
                      managed:
                        type: string
                      waitingOnYou:
                        type: number
                    required:
                      - tracked
                      - managed
                      - waitingOnYou
                    additionalProperties: false
                  advertisers:
                    type: array
                    items:
                      type: object
                      properties:
                        advertiserId:
                          type: string
                        name:
                          type: string
                        initials:
                          type: string
                        brandColors:
                          type: object
                          additionalProperties:
                            type: string
                        logoUrl:
                          type: string
                        logoTileColor:
                          type: string
                        logoFill:
                          type: boolean
                        managed:
                          nullable: true
                          type: string
                        tracked:
                          nullable: true
                          type: string
                        campaignCount:
                          type: number
                        resumableDraft:
                          type: boolean
                        attention:
                          type: object
                          properties:
                            flags:
                              type: array
                              items:
                                type: object
                                properties:
                                  label:
                                    type: string
                                  tone:
                                    type: string
                                    enum:
                                      - critical
                                      - needsAction
                                      - info
                                required:
                                  - label
                                  - tone
                                additionalProperties: false
                          required:
                            - flags
                          additionalProperties: false
                        nextAction:
                          type: object
                          properties:
                            label:
                              type: string
                          required:
                            - label
                          additionalProperties: false
                      required:
                        - advertiserId
                        - name
                        - initials
                        - managed
                        - tracked
                        - campaignCount
                        - resumableDraft
                      additionalProperties: false
                  currentAdvertiserId:
                    type: string
                required:
                  - portfolio
                  - advertisers
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}:
    get:
      operationId: getAdvertiser
      summary: Get advertiser
      description: Get a single advertiser by ID. Always returns full brand details including the ADCP manifest.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: Get advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateAdvertiser
      summary: Update advertiser
      description: Update an existing advertiser.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdvertiserBody'
      responses:
        '200':
          description: Update advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteAdvertiser
      summary: Delete advertiser
      description: Delete (archive) an advertiser.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/restore:
    post:
      operationId: restoreAdvertiser
      summary: Restore advertiser
      description: Restore a previously deleted (archived) advertiser, making it active again.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: Restore advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No archived advertiser with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/data-delivery-credentials/{name}/validate:
    post:
      operationId: revalidateDataDeliveryCredential
      summary: Revalidate data delivery credential
      description: >-
        Re-runs the destination Probe for a supported object-storage credential and returns the updated record with a
        fresh status (VALIDATED or FAILED). Use after fixing a buyer-side destination access issue (e.g., re-granting
        GCS bucket IAM) without otherwise editing the credential.
      tags:
        - Advertisers
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Advertiser ID (numeric, as a string).
            type: string
            minLength: 1
          required: true
          description: Advertiser ID (numeric, as a string).
        - in: path
          name: name
          schema:
            description: Credential name (unique per advertiser).
            type: string
            minLength: 1
          required: true
          description: Credential name (unique per advertiser).
      responses:
        '200':
          description: Revalidate data delivery credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevalidateDataDeliveryCredentialResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/creative/model-credentials:
    get:
      operationId: listCreativeModelCredentials
      summary: List generation-provider keys for an advertiser
      description: >-
        List the buyer's generation-provider keys usable for this advertiser — its assigned keys plus the customer's
        all-accounts keys — each carrying a label, assignment, status, a masked key hint (never the raw key), and
        `effective: true` on the one auto-selected for its provider. Gated behind buyer-creative-v2 and
        buyer-generative-creative.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      responses:
        '200':
          description: List generation-provider keys for an advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvertiserModelCredentialList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Feature not enabled for this account (buyer-creative-v2 or buyer-generative-creative is off).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: connectCreativeModelCredential
      summary: Connect a generation-provider key for an advertiser
      description: >-
        Store a buyer generation-provider API key assigned to this advertiser so generation runs on the buyer's own
        account. The raw key is held in the secret manager; only a reference and a masked hint are persisted. Gated
        behind buyer-creative-v2 and buyer-generative-creative.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: advertiserId
          schema:
            description: Unique identifier for the advertiser
            example: '12345'
            type: string
            minLength: 1
          required: true
          description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectBuyerModelCredentialBody'
      responses:
        '200':
          description: Connect a generation-provider key for an advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerModelCredential'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Feature not enabled for this account (buyer-creative-v2 or buyer-generative-creative is off).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /creative/model-credentials/{id}:
    patch:
      operationId: updateCreativeModelCredential
      summary: Update or rotate a generation-provider key
      description: >-
        Update a buyer generation-provider credential. Supplying `apiKey` atomically rotates only the stored secret
        while preserving the credential's label, advertiser assignments, and default status unless those fields are also
        explicitly changed. Gated behind buyer-creative-v2 and buyer-generative-creative.
      tags:
        - Creatives
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: string
            pattern: ^[1-9]\d*$
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                apiKey:
                  type: string
                  minLength: 1
                label:
                  type: string
                  minLength: 1
                  maxLength: 120
                advertiserIds:
                  type: array
                  items:
                    type: integer
                    maximum: 9007199254740991
                    minimum: 1
                isDefault:
                  type: boolean
      responses:
        '200':
          description: Update or rotate a generation-provider key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerModelCredential'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Feature not enabled for this account (buyer-creative-v2 or buyer-generative-creative is off).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No active model credential with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /brands/resolve:
    post:
      operationId: resolveBuyerBrand
      summary: Resolve a brand profile
      description: >-
        Resolve a buyer domain to a brand-confirmation card ("here is how we see you"). Resolve-only — no persistence;
        the buyer confirms the card and the advertiser-create flow persists it. Always returns 200: resolved=true with
        the brand name, logo, and ADCP manifest when found; resolved=false with a builderUrl when no profile exists. A
        resolved card may carry a warning when the profile was built from the website and is unverified — review before
        saving.
      tags:
        - Brands
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveBrandBody'
      responses:
        '200':
          description: Resolve a brand profile
     

# --- truncated at 32 KB (3788 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scope3/refs/heads/main/openapi/_original/scope3-buyer-openapi-original.yml