Andrew’s Freebies Outcomes API

openapi: 3.2.0
info:
  title: Andrew’s Freebies Outcomes 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: Outcomes
paths:
  /api/v1/outcomes:
    get:
      operationId: getOutcomeSummary
      summary: Get anonymous page usage, setup navigation, action opens, voluntary outcomes…
      description: Separates a measured ChatGPT plugin-page handoff from installation or tool use, Cloudflare-verified automated clients from spoofable user-agent claims, answer retrieval from crawlers, primary site-search demand from supplemental enrichment, filter, pagination, and browse requests, query-bearing demand signals, modern unattributed REST attempts, legacy preclassification REST and MCP activity, attributed MCP agent discovery, unidentified initialization traffic, known registry/probe automation, modern session-linked tool use, official action opens, and voluntary outcomes. REST search demand admits attributed AI or AI-referral queries plus unverified api-query and legacy rows; verified automation and site-interface calls are reported as excluded rather than relabeled as external API demand. Otherwise-unknown Cloudflare-verified automation and recognizable but unverified agent labels on arbitrary paths are excluded from human page-hit, unattributed API-demand, referral, setup-open, and qualified-handoff totals. A qualified AI-agent handoff requires Cloudflare verification of the recognized user-agent. Modern downstream MCP metrics require the request class stored at event time; older tool rows remain visible without inferring downstream use or attribution. New handoffs and outcome reports snapshot record corpus and verification readiness while current catalog state remains a separate projection, so later corrections cannot rewrite historical quality. The actionable-handoff safety window starts at the first retained production snapshot proving both the audit gate and provenance-aware initiator classifier at 100%, and keeps earlier events as historical context. A browser-shaped user agent without a same-origin referrer is unidentified rather than qualified as browser navigation. Known labeled validation traffic is excluded. It reports normalized presentation sources and derived initiator classes without visitor identifiers or raw user agents. Setup-page opens are not installations, action opens are not completions, and outcome reports are unverified; none are cohort conversion rates.
      parameters:
      - name: days
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 365
          default: 30
      responses:
        '200':
          description: Anonymous page usage, setup navigation, action opens, voluntary outcomes, demand, and agent-distribution stages
        '400':
          description: Invalid period
        '503':
          description: Outcome telemetry unavailable
      tags:
      - Outcomes
    post:
      operationId: reportOfferOutcome
      summary: Record one anonymous actionable-offer outcome
      description: Accepts one worked, ineligible, or terms-differed selection for a current trial or redeemable-savings record. Public-benefit records are excluded. The report contains no free text or visitor identifier and is not linked to a prior handoff or provider completion record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutcomeFeedbackInput'
      responses:
        '201':
          description: Anonymous voluntary report recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutcomeFeedbackReceipt'
        '400':
          description: Invalid report or non-actionable public-benefit record
        '404':
          description: Catalog record not found
        '413':
          description: Request body too large
        '503':
          description: Outcome telemetry unavailable
      tags:
      - Outcomes
components:
  schemas:
    OutcomeFeedbackInput:
      type: object
      additionalProperties: false
      required:
      - record_type
      - record_id
      - outcome
      properties:
        record_type:
          type: string
          enum:
          - trial
          - entitlement
        record_id:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,198}[a-z0-9])?$
        outcome:
          type: string
          enum:
          - worked
          - ineligible
          - terms-differed
        source_context:
          type: string
          description: Optional normalized presentation source. Unrecognized values become api.
    OutcomeFeedbackReceipt:
      type: object
      required:
      - api_version
      - recorded
      - outcome
      - record
      - interpretation
      properties:
        api_version:
          type: string
          const: '1.24'
        recorded:
          type: boolean
          const: true
        outcome:
          type: string
          enum:
          - worked
          - ineligible
          - terms-differed
        record:
          type: object
          required:
          - record_type
          - record_id
          - corpus
          properties:
            record_type:
              type: string
              enum:
              - trial
              - entitlement
            record_id:
              type: string
            corpus:
              type: string
              enum:
              - trial
              - redeemable-savings
        interpretation:
          type: string
  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.'