besot Programs API

openapi: 3.2.0
info:
  title: BestAffiliatePrograms.cc Programs API
  version: 1.0.0
  description: 'A read-only, cite-friendly API over a verified directory of affiliate programs, each compared by network, published commission, cookie window, how it pays, requirements, and a MODELLED value per referral. Every figure traces to the program''s own affiliate page or a public network or aggregator listing. Programs whose terms were read only from CJ''s advertiser records, which CJ shows only to its publishers, are listed on the site''s program pages but left out of the dataset, the API and the MCP server: CJ''s API terms restrict redistributing its data. Requires an API key (a free tier with a daily limit, or Pro for volume): send it as ''Authorization: Bearer ''. Get a key at https://bestaffiliateprograms.cc/developers. The bulk dataset (https://bestaffiliateprograms.cc/affiliate-programs.json) and the MCP server (https://bestaffiliateprograms.cc/v1/mcp) are open and keyless.'
  contact:
    url: https://bestaffiliateprograms.cc/developers
  license:
    name: Free to cite with attribution
    url: https://bestaffiliateprograms.cc/data#license
servers:
- url: https://bestaffiliateprograms.cc/v1
  description: Production
security:
- ApiKeyBearer: []
- ApiKeyHeader: []
tags:
- name: Programs
paths:
  /programs:
    get:
      operationId: listPrograms
      summary: List affiliate programs (filterable, paginated)
      parameters:
      - name: category
        in: query
        schema:
          type: string
        description: Filter by category key (see /categories).
      - name: network
        in: query
        schema:
          type: string
        description: Filter by network bucket key (see /networks) or its display label; both work.
      - name: recurring
        in: query
        schema:
          type: boolean
        description: Only recurring (true) or one-time (false) programs.
      - name: confidence
        in: query
        schema:
          type: string
          enum:
          - confirmed
          - network
      - name: min_value
        in: query
        schema:
          type: number
        description: Minimum modelled value per referral (USD).
      - name: q
        in: query
        schema:
          type: string
        description: 'What the programs are for, in plain words: a niche, product or audience (''vpn'', ''skincare'', ''pet supplements for a dog blog'', ''recurring saas''). Read and ranked exactly as the site''s own search reads it; a topic with a curated niche list is answered by that list. The response''s `interpretation` says how the query was read. When set, results are the matches, best first, and the sort parameter is ignored.'
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - value
          - name
          - cookie
          default: value
        description: Ordering when q is absent. Ignored while q is set (search results are relevance-ordered).
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: A page of programs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  count:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
                  interpretation:
                    type: string
                    nullable: true
                    description: How q was read ("VPN programs, by value per referral"); null without q, or when no reading matched and keyword relevance answered.
                  next:
                    type: string
                    nullable: true
                  programs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Program'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Programs
  /programs/{slug}:
    get:
      operationId: getProgram
      summary: Get one affiliate program by slug
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The program.
          content:
            application/json:
              schema:
                type: object
                properties:
                  program:
                    $ref: '#/components/schemas/Program'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No program with that slug (error 'not_found'), or a program the site lists whose terms come only from CJ's records (error 'not_in_api', with `url` = its page).
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Programs
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
    RateLimited:
      description: Daily request limit reached for the plan. See the X-RateLimit-* headers and Retry-After.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
  schemas:
    Program:
      type: object
      properties:
        slug:
          type: string
        name:
          type: string
        category:
          type: string
        categoryLabel:
          type: string
        network:
          type: string
          description: Human display label for the primary affiliate network.
        networkKey:
          type: string
          description: Canonical bucket key to pass back as ?network=... (round-trips with the filter and /networks).
        homepage:
          type: string
          nullable: true
        applyUrl:
          type: string
          description: Where to apply to the program.
        commission:
          type: string
          description: The published commission, verbatim.
        cookie:
          type: string
          description: The tracking/cookie window, or an honest 'not posted'.
        recurring:
          type: boolean
        howEarned:
          type: string
          nullable: true
        requirements:
          type: string
        confidence:
          type: string
          enum:
          - confirmed
          - network
          description: confirmed = read on the program's own affiliate page; network = read on a network/aggregator listing.
        modelledValuePerReferralUsd:
          type: number
          description: MODELLED conservative value of one paid referral from published terms. NOT a guaranteed payout.
        lastVerified:
          type: string
          format: date
        sources:
          type: array
          items:
            type: string
        url:
          type: string
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: Your API key as a Bearer token. Get a free key at /developers.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API key (alternative to the Authorization header).