Developer Hub — CouponsRiver Public API

Overview

The API exposes the same tool records that power this site, projected to a small, safe set of fields. It is read-only — there are no write endpoints. It never returns coupon codes, affiliate links, or private editorial data.

Base URL: https://couponsriver.com/api/v1/
Format: UTF-8 JSON
Auth: none (public)
Spec: OpenAPI 3.1 (/openapi.json)
Discovery manifest: /ai-resources.json
Changelog: /developers/changelog/

Endpoints

Method & path	Description
`GET /api/v1/health/`	Liveness probe.
`GET /api/v1/categories/`	Content categories with tool counts.
`GET /api/v1/tools/`	Full tool catalogue.
`GET /api/v1/tools/{slug}/`	One tool, or 404.
`GET /api/v1/deals/`	Tools that carry a known offer.
`GET /api/v1/search/?q=`	Substring search (2–64 chars, max 20 results).
`GET /api/v1/compare/?tools=a,b`	Compare 2–4 tools by slug.

Example — a single tool record (note: all routes use a trailing slash):

GET /api/v1/tools/notion/

{
  "api_version": "v1",
  "tool": {
    "slug": "notion",
    "name": "Notion",
    "canonical_url": "https://couponsriver.com/business/notion/",
    "category": "Business",
    "description": "Notion pricing, plans, and how to save.",
    "offer_status": "unknown",
    "verification_status": "not-independently-verified",
    "discount_value": null,
    "last_verified_at": null,
    "updated_at": null,
    "pricing_source_url": null,
    "source_urls": []
  }
}

Provenance & verification fields

offer_status — the editorial offer state (officially-verified, tested-working, third-party-reported, expired, not-found, unknown).
verification_status — how strongly the offer is verified. not-independently-verified means no first-party confirmation exists.
discount_value — human-readable discount, or null unless first-party verified.
last_verified_at / updated_at — ISO 8601 dates, or null when unknown. A null date is deliberate and is never replaced with a placeholder.
pricing_source_url / source_urls — real, public URLs only; never affiliate or /go/ links.

See the verification methodology and data sources pages for what each state and source means.

Format, caching & CORS

All responses are application/json; charset=utf-8.
List and detail responses send Cache-Control: public, max-age=900, stale-while-revalidate=86400; /health uses a 60-second window; errors are no-store.
CORS is open (Access-Control-Allow-Origin: *) because the data is public and non-credentialed.
Output ordering is deterministic (lists are sorted by slug).

Errors

Errors use a stable envelope and correct HTTP status codes — never a stack trace:

{ "error": { "code": "not_found", "message": "No tool found for slug \"foo\"." } }

400 — missing/invalid parameter, over-length query, or too many/few compare targets.
404 — unknown slug.

Limits & usage

Query strings are length-bounded (search 2–64 chars; compare 2–4 slugs) and matched literally — never compiled into a regular expression. The API does not currently enforce application-level rate limits, so please cache responses and keep request volume reasonable. This is public catalogue data intended for building tools and integrations; do not use it to misrepresent CouponsRiver or imply an endorsement.

Questions or corrections? Use the contact page.

CouponsRiver Developer Hub