distribution-tech Evidence API

openapi: 3.2.0
info:
  title: distribution Evidence API
  version: 1.29.0
  description: 'Your own distribution workspace for your agents and systems. Every endpoint takes an API key you create in the workspace (Developers) as Authorization: Bearer and returns exactly what the workspace shows you. Reads are GET. The writes (start a campaign, change its creators, set what its creators read, approve for a payment link) need a key with campaigns:write or plans:approve, an Idempotency-Key header, and act only inside the mandate your brand sets on the key in Developers: its maximum plan total, monthly cap, channels, whether it may sign, its expiry and the brand terms a person accepted for it. A request outside the mandate is refused before any spend with the limit and how much over. Approved creators on sale are listed by name with their X handle and profile link, before any purchase, and every creator on a plan line is named before payment; a creator who is not approved carries no handle in lists and profiles; not-reviewed, declined and paused creators are never listed (operator decisions 2026-10-08). What bookable means (DT-021): A creator is bookable (on sale) when all of these hold: our team approved the creator after review (verified and active); our review keeps the creator among those we sell, not flagged as an inactive account and not excluded; and at least one of the creator''s formats has a fresh price: a price at most 30 days old, or a price quoted by our team. Every surface counts bookable creators with this one rule (the Creators list''s priced, Market''s Bookable now, the Overview, the chat, creators_search priced and catalog.priced, GET /api/network/facts and the guest quote), so the same filter shows the same number. An approved creator who is not bookable is still listed, with price on request. Any valid key may send feedback (POST /feedback) when something fails, is missing or could be better; it reaches the team directly. The same reads and writes are tools on the MCP server at /api/mcp. Changelog: 2026-10-21 (1.29.0): a quote line carries review, the creator''s review state (Approved, Under review), on REST and MCP; vetting stays as a deprecated alias with the same value until 2026-11-20, so read review (DT-205). 2026-10-21 (1.28.0): every approved creator is named before purchase: its X handle and profile link (handle, url) on every creator read, GET /creators rows and creators_search (CreatorSummary now lists handle and url), GET /creators/{id} and creator_get, with its post links; and a plan names its creators before payment too: plan_quote lines carry creator.handle and creator.profile_url, and campaign_status line slots carry the @handle, whatever the order''s payment state. A creator who is not approved carries no handle in lists and profiles. 2026-10-21 (1.27.0): every campaign (list and status) and every line proposal carries brand_context_version, the version of your brand context (GET /brain) in force when it was created; it is frozen there, so editing the context later never changes it, and null means there was no context yet. 2026-10-21 (1.26.3): GET /creators and GET /creators/{id} refuse a query parameter they do not take (handle, for one) with 400 bad_request, details.problems naming it and details.accepted listing what they take, instead of ignoring it. A client that sends an extra parameter now gets 400 and must drop it. Over the daily creator-view limit, an id not opened today answers 429 daily_seen before it is looked up, so an id no creator has answers 429 too, not 404: the limit never reveals which ids exist (DT-324). 2026-10-21 (1.26.2): a creator read''s 429 daily_lists (the day''s 60 list calls, each GET /creators page or creators_search) and daily_reveals carry details.limit, and daily_lists says list calls, never creator views; both are described with the creator read limits (DT-337).'
