Andrew’s Freebies Entitlements API

openapi: 3.2.0
info:
  title: Andrew’s Freebies Entitlements 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: Entitlements
paths:
  /api/v1/entitlements:
    get:
      operationId: searchEntitlements
      summary: Search conditional benefits, bonuses, perks, and eligibility programs
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Natural-language relationship, provider, benefit, or requirement query.
      - name: focus
        in: query
        schema:
          type: string
          enum:
          - redeemable-value
        description: Restrict results to cash, statement credits, bank and card bonuses, shopping rewards, coupons, rebates, tax credits, grants, and loyalty perks.
      - name: kind
        in: query
        schema:
          type: string
          enum:
          - bank-account-bonus
          - benefit-tracker
          - benefits-counseling
          - business-support
          - card-linked-offer
          - community-benefit
          - community-program
          - consumer-complaint
          - credit-card-welcome-bonus
          - cultural-access
          - customer-loyalty-perk
          - deal-directory
          - education-program
          - eligibility-directory
          - employment-program
          - family-support
          - free-admission
          - government-benefit
          - grant
          - health-coverage
          - health-locator
          - hotline
          - housing-assistance
          - insurance-benefit
          - library-access
          - library-benefit
          - public-resource
          - rebate
          - rights-advocacy
          - rights-enforcement
          - school-program
          - shopping-portal
          - tax-credit
        description: Primary entitlement archetype. Definitions, inclusions, exclusions, and usage instructions are published at /api/v1/taxonomy.
      - name: cost_basis
        in: query
        schema:
          type: string
          enum:
          - no-cost
          - no-additional-cost
          - discounted
          - subsidized
          - requires-purchase
          - requires-spend
          - requires-deposit
          - paid-membership
          - varies
        description: Financial condition attached to access. 'varies' means provider- or eligibility-dependent, not universally free; inspect access.fees and access.requirements.
      - name: personalized
        in: query
        schema:
          type: boolean
      - name: status
        in: query
        schema:
          type: string
          enum:
          - verified
          - source-found
          - directory-listed
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: A paginated list of matching entitlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementSearchResponse'
      tags:
      - Entitlements
  /api/v1/entitlements/{slug}:
    get:
      operationId: getEntitlement
      summary: Get one conditional-entitlement record
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Entitlement record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entitlement'
        '404':
          description: Not found
      tags:
      - Entitlements
components:
  schemas:
    VerificationReadiness:
      type: object
      required:
      - status
      - latest_outcome
      - latest_checked_at
      - interpretation
      properties:
        status:
          type: string
          enum:
          - audit-confirmed-exact
          - audit-confirmed-partial
          - audit-inconclusive
          - audit-warning
          - not-audited
        latest_outcome:
          oneOf:
          - $ref: '#/components/schemas/VerificationOutcome'
          - type: 'null'
        latest_checked_at:
          type:
          - string
          - 'null'
          format: date-time
        interpretation:
          type: string
          description: Factual guidance for using the latest audit without treating an inconclusive fetch as expiration.
    Entitlement:
      type: object
      required:
      - id
      - name
      - provider
      - entitlement_type
      - entitlement_type_label
      - entitlement_type_context
      - benefit
      - discovery
      - access
      - status
      - source
      - taxonomy
      - verification_readiness
      - action_url
      - official_action
      properties:
        id:
          type: string
        name:
          type: string
        provider:
          type: string
        entitlement_type:
          type: string
          enum:
          - bank-account-bonus
          - benefit-tracker
          - benefits-counseling
          - business-support
          - card-linked-offer
          - community-benefit
          - community-program
          - consumer-complaint
          - credit-card-welcome-bonus
          - cultural-access
          - customer-loyalty-perk
          - deal-directory
          - education-program
          - eligibility-directory
          - employment-program
          - family-support
          - free-admission
          - government-benefit
          - grant
          - health-coverage
          - health-locator
          - hotline
          - housing-assistance
          - insurance-benefit
          - library-access
          - library-benefit
          - public-resource
          - rebate
          - rights-advocacy
          - rights-enforcement
          - school-program
          - shopping-portal
          - tax-credit
          description: Primary record archetype; this value does not establish price or individual eligibility.
        entitlement_type_label:
          type: string
        entitlement_type_context:
          type: object
          properties:
            definition:
              type: string
            domain:
              type: string
            archetype:
              type: string
            agent_instruction:
              type: string
        summary:
          type: string
        benefit:
          type: object
          properties:
            description:
              type: string
            estimated_value_usd:
              type:
              - number
              - 'null'
        discovery:
          type: object
          properties:
            focus:
              type: string
              enum:
              - redeemable-value
              - public-service
            has_estimated_dollar_value:
              type: boolean
        access:
          type: object
          properties:
            relationships:
              type: array
              items:
                type: string
            requirements:
              type: string
            activation:
              type: string
            cost_basis:
              type: string
              enum:
              - no-cost
              - no-additional-cost
              - discounted
              - subsidized
              - requires-purchase
              - requires-spend
              - requires-deposit
              - paid-membership
              - varies
              description: Normalized financial condition; read cost_basis_context and fees before describing the benefit as free.
            cost_basis_label:
              type: string
            cost_basis_context:
              type: object
              properties:
                classification:
                  type: string
                definition:
                  type: string
                agent_instruction:
                  type: string
                variation_patterns:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                does_not_mean:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
            fees:
              type: string
            personalized:
              type: boolean
            regions:
              type: array
              items:
                type: string
            expires:
              type:
              - string
              - 'null'
        parent:
          type:
          - object
          - 'null'
          description: Parent entitlement when this record exposes one independently searchable benefit from a broader access relationship.
          properties:
            id:
              type: string
            name:
              type: string
            relationship:
              type: string
              enum:
              - benefit-of
            web_url:
              type: string
        coverage:
          type:
          - object
          - 'null'
          properties:
            level:
              type: string
              enum:
              - national
              - state
              - local
            family:
              type: string
            jurisdiction:
              type: string
            maturity:
              type: string
              enum:
              - locator
              - direct
        status:
          type: string
        last_checked:
          type: string
          format: date
        verification_readiness:
          $ref: '#/components/schemas/VerificationReadiness'
        action_url:
          type:
          - string
          - 'null'
          format: uri
          description: Measured official-action path; null means the record is inspectable but must not be recommended for action.
        official_action:
          $ref: '#/components/schemas/OfficialActionState'
        claim_url:
          type: string
          format: uri
        source_url:
          type: string
          format: uri
        source:
          type: object
        taxonomy:
          type: object
          properties:
            version:
              type: string
            url:
              type: string
    EntitlementSearchResponse:
      type: object
      properties:
        count:
          type: integer
        returned:
          type: integer
        next_offset:
          type:
          - integer
          - 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Entitlement'
    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.
    OfficialActionState:
      type: object
      required:
      - allowed
      - status
      - reason
      properties:
        allowed:
          type: boolean
        status:
          type: string
          enum:
          - ready
          - source-navigation
          - withheld
        reason:
          type: string
          description: Instruction for whether an agent may recommend the official action path.
  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.'