{"openapi":"3.1.0","info":{"title":"Andrew’s Freebies API","version":"1.9.0","description":"Open access to one unified tool search across normalized free offers and live licensed repositories, plus redeemable economic value, public services, conditional entitlements, append-only field-level verification, freshness coverage, and non-destructive expiration reports. Public reads require no API key; verification ingestion is operator-authenticated."},"servers":[{"url":"https://andrewsfreebies.com"}],"paths":{"/api/v1/trials":{"get":{"operationId":"searchTrials","summary":"Search free trials","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Natural-language capability or provider query."},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"card","in":"query","schema":{"type":"string","enum":["no-card"]}},{"name":"offer_type","in":"query","schema":{"type":"string","enum":["free-trial","free-plan","money-back-guarantee","promotional-offer","directory-listing"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["verified","source-found","conditional","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 trials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}}}}},"/api/v1/trials/{slug}":{"get":{"operationId":"getTrial","summary":"Get one free-trial record","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trial record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trial"}}}},"404":{"description":"Not found"}}}},"/api/v1/search":{"get":{"operationId":"searchTools","summary":"Search every tool source at once","description":"Returns one ranked list combining curated Andrew’s Freebies offers and live public, non-archived GitHub repositories with a detected SPDX license. Every item retains result_type and result_source provenance. Repository code can be free while hosting, deployment, support, or connected services still cost money.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":160},"description":"Natural-language purpose, such as 'edit PDFs' or 'self-hosted password manager'."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Optional filter applied to curated Andrew’s Freebies offers."},{"name":"card","in":"query","schema":{"type":"string","enum":["no-card"]},"description":"Optional filter applied to curated Andrew’s Freebies offers."},{"name":"offer_type","in":"query","schema":{"type":"string","enum":["free-trial","free-plan","money-back-guarantee","promotional-offer","directory-listing"]},"description":"Optional filter applied to curated Andrew’s Freebies offers."},{"name":"status","in":"query","schema":{"type":"string","enum":["verified","source-found","conditional","directory-listed"]},"description":"Optional filter applied to curated Andrew’s Freebies offers."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":12}}],"responses":{"200":{"description":"One ranked result list across the catalog and live licensed repositories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSearchResponse"}}}},"400":{"description":"Missing or too-short query"}}}},"/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"}}}}}}},"/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"}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"List trial categories and entitlement taxonomy facets","responses":{"200":{"description":"Trial categories plus fully defined entitlement types and cost bases with record counts"}}}},"/api/v1/taxonomy":{"get":{"operationId":"getEntitlementTaxonomy","summary":"Get the canonical entitlement taxonomy","responses":{"200":{"description":"Entitlement taxonomy 1.0: axes, type definitions, cost semantics, examples, and agent instructions"}}}},"/api/v1/sources":{"get":{"operationId":"listSources","summary":"Get source coverage and known crawl limitations","responses":{"200":{"description":"Source inventory, raw counts, deduplication totals, and limitations"}}}},"/api/v1/coverage":{"get":{"operationId":"getPublicServiceCoverage","summary":"Get the measurable U.S. public-service coverage ledger","responses":{"200":{"description":"National, state, and local coverage targets, current counts, family gaps, and quality gates"}}}},"/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"}}},"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"}}}},"/api/v1/freshness":{"get":{"operationId":"getFreshness","summary":"Get latest verification state and sweep coverage","description":"Returns the latest audit event per record, total/checked/unchecked coverage, outcome counts, and verification-age boundaries. The goal is 100% attempted on schedule, not forced confirmation.","parameters":[{"name":"record_type","in":"query","schema":{"type":"string","enum":["trial","entitlement"]}},{"name":"outcome","in":"query","schema":{"$ref":"#/components/schemas/VerificationOutcome"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Latest-state freshness projection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreshnessResponse"}}}},"400":{"description":"Invalid filter"},"503":{"description":"Verification ledger unavailable"}}}},"/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"}}},"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"}}}}},"components":{"securitySchemes":{"operatorToken":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Operator credential for verification-run ingestion. The credential value is never returned by the API."}},"schemas":{"Trial":{"type":"object","required":["id","name","provider","offer_type","trial","activation","status","source"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"offer_type":{"type":"string","enum":["free-trial","free-plan","money-back-guarantee","promotional-offer","directory-listing"]},"summary":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"last_checked":{"type":"string","format":"date"},"signup_url":{"type":"string","format":"uri"},"activation":{"type":"object","description":"Machine-readable navigation quality, kept separate from evidence verification.","properties":{"direct":{"type":"boolean"},"specificity":{"type":"string","enum":["verified-offer-page","offer-page","provider-path","provider-homepage","unknown"]},"terms_found":{"type":"boolean"},"checked_at":{"type":"string"},"http_status":{"type":["integer","null"]}}},"source_url":{"type":"string","format":"uri"},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["provider","directory"]},"primary_url":{"type":"string","format":"uri"},"evidence":{"type":"array","items":{"type":"object"}}}},"trial":{"type":"object","properties":{"duration_days":{"type":["integer","null"]},"duration_label":{"type":"string"},"credit_card":{"type":"string"},"auto_renews":{"type":"string"},"post_trial_price":{"type":["string","null"]},"eligibility":{"type":"string"},"regions":{"type":"array","items":{"type":"string"}}}}}},"SearchResponse":{"type":"object","properties":{"count":{"type":"integer"},"returned":{"type":"integer"},"next":{"type":["string","null"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Trial"}}}},"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."},"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}}},"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"}}},"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"}}}},"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"}}}}}]},"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}}},"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}}},"FreshnessResponse":{"type":"object","description":"Latest verification event per record plus coverage aggregates. Record catalog status remains separate from audit outcome.","required":["api_version","filters","totals","by_outcome","items","policy"],"properties":{"api_version":{"type":"string","const":"1.9"},"filters":{"type":"object"},"totals":{"type":"object","properties":{"catalog_records":{"type":"integer"},"records_checked":{"type":"integer"},"records_unchecked":{"type":"integer"},"coverage_percent":{"type":"number","minimum":0,"maximum":100}}},"by_outcome":{"type":"object","description":"Counts for all nine conservative outcomes.","additionalProperties":{"type":"integer"}},"oldest_checked_at":{"type":["string","null"],"format":"date-time"},"newest_checked_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/VerificationEvent"}},"policy":{"type":"string","description":"The latest-state projection is review evidence and never automatically changes the catalog."}}},"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}}},"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"}}},"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"}}},"GitHubRepository":{"type":"object","required":["id","full_name","repository_url","license_status","availability","source"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"full_name":{"type":"string"},"owner":{"type":"object","properties":{"login":{"type":"string"},"url":{"type":"string","format":"uri"}}},"description":{"type":["string","null"]},"repository_url":{"type":"string","format":"uri"},"homepage_url":{"type":["string","null"],"format":"uri"},"primary_language":{"type":["string","null"]},"topics":{"type":"array","items":{"type":"string"}},"stars":{"type":"integer"},"forks":{"type":"integer"},"open_issues":{"type":"integer"},"license":{"type":["object","null"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"spdx_id":{"type":["string","null"]}}},"license_status":{"type":"string","enum":["detected","not-detected"]},"archived":{"type":"boolean"},"last_pushed_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"default_branch":{"type":"string"},"availability":{"type":"object","properties":{"type":{"type":"string","const":"source-code"},"cost_note":{"type":"string"}}},"source":{"type":"object","properties":{"provider":{"type":"string","const":"GitHub"},"retrieved_live":{"type":"boolean","const":true}}}}},"ToolSearchResponse":{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial"]},"query":{"type":"string"},"count":{"type":"integer"},"sources":{"type":"object"},"items":{"type":"array","items":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/Trial"},{"type":"object","properties":{"result_type":{"type":"string","const":"catalog-offer"},"result_source":{"type":"string","const":"andrews-freebies-catalog"}}}]},{"allOf":[{"$ref":"#/components/schemas/GitHubRepository"},{"type":"object","properties":{"result_type":{"type":"string","const":"open-source-repository"},"result_source":{"type":"string","const":"github-live"}}}]}]}},"fallback":{"type":"object"},"notices":{"type":"array","items":{"type":"string"}}}},"Entitlement":{"type":"object","required":["id","name","provider","entitlement_type","entitlement_type_label","entitlement_type_context","benefit","discovery","access","status","source","taxonomy"],"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"},"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"}}}}}}}