servers:
- url: https://app.distribution.tech/api/v1
tags:
- name: Evidence
paths:
  /evidence:
    get:
      summary: Proof of each post a paid campaign put live
      description: 'Scope: evidence:read.'
      security:
      - apiKey:
        - evidence:read
      parameters:
      - name: campaign_id
        in: query
        required: false
        description: Only this campaign.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          headers:
            RateLimit-Limit:
              description: Requests one window allows for this key.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window closes; the next request after that opens a new one.
              schema:
                type: integer
            RateLimit-Policy:
              description: 'The limit and the window in seconds, e.g. 60;w=60. The window is fixed: it opens at the key''s first request after the last one closed (DT-271), so a burst across two windows can pass more than the limit in one rolling minute.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evidence'
        '400':
          description: 'A parameter is not valid: details.problems names each field and what it accepts.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No API key, an unknown one, or a revoked one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key does not have this endpoint's scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many requests for this key in the current minute (60); Retry-After and RateLimit-Reset say when to try again. On POST /campaigns and on POST /plans/current/lines when it starts a plan: the brand''s 3 new campaigns in 24 hours are used (details.reason daily_campaign_limit); details.resets_at and Retry-After say when the limit reopens, a rolling 24 hours from the first of them, not a calendar day; archiving or deleting a campaign does not give its slot back. On GET /creators and GET /creators/{id}: a creator read limit is used (details.reason per_minute, daily_lists, daily_reveals, daily_seen or locked). daily_seen is your workspace''s one pool of 300 creator views a day (300 different creators shown or opened since midnight UTC), shared by the app and every API key of the brand: details.scope workspace and details.limit 300; a creator already seen today, in the app or through any key, still opens and costs nothing. daily_lists is the day''s list calls (each GET /creators page or creators_search is one; details.limit, 60): it is counted apart from creator views, resets at midnight UTC, and Retry-After says when. daily_reveals is the day''s creator profiles opened (details.limit, 60). The other reasons are this key''s own limit (details.scope key) or the brand''s ceiling over all its keys (details.scope api).'
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit-Limit:
              description: Requests one window allows for this key.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window closes; the next request after that opens a new one.
              schema:
                type: integer
            RateLimit-Policy:
              description: 'The limit and the window in seconds, e.g. 60;w=60. The window is fixed: it opens at the key''s first request after the last one closed (DT-271), so a burst across two windows can pass more than the limit in one rolling minute.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'internal: the request failed on our side. Try again.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'unavailable: the service or this part of it is not reachable right now. Try again shortly.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Evidence
      operationId: getEvidence
      x-operation-id-source: derived
components:
  schemas:
    EvidenceItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        campaign_id:
          type: string
          format: uuid
        brief_id:
          type: string
          format: uuid
          deprecated: true
          x-sunset: '2026-11-10'
          description: 'Deprecated: the same id as campaign_id. Removed on 2026-11-10; read campaign_id.'
        campaign:
          type: string
        slot:
          type: string
        status:
          type: string
          enum:
          - live
          - completed
        status_label:
          type: string
        date:
          type: string
        proof_url:
          type:
          - string
          - 'null'
        published_at:
          type:
          - string
          - 'null'
          format: date-time
        disclosure:
          type:
          - string
          - 'null'
        still_up:
          oneOf:
          - type: 'null'
          - type: object
            properties:
              checked_at:
                type: string
                format: date-time
              views:
                type:
                - integer
                - 'null'
              line:
                type: string
            required:
            - checked_at
            - views
            - line
            additionalProperties: false
          description: The first metrics snapshot on or after published_at plus 7 days, the proof the post stayed up (brand terms 8.1). Null while there is none.
      required:
      - id
      - campaign_id
      - brief_id
      - campaign
      - slot
      - status
      - status_label
      - date
      - proof_url
      - published_at
      - disclosure
      - still_up
      additionalProperties: false
    Evidence:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceItem'
      required:
      - items
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - bad_request
              - filter_required
              - unauthorized
              - forbidden
              - not_found
              - method_not_allowed
              - rate_limited
              - unavailable
              - internal
              - mandate_refused
              - conflict
              - unprocessable
              - idempotency_conflict
              - in_progress
            message:
              type: string
            details:
              type: object
              description: 'Machine-readable facts. mandate_refused: reason (no_mandate, mandate_expired, channel_not_allowed, approval_not_allowed, terms_not_accepted, over_max_plan_total, over_monthly_cap, over_budget), limit_cents, requested_cents, over_by_cents, spent_cents, and escalate: true (take it to a person at the brand). conflict: reason; for over_budget on plan_add_creator or plan_swap_creator also budget_cents, remaining_cents (the room the plan had before the creator), price_cents and over_by_cents. unprocessable: problems, each a field and a message.'
          required:
          - code
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key from the workspace. Scopes: inventory:read (Network coverage for your audience), audience:read (Audience fit for a campaign or a profile), campaigns:read (Campaigns and where each stands), evidence:read (Proof of each paid post), results:read (Results of each paid post), brain:read (Your company context), creators:read (Approved creators on sale, by name, with price per format), campaigns:write (Start campaigns and change the creators on a plan, within its mandate), plans:approve (Sign a plan and get its payment link, within its mandate). Rate limit: 60 requests a minute per key.'