> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluate a media buy against acceptance policy

> Classify whether a pending media buy is definitely on policy, definitely not on policy, or needs human approval. The evaluator only recommends automatic approval when the buy references quoted storefront products, contains advertiser evidence, and does not match active acceptance-policy review or block rules. This endpoint does not record a decision.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml post /media-buy-approvals/{mediaBuyId}/evaluate
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.interchange.io/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.interchange.io/api/v2/storefront
    description: Production server
security: []
tags:
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Storefront
    description: Manage storefront and inventory sources
  - name: Storefront Agents
    description: List and manage registered sales, signals, and outcomes agents
  - name: Storefront Activity
    description: Audit log of configuration and inventory changes on the storefront
  - name: Storefront Billing
    description: Payout bank details and billing configuration for storefronts
  - name: AI Usage
    description: Storefront AI token usage visibility by model
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /media-buy-approvals/{mediaBuyId}/evaluate:
    post:
      tags:
        - Storefront
      summary: Evaluate a media buy against acceptance policy
      description: >-
        Classify whether a pending media buy is definitely on policy, definitely
        not on policy, or needs human approval. The evaluator only recommends
        automatic approval when the buy references quoted storefront products,
        contains advertiser evidence, and does not match active
        acceptance-policy review or block rules. This endpoint does not record a
        decision.
      operationId: evaluatePendingMediaBuy
      parameters:
        - in: path
          name: mediaBuyId
          schema:
            description: Buyer-supplied media buy identifier (AdCP `media_buy_id`).
            type: string
            minLength: 1
          required: true
          description: Buyer-supplied media buy identifier (AdCP `media_buy_id`).
      responses:
        '200':
          description: Evaluate a media buy against acceptance policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaBuyApprovalEvaluationResponse'
        '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'
      security:
        - bearerAuth: []
components:
  schemas:
    MediaBuyApprovalEvaluationResponse:
      description: >-
        Policy evaluation for a storefront media-buy approval queue entry. This
        classifies whether the buy is auto-approval eligible or should escalate
        to a human.
      type: object
      properties:
        mediaBuyId:
          description: Buyer-supplied media buy identifier that was evaluated.
          type: string
        evaluatorId:
          description: Stable evaluator implementation id.
          type: string
        evaluatorVersion:
          description: Evaluator implementation version.
          type: string
        policyDecision:
          description: >-
            `definitely_on_policy` means this buy is eligible for automatic
            approval. `needs_human_approval` is the safe escalation default.
            `definitely_not_on_policy` means the payload clearly conflicts with
            acceptance policy, but the recommended action can still be
            escalation rather than automatic rejection because the storefront
            may have already quoted the product.
          allOf:
            - $ref: '#/components/schemas/StorefrontApprovalPolicyDecision'
        recommendation:
          description: >-
            Recommended workflow action. `auto_approve` = definitely on policy,
            eligible to forward without review. `escalate_to_human` = the safe
            default, queue for an operator. `auto_reject` = the buy clearly
            violates an explicit, deterministically-matched acceptance-policy
            rule (e.g. a category the operator wrote in unambiguous block
            language); it is decision-support only — the gate still queues these
            to a human unless an operator has opted a storefront into live
            auto-reject. LLM-judged conflicts never yield `auto_reject`; they
            escalate.
          type: string
          enum:
            - auto_approve
            - escalate_to_human
            - auto_reject
        rejectionReason:
          description: >-
            When `recommendation` is `auto_reject`, an evaluator-generated
            explanation naming the acceptance-policy terms the buy matched
            (drawn from the operator's policy). Null otherwise.
          nullable: true
          type: string
        summary:
          description: Short evaluator summary.
          type: string
        checks:
          description: >-
            Individual policy, advertiser, and quoted-product checks supporting
            the recommendation.
          type: array
          items:
            type: object
            properties:
              evaluator_id:
                type: string
                minLength: 1
              evaluator_version:
                type: string
                minLength: 1
              category:
                type: string
                enum:
                  - readiness
                  - asset
                  - brand_brief
                  - format_seller
                  - policy_safety
                  - performance
              code:
                type: string
              label:
                type: string
              stage:
                type: string
                enum:
                  - generation
                  - selection
                  - refinement
                  - finalization
                  - adaptation
                  - approval
                  - live_learning
                  - draft
                  - final
              status:
                type: string
                enum:
                  - pass
                  - warn
                  - fail
              detail:
                type: string
              severity:
                type: string
                enum:
                  - hard
                  - soft
              blocking:
                type: boolean
              confidence:
                type: number
                minimum: 0
                maximum: 1
              evidence_refs:
                type: array
                items:
                  type: string
                  minLength: 1
              remediation:
                type: string
                maxLength: 1000
            required:
              - label
              - status
              - detail
            additionalProperties: false
      required:
        - mediaBuyId
        - evaluatorId
        - evaluatorVersion
        - policyDecision
        - recommendation
        - rejectionReason
        - summary
        - checks
      additionalProperties: false
    ErrorResponse:
      description: Standard error response
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
    StorefrontApprovalPolicyDecision:
      description: >-
        Policy confidence for storefront approval automation.
        `definitely_on_policy` is eligible for automatic approval,
        `definitely_not_on_policy` is a clear policy conflict, and
        `needs_human_approval` is the safe default for ambiguous or incomplete
        evidence.
      type: string
      enum:
        - definitely_on_policy
        - definitely_not_on_policy
        - needs_human_approval
    ApiError:
      description: Structured error object
      type: object
      properties:
        code:
          description: Machine-readable error code
          type: string
        message:
          description: Human-readable error message
          type: string
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````