Andrew’s Freebies Verification API

openapi: 3.2.0
info:
  title: Andrew’s Freebies Verification API
  version: 2.6.0
  description: Open access to one preferred search for evidence-backed free trials and U.S. savings. Matching answer guides are returned separately from normalized records only while their lifecycle, copy fingerprint, and supporting-record set remain current. The broader public-benefit corpus and live licensed repositories are available through explicit scopes. Public reads and anonymous actionable-offer outcome reports require no API key; verification ingestion is operator-authenticated. Qualified AI-agent handoffs require Cloudflare verification of the recognized user-agent so spoofed agent labels cannot become adoption evidence. Outcomes separate primary site search from supplemental enrichment, filtering, pagination, and browse resets.
servers:
- url: https://andrewsfreebies.com
tags:
- name: Verification
paths:
  /api/v1/verification:
    get:
      operationId: getVerificationHistory
      summary: Get one record's field-level verification history
      description: Returns append-only verification events and run metadata. Catalog status and field-level audit outcome are separate concepts. Audits never remove, hide, or modify catalog records.
      parameters:
      - name: record_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 200
        description: Exact trial or entitlement id.
      - name: record_type
        in: query
        schema:
          type: string
          enum:
          - trial
          - entitlement
        description: Optional when the id uniquely resolves.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Append-only audit history for the record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationHistory'
        '400':
          description: Invalid filter
        '404':
          description: Catalog record not found
        '503':
          description: Verification ledger unavailable
      tags:
      - Verification
    post:
      operationId: ingestVerificationRun
      summary: Append an operator verification run
      description: Operator-only ingestion for up to 100 field-level audit events. This append-only operation does not mutate or remove catalog records. blocked, fetch-error, not-found, and unknown preserve uncertainty and do not establish expiration.
      security:
      - operatorToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationIngestInput'
      responses:
        '201':
          description: Verification events appended; catalog records unchanged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationIngestReceipt'
        '400':
          description: Invalid run or event payload
        '401':
          description: Missing or invalid operator bearer token
        '404':
          description: One or more catalog records not found
        '503':
          description: Verification ledger unavailable
      tags:
      - Verification
components:
  schemas:
    VerificationIngestInput:
      type: object
      required:
      - run
      - verification_events
      properties:
        schema_version:
          type: string
          maxLength: 32
          default: '1.0'
        generated_at:
          type: string
          format: date-time
          description: Defaults to the ingestion time.
        run:
          $ref: '#/components/schemas/VerificationRunInput'
        verification_events:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/VerificationEventInput'
    VerificationHistory:
      type: object
      required:
      - api_version
      - record
      - count
      - items
      - append_only
      properties:
        api_version:
          type: string
          const: '1.9'
        record:
          type: object
          properties:
            record_id:
              type: string
            record_type:
              type: string
              enum:
              - trial
              - entitlement
            name:
              type: string
            web_url:
              type: string
        count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/VerificationEvent'
        append_only:
          type: boolean
          const: true
    VerificationEvent:
      allOf:
      - $ref: '#/components/schemas/VerificationEventInput'
      - type: object
        properties:
          id:
            type: string
            format: uuid
          run_id:
            type: string
            format: uuid
          created_at:
            type: string
            format: date-time
          run:
            type: object
            properties:
              schema_version:
                type: string
              generated_at:
                type: string
                format: date-time
              method:
                type: string
              verifier:
                type:
                - string
                - 'null'
              started_at:
                type: string
                format: date-time
              completed_at:
                type: string
                format: date-time
    VerificationRunInput:
      type: object
      required:
      - method
      properties:
        method:
          type: string
          maxLength: 100
        verifier:
          type: string
          maxLength: 200
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    VerificationOutcome:
      type: string
      enum:
      - confirmed-exact
      - confirmed-partial
      - terms-changed
      - explicitly-expired
      - moved
      - blocked
      - fetch-error
      - not-found
      - unknown
      description: Conservative field-level audit result. blocked, fetch-error, not-found, and unknown do not establish expiration.
    VerificationIngestReceipt:
      type: object
      required:
      - api_version
      - run
      - accepted
      - events
      - catalog_records_unchanged
      properties:
        api_version:
          type: string
          const: '1.9'
        run:
          type: object
        accepted:
          type: integer
        events:
          type: array
          items:
            $ref: '#/components/schemas/VerificationEvent'
        catalog_records_unchanged:
          type: boolean
          const: true
    VerificationEventInput:
      type: object
      required:
      - record_id
      - record_type
      - url
      - url_role
      - outcome
      - url_health
      - offer_existence
      - terms_match
      - redemption_path
      - evidence_quality
      - freshness
      properties:
        record_id:
          type: string
          maxLength: 200
        record_type:
          type: string
          enum:
          - trial
          - entitlement
        category:
          type: string
          maxLength: 120
          description: Optional; when present it must match the canonical record category.
        url:
          type: string
          format: uri
          maxLength: 2048
        url_role:
          type: string
          maxLength: 80
        checked_at:
          type: string
          format: date-time
          description: Defaults to generated_at.
        method:
          type: string
          maxLength: 100
          description: Defaults to run.method.
        outcome:
          $ref: '#/components/schemas/VerificationOutcome'
        content_hash:
          type: string
          maxLength: 256
        evidence_excerpt:
          type: string
          maxLength: 2000
        matched_fields:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 100
        unmatched_fields:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 100
        url_health:
          type: object
          description: Structured status, redirect, and reachability observations.
          additionalProperties: true
        offer_existence:
          type: object
          description: Structured evidence for whether the provider currently describes the offer.
          additionalProperties: true
        terms_match:
          type: object
          description: Matched, unmatched, and contradicted normalized fields.
          additionalProperties: true
        redemption_path:
          type: object
          description: Structured activation, application, or claim-path result.
          additionalProperties: true
        evidence_quality:
          type: object
          description: Evidence ownership, authority, and sufficiency.
          additionalProperties: true
        freshness:
          type: object
          description: Audit age and next-check scheduling fields.
          additionalProperties: true
  securitySchemes:
    operatorToken:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: Operator credential for verification-run ingestion. The credential value is never returned by the API.
externalDocs:
  description: Human-readable agent integration guide
  url: https://andrewsfreebies.com/agents
x-agent-discovery:
  api_catalog: https://andrewsfreebies.com/.well-known/api-catalog
  mcp_server: https://andrewsfreebies.com/api/mcp
  public_benefits_plugin_mcp: https://andrewsfreebies.com/api/mcp/public-benefits
  mcp_server_card: https://andrewsfreebies.com/.well-known/mcp/server-card.json
  llms: https://andrewsfreebies.com/llms.txt
  authentication: https://andrewsfreebies.com/auth.md
  markdown: 'Send Accept: text/markdown to any human-readable page or append /index.md to its canonical path.'