Andrew’s Freebies Flags API

openapi: 3.2.0
info:
  title: Andrew’s Freebies Flags 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: Flags
paths:
  /api/v1/flags:
    get:
      operationId: listDealFlags
      summary: List expiration and accuracy reports
      description: With record_id, returns the append-only report history for one catalog record. Without record_id, returns records with open review signals. Reports never remove or alter catalog records.
      parameters:
      - name: record_id
        in: query
        schema:
          type: string
          maxLength: 200
      - name: record_type
        in: query
        schema:
          type: string
          enum:
          - trial
          - entitlement
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      responses:
        '200':
          description: Report history or the open review queue
        '400':
          description: Invalid filter
        '404':
          description: Catalog record not found
        '503':
          description: Ledger unavailable
      tags:
      - Flags
    post:
      operationId: flagDeal
      summary: Append a report about an expired or inaccurate deal
      description: Creates an append-only review signal. The source trial or entitlement remains unchanged and searchable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealFlagInput'
      responses:
        '201':
          description: Report recorded without changing the catalog record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealFlagReceipt'
        '400':
          description: Invalid report
        '404':
          description: Catalog record not found
        '503':
          description: Ledger unavailable
      tags:
      - Flags
components:
  schemas:
    DealFlagReceipt:
      type: object
      required:
      - api_version
      - flag
      - record
      - original_record_unchanged
      - review_status
      properties:
        api_version:
          type: string
          const: '1.9'
        flag:
          $ref: '#/components/schemas/DealFlag'
        record:
          type: object
          properties:
            record_type:
              type: string
              enum:
              - trial
              - entitlement
            record_id:
              type: string
            name:
              type: string
            web_url:
              type: string
        original_record_unchanged:
          type: boolean
          const: true
        review_status:
          type: string
          const: open
    DealFlag:
      type: object
      required:
      - id
      - record_type
      - record_id
      - reason
      - status
      - created_at
      properties:
        id:
          type: integer
        record_type:
          type: string
          enum:
          - trial
          - entitlement
        record_id:
          type: string
        reason:
          type: string
          enum:
          - expired
          - unavailable
          - terms-changed
          - incorrect
        evidence_url:
          type:
          - string
          - 'null'
          format: uri
        note:
          type:
          - string
          - 'null'
        reporter:
          type:
          - string
          - 'null'
        status:
          type: string
          const: open
        created_at:
          type: string
          format: date-time
    DealFlagInput:
      type: object
      required:
      - record_id
      additionalProperties: false
      properties:
        record_id:
          type: string
          maxLength: 200
          description: Exact id returned by an Andrew’s Freebies search or record endpoint.
        record_type:
          type: string
          enum:
          - trial
          - entitlement
          description: Optional when the id uniquely resolves.
        reason:
          type: string
          enum:
          - expired
          - unavailable
          - terms-changed
          - incorrect
          default: expired
        evidence_url:
          type: string
          format: uri
          maxLength: 2048
        note:
          type: string
          maxLength: 1000
        reporter:
          type: string
          maxLength: 120
  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.'