# Rout Data API

Version **1.0.0-preview** · Read-only · Independently collected from issuer sources

Rout Data exposes card identities, original issuer artwork, reviewed fees and reward rules, revision history, and source-check history. It is a separate read-only product surface. It never exposes customer accounts, balances, transactions, Plaid tokens, card numbers or wallet membership.

This is a developer preview implemented in the Rout backend. Production hosting, customer provisioning, billing, contractual redistribution rights and a service SLA are not launched. No production URL is implied by the examples.

## Start locally

Start the backend using `pnpm dev` in `services/api`. Its default base URL is `http://localhost:3001/data/v1`. HTTPS is required for a deployed service.

An operator provisions a key from that directory:

```sh
pnpm catalog:access create "My server" --owner "customer-identifier" --out /tmp/rout-data-key.json --days 90 --rate 120
```

The output file is created exclusively with mode `0600`. The secret is displayed only inside that file, never in CLI output or the database. Transfer it through your secret manager, then remove the temporary file. Do not put it in a browser bundle, mobile bundle, URL, Git repository or support log. The database stores a SHA-256 digest of a random 256-bit token. Keys carry only `catalog:read`; they do not work on `/api/v1/accounts`, `/api/v1/manual-cards` or any other app route. User-session cookies alone do not authenticate the product API.

Configure `ROUT_DATA_KEY` privately on your server, then:

```sh
curl --fail-with-body \
  -H "Authorization: Bearer $ROUT_DATA_KEY" \
  'http://localhost:3001/data/v1/cards?q=freedom&limit=10'
```

```javascript
const origin = process.env.ROUT_DATA_ORIGIN ?? 'http://localhost:3001';
const response = await fetch(`${origin}/data/v1/cards/chase-freedom-flex`, {
  headers: { Authorization: `Bearer ${process.env.ROUT_DATA_KEY}` },
  signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`Rout Data returned ${response.status}`);
const card = await response.json();
// Artwork URLs are origin-relative. Preserve the image's intrinsic proportions.
const artworkUrl = card.artwork ? new URL(card.artwork.url, origin).href : null;
const qualityResponse = await fetch(
  `${origin}/data/v1/cards/${card.id}/quality`,
  {
    headers: { Authorization: `Bearer ${process.env.ROUT_DATA_KEY}` },
    signal: AbortSignal.timeout(10_000),
  },
);
if (!qualityResponse.ok) throw new Error('Could not verify product coverage');
const quality = await qualityResponse.json();
if (!quality.allChecksPassed) {
  // Show sourced partial details and the gaps; do not label the product complete.
}
```

List keys (metadata only) with `pnpm catalog:access list`. Revoke immediately with `pnpm catalog:access revoke KEY_ID`. For rotation, provision a second key, update your server secret, verify a request, then revoke the first. Keys expire after 90 days by default; operators may choose 1–365 days. Provisioning is an operator CLI, not a public signup API.

## Endpoint reference

Every `/data/v1` endpoint requires a bearer key. The contract is available without a key at `/data/openapi.json`; the website hosts a downloadable copy at `/developers/openapi.json`.

| Method and path                | Purpose                                                                          |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `GET /cards`                   | Search and paginate identities with verification and artwork metadata            |
| `GET /cards/{id}`              | Full product, published facts, evidence references and source state              |
| `GET /cards/{id}/history`      | Published version numbers, review dates and review notes                         |
| `GET /cards/{id}/verification` | Current daily verification result for every source supporting this card          |
| `GET /cards/{id}/quality`      | Ten explicit completeness checks, outstanding gaps and current all-checks result |
| `GET /cards/{id}/checks`       | Immutable source-check records, newest first                                     |
| `GET /issuers`                 | Registered issuer IDs and names, including issuers still being collected         |
| `GET /coverage`                | Measured inventory and field completeness, overall and per issuer                |
| `GET /changes`                 | Incremental creation, publication and identity-update events                     |
| `GET /health`                  | Daily freshness, unavailable sources and due work                                |

`GET /data/artwork/{id}` serves reviewed original assets without authentication. This route serves only bundled, allowlisted assets, not an arbitrary image proxy. It returns image MIME type, SHA-256 ETag, a one-day cache lifetime and supports `If-None-Match` / `304`. `artwork.sourceUrl` and `sourcePage` identify the issuer asset and the page where it was matched. An unavailable exact product has `artwork: null`; a different card's image is never substituted. Issuer marks and artwork remain issuer-owned. Metadata provenance is not a grant of redistribution rights.

### Search and pagination

`/cards?q=...&issuer=...&country=...&currency=...&category=...&benefits=true&limit=30&offset=0`

- `q`: up to 160 characters, case-insensitive words matched against name, issuer and aliases; all words must match.
- `issuer`: exact ID from `/issuers`, such as `chase` or `capital-one`.
- `country`: uppercase two-letter market code, such as `GB`, `DE`, `CA`, `SG`, `AU`, `IN` or `ZA`.
- `currency`: uppercase three-letter billing currency, such as `GBP`, `EUR`, `CAD`, `SGD`, `AUD`, `INR` or `ZAR`. Both filters require explicit product market metadata; older identities without it are excluded, not assumed to be US/USD.
- `category`: exact published rule category, such as `dining`. Merchant-specific categories can also exist. A match does not establish freshness.
- `benefits`: `true` or `false`; whether **any** reviewed facts have been published. A fee-only record qualifies. Inspect `facts.rules` to determine reward-rule coverage.
- `limit`: 1–50, default 30. `offset`: 0–100,000, default 0.
- Ordering: cards with assigned artwork first, led by curated US popularity, followed by other cards ordered by issuer ID and card ID. Cards without artwork come last, even if they are popular; that final group uses the same popularity and stable ID order. Review status and published-fact coverage do not affect ranking. Filters and ordering apply before pagination. Quality metadata remains available separately. Popularity is editorial discovery order, not measured market share, financial advice or the decision engine's recommendation score.
- Response: `{ cards, total, offset, nextOffset }`. Continue until `nextOffset` is null. Deduplicate by stable ID: additions and reviews can change sort order between pages. This is not a snapshot-consistent bulk export.

Check history uses `before` (exclusive sequence) and `limit` (1–100, default 50). Continue using `nextBefore` until null. Sequences belong to the global source-check ledger; one source may support several cards.

### Card fields and unknown values

`id` is a stable Rout product identity. It is not a PAN, BIN, bank account ID or application reference. Products are differentiated by issuer and actual product variant, including personal/business and secured/unsecured distinctions. Cosmetic designs and loyalty tiers are not independently counted products. `active: null` means current availability has not been established.

`market`, when reviewed, identifies the product's country and billing currency. Cards from the same global bank in different markets must have separate identities. A missing market is unknown; never infer a currency from a bank's name.

`facts` includes recurring fee, legacy USD annual fee, foreign transaction fee, reward program, earning rules, benefit descriptions, offers and transfer partners. Unknown objects are null or absent and missing collections are empty arrays. An empty array means **no published data**, not “no benefits exist.” Do not substitute zeros for unknown fees. `hasBenefits` means at least one fact is published, not complete coverage.

`facts.recurringFee` contains `amount`, `currency`, `period` (`month` or `year`), `conditions` and `evidence`. Amounts are major currency units, including fractional units. Preserve monthly pricing, conditional waivers and applicable-tax notes. Variable fees remain unknown unless the applicable tier is established. Legacy `annualFee.amountUsd` is retained for USD annual fees only. For example, a EUR 2.49 monthly DKB fee has `recurringFee: { amount: 2.49, currency: "EUR", period: "month", ... }` and `annualFee: null`; it is neither USD 2.49 nor EUR 2.49 annually. No exchange conversion is performed.

A rule contains its rate and unit (`points`, `miles` or `percent`), category, channel, enrollment requirement, optional cap, dates and exclusions. Non-USD point/mile rules require `spendBasis: { amount, currency }`: five points per INR 150 is `rate: 5`, not five points per dollar or rupee. Spend increments, transaction-level rounding and exclusions can require additional conditions; do not round or prorate from the denominator alone. Percentage rates remain percentages.

`requiresCategorySelection: true` means the customer must have this category selected on the issuer account for its bonus to apply. This is separate from program enrollment; a published default category is not evidence of an existing customer's selection. Omitted/false means the rule has no separately modeled category-choice requirement, not that every other condition is satisfied. Rout's current comparison service excludes choice bonuses until personal selection can be verified and discloses the resulting uncertainty. It also labels unknown remaining bonus caps, even when it can evaluate a conservative base/post-cap rate. Such estimates do not establish the best reward across the entire wallet.

Legacy `cap.amountUsd` represents a USD spending cap. The additive `capMoney` instead uses `amount`, `currency`, `period`, `group` and `afterRate` for a spending cap in the product's currency. A limit on reward points or cashback earned is not a spending cap; such conditions remain in descriptions until represented by a dedicated structured model. Respect shared cap groups and reset periods. If both legacy and currency-aware aliases are present, they must agree; publication rejects mixed currencies. Unknown caps do not mean unlimited rewards.

`issuer-portal` is not equivalent to direct booking. Points and miles have no implied cash valuation. Merchant reward currencies are not automatically cash. Targeted offers are labeled and must not be promised to all users. Published facts do not establish a customer's personal eligibility or linked account product match. Use the current quality assessment to distinguish complete reviews from partial records. A published revision alone does not establish full benefit coverage.

Evidence is either a short excerpt or a source URL with UTF-16 text offsets and a SHA-256 excerpt hash. Offsets reference normalized captured text, not raw HTML. Source snapshots are retained internally for review; this API does not redistribute full issuer pages. Each published revision records the source hashes actually reviewed. History currently returns revision metadata; retrieving historical fact bodies is not yet an endpoint.

### Complete product review

`GET /cards/{id}/quality` is the completeness gate. A `reviewed` record or a successful daily check alone does not pass it. It returns `{ cardId, version, asOf, status, allChecksPassed, passed, total, checks, scope }`. Every check has `id`, `label`, `status` (`passed`, `missing`, `partial`, `needs-review`) and an explanation.

The ten checks cover exact product/market metadata, original artwork, fees/interest, earning rules/limits, benefits/protections, public offers, loyalty/transfers, eligibility, published evidence, and successful source verification within 24 hours. Artwork requires the exact product mapping, an allowed issuer source and a matching bundled-file SHA-256. Identity requires explicit market, audience, network/private-label designation and availability; a public directory listing alone does not establish all four.

Six financial sections require `facts.review[section]`, where `section` is `fees`, `rewards`, `benefits`, `offers`, `transfers` or `eligibility`. Each assessment includes `status: "complete" | "not-applicable" | "none-published"`, an independently written `summary`, and a nonempty `evidence` array. An operator must review the full applicable public terms, including linked disclosures and limitations, before recording completion. The API validates evidence and structural consistency; it cannot infer that an editor has read every applicable term. No existing partial record is automatically upgraded.

`not-applicable` requires positive source evidence. Empty arrays are insufficient. It is rejected for fees, eligibility or a populated section. A complete fee assessment requires known recurring and foreign fees (including evidenced zero amounts); credit/charge products also need interest terms. `facts.terms` stores sourced `interest`, `fee`, `eligibility`, `redemption` and `other` disclosures with stable IDs, titles, descriptions and evidence. Missing earning denominators, unknown enrollment/channel conditions, unknown transfer ratios and expired offers prevent affected sections passing.

`none-published` is allowed only for an empty **offers** section after an explicit review of at least two distinct public sources, such as the product page and current pricing disclosure. The summary must identify the scope and review date. It means no advertised promotion was found in those sources, not that private or targeted offers cannot exist. It cannot complete benefits, rewards or other sections and is never assigned automatically to an empty list.

A benefit can carry `applicableNetworks`, an explicit list of payment-network variants to which its issuer guide applies. Never apply a Visa-only benefit to a Mastercard account. An omitted network list means network scope was not separately recorded, not universal coverage. Preserve `enrollment`, all limits, exclusions and claim conditions in the description. The app exposes the source guide from each benefit.

The assessments belong to immutable fact revisions. If evidence changes or any supporting source loses daily verification, previously passed financial sections become `needs-review`. Future-dated checks and checks for a different source hash cannot establish freshness. Consumers should inspect the current response rather than persist `allChecksPassed` indefinitely. Even a complete public product review does not establish a user's eligibility, points balance, enrollment, targeted offers or suitability for a transaction.

For an operator audit from `services/api`:

```sh
pnpm catalog quality > /tmp/rout-card-quality.json
pnpm catalog quality chase-freedom-flex
# Optional release gate: exits 1 unless every requested card passes all ten checks.
pnpm catalog quality --require-complete
pnpm catalog quality chase-freedom-flex --require-complete
```

The November 3 capture covers **4,001 cards across 258 issuer/brand labels**, **119 products with published financial records**, **3,882 products without published financial facts**, and **3,880 original card designs**. **Thirteen products currently pass all ten checks.** Earlier completion counts are historical: a source change or overdue check can remove current full-review status without deleting a reviewed version. The [latest source refresh](reports/complete-cards-refresh-2026-11-03.json) restored eight unchanged records. A separate [review of eleven changed sources](reports/source-change-review-2026-11-03.json) reconfirmed five more: changes were dated confirmations, a holiday notice and disclosure-link metadata, with unchanged financial content. The other 3,988 records remain incomplete; the [per-card assessment](reports/card-completion-status-2026-11-03.json) lists each outstanding check. A [First Citizens FAQ review](reports/disclosure-review-2026-11-03-first-citizens-transfers.json) also completed two external-transfer assessments and added current internal point-gifting and pooling terms without certifying the unfinished rewards sections.

The fixed [157-card review](reports/card-review-cohort-157-2026-11-03.json) includes artwork and all financial-data checks. **36 images have been repaired and 121 artwork gaps remain. All 157 have outstanding checks. TD Business Solutions passes nine of ten:** phone-protection enrollment needs clarification, so its earlier complete result was reopened during final review. TD First Class now has reviewed fees, rewards, transfer policy and eligibility, plus detailed personal insurance terms, but conflicting welcome-bonus timing and incomplete partner-benefit terms remain open. The [artwork ledger](reports/artwork-gap-review-2026-11-03.json) records each repair. Earlier 116-card and artwork reports remain separate, dated evidence; overlapping cohorts are not added together.

Operators can run `pnpm catalog:cohort:refresh --database data/rout.sqlite --seconds 300` to check due sources for this fixed cohort through the normal collector. Then run `pnpm catalog:cohort --database data/rout.sqlite --origin http://localhost:3001 --report reports/card-review-cohort-157-latest.json --require-complete`. This gate checks all ten requirements, decoded original image files, generated app mappings and live artwork delivery. It exits nonzero until every frozen member passes. `catalog:artwork:cohort` is a separate artwork-only audit. Refreshing sources never automatically approves changed terms, substitutes a design or marks an incomplete card fully reviewed.

Search responses include `cards[].quality` with `status`, `allChecksPassed`, `passed`, `total` and `asOf`. `/coverage` exposes `fullyReviewed`, calculated using the same live quality checks. `withBenefits` counts any published facts, including incomplete records, and the legacy `reviewed` state is not a completeness certificate.

## Freshness and daily verification

Two independent concepts are exposed:

| `card.verification` | Meaning                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| `identity-only`     | Product identified; no financial facts published                                                 |
| `reviewed`          | Published evidence matches the reviewed source and all source checks succeeded within seven days |
| `changed`           | Source text differs from the reviewed version; review is pending                                 |
| `stale`             | A source failed or has not been successfully checked within seven days                           |

| Daily `/verification` status | Meaning                                                                                                                          |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `confirmed`                  | All supporting sources have an audited successful check within 24 hours, no pending source changes, and some facts are published |
| `identity-observed`          | Sources checked within 24 hours, but no facts are published                                                                      |
| `changed`                    | An unresolved source change exists                                                                                               |
| `unavailable`                | The most recent audited attempt for at least one source failed                                                                   |
| `overdue`                    | No successful audited check within 24 hours for at least one source                                                              |

For strict daily freshness, require both `card.verification === 'reviewed'` and `/verification.status === 'confirmed'`. Confirmation applies to the published evidence, not completeness of all benefits. Changes may be page navigation, formatting or unrelated content; they require review and are not automatically labeled financial changes.

The backend continuously checks durable due schedules while running. Every successful source check schedules another for 24 hours later; errors retry with bounded backoff, and unavailable/robots-blocked pages are retried daily. It respects robots policies, a minimum five-second per-host delay, conditional ETags/Last-Modified, pinned public DNS, response size bounds, and durable source/host leases. A `304` with a prior capture records `unchanged`. A successful new text hash records `initial` or `changed`; identical text records `unchanged`. Failures never advance successful-check time and remain visible in the audit trail. Successful product HTML captures discover linked issuer-hosted disclosure candidates and retain the parent snapshot hash, URL, label, section hints and observation time. PDFs and explicit guides are prioritized over generic links; global navigation and unrelated hosts are excluded. Linked document targets are included in the product source fingerprint, so replacing a guide URL while retaining its visible label also triggers review. Older HTML captures receive one unconditional fetch to discover documents; a completed zero-link scan is retained to avoid repeating this on every check. A discovered link is not proof of applicability. Disclosure pages are not recursively crawled. Successful HTML captures also queue discovered artwork for variant review. Image discovery never automatically assigns a card design.

When a source changes, the last published version remains available with `changed` status. An operator reviews current evidence, updates facts or confirms the existing facts against the new snapshot, then publishes a new version. Unsupported financial changes are not silently published. Source-check automation is implemented; fully autonomous financial-fact extraction and approval is not claimed.

RBC public card/legal JSON is captured from inert product-page data or strictly matched issuer-owned card-data URLs. This includes endpoints that omit Content-Type; valid JSON, expected path and matching product identity are required. Legal text and offer-expiry metadata contribute to source changes; unrelated telemetry, affiliate and authenticated offers are excluded. Collection never executes issuer scripts or certifies an offer's active status.

Text-based issuer PDFs use the same verification and review lifecycle as HTML. Extraction preserves page boundaries and includes an original-file SHA-256 in the source fingerprint, so non-text changes also trigger review. Private storage retains the exact PDF, parser version and page count for each capture; it does not redistribute those files through this API. Current captures and all published revision evidence survive pruning. Unreferenced originals and snapshots can be removed after 30 days.

PDF parsing is isolated and bounded (16 MiB, 100 pages, 900,000 characters and 20 seconds). Protected, invalid or scanned pages that cannot be reliably extracted fail closed and require a separate review; the failed attempt never advances a successful-check timestamp. Reviewed title or blank pages may have explicit non-substantive-page exceptions in the private operator registry, bound to the exact original SHA-256, total page count and inspected page numbers. Image-only financial pages require a complete, manually verified transcription bound to the exact file hash/page, not a blank-page exception. A changed file requires fresh visual inspection; no scanned financial page is silently omitted. The capture retains the visual-review observation. A PDF capture establishes source availability, not accuracy of an automatically inferred financial rule. Reviewers must check tables, footnotes, effective dates, product/network variants and conflicts across linked disclosures before marking a section complete.

A daily interval is a target, not an uptime or verification guarantee. An issuer can block access, remove a page or change unmonitored terms. All sources must be mapped to cover a product's complete terms. Monitor `/health` and alert when any card is overdue or unavailable. Stop/start of a laptop cannot provide an always-on service: production requires an always-running worker and persistent storage.

## Change feed

Bootstrap by paginating `/cards`, then read `GET /changes?after=0` to catch changes that occurred during that scan. Existing pre-preview records may precede the change feed; reconcile inventory periodically. Process the returned `changes`, fetch each affected card, and persist `nextCursor` **only after processing succeeds**. Repeat until an empty page; then poll on your own schedule. Process idempotently by `seq`. Events include `card.created`, `card.published`, `card.updated` and `card.identity-updated`. New identities emit `card.created` atomically with registration; re-registering an unchanged identity does not duplicate it. Every check is in `/checks`; the change feed does not emit unchanged daily checks. Webhook delivery and snapshot export are not implemented.

## Errors and rate limits

Errors use `{ "error": { "code": "unauthorized", "message": "…", "requestId": "…" } }`.

| HTTP | Action                                                         |
| ---- | -------------------------------------------------------------- |
| 400  | Fix invalid ID/query parameters; do not retry unchanged        |
| 401  | Check secret, expiry and revocation; do not retry indefinitely |
| 404  | Unknown product/route; refresh inventory                       |
| 429  | Wait `Retry-After` seconds, then retry with jitter             |
| 500  | Retry with bounded exponential backoff; retain request ID      |

Valid-key requests return `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (UTC Unix seconds). The default is 120 requests per fixed minute per key. The counter is persisted and atomic across local processes sharing the database. New keys may have a different operator-set limit. Rate-limited requests do not consume additional quota. Responses are `no-store` except the public artwork route. The API is designed for server-to-server requests; cross-origin browser access with secret keys is deliberately not configured.

## Operating the data service

From `services/api`:

```sh
pnpm catalog coverage-report
pnpm catalog health
pnpm catalog verification chase-freedom-flex
pnpm catalog discover 50
pnpm catalog queue-candidates
pnpm catalog crawl 300
pnpm catalog artwork-candidates
pnpm catalog:artwork --missing
pnpm catalog reviews
pnpm catalog review-plan --out /tmp/card-review-plan.json
pnpm catalog review-plan CARD_ID --out /tmp/product-review-plan.json
pnpm catalog review-packet CARD_ID --out /tmp/private-review-packet.json
pnpm catalog draft CARD_ID --out /tmp/review.json
pnpm catalog publish /tmp/review.json --reviewer REVIEWER --note 'Describe the evidence and changes'
pnpm catalog:docs --coverage
```

`review-plan` lists every requested product’s actual outstanding checks, current linked disclosure candidates and published sources, ordered with popular products first. `review-packet` adds the private normalized source text and hashes for editorial work. Packet files are written with mode 0600 on creation and must not be published through the data API. Link candidates from a superseded parent snapshot remain historical, not current. Neither command publishes or approves facts.

`catalog recheck ISSUER_ID` explicitly queues that issuer again (or all sources if omitted). Collection is bounded; `crawl 300` can finish an in-flight batch after its time budget. The application worker runs every second with an overlap guard; host delays and durable leases control actual throughput. `ROUT_CATALOG_MONITOR=off` pauses background collection. Fresh installations register identities only; they must collect current snapshots and review facts before publishing. Reviewed seed files are not automatically declared current.

Keep the API behind TLS, persist and back up the SQLite database, supervise the process with automatic restart, and monitor unavailable/overdue sources and disk space. Multiple local workers can share a database and respect its leases. SQLite is not a multi-region distributed database; plan a database/queue migration before horizontal deployment across independent hosts. Source history and verification logs need a documented retention policy before large-scale operation. Operator key provisioning, usage billing, customer self-service, contractual image licensing and production monitoring remain launch work.

To add artwork, visually verify the exact product variant against its official page, preserve the original image under `native/iphone/assets/connected-cards/catalog`, add its source URLs, dimensions, checksum and review note to `seeds/artwork.json`, and set the matching identity’s `artworkId`. Run `pnpm catalog:artwork --generate` to validate asset hashes and regenerate the app’s static asset bindings, then format the generated files. A mismatched or missing product fails validation. `pnpm catalog:artwork --missing` lists the remaining exact product IDs, names and issuer pages needing artwork. Original self-contained SVG files are accepted alongside PNG/JPEG/WebP; active content and external references are rejected. The iPhone app renders their paths, gradients and styles directly; the public endpoint applies a restrictive CSP when serving SVG. Bundled artwork updates require an app release; the public data API serves the current deployed manifest. At larger inventory sizes, remote image delivery and an image CDN should replace bundling the entire catalog in each mobile release.

Rout's owned assets are the normalized product model, source-to-fact lineage, review history, verification records and matching infrastructure. The underlying public issuer facts and trademarks are not exclusive. The coverage report measures identities, reviewed rules, fees, benefits and artwork separately. Reaching 4,000 identities alone would not prove feature or inventory parity with another provider.

## Compatibility

The `/data/v1` prefix versions the contract. Additive fields may appear; clients should ignore unknown fields. New enum values or breaking meaning changes require a major contract version. Product IDs remain stable; facts and artwork can change with provenance. Generate client types from the OpenAPI 3.1 contract. The app's session-authenticated `/api/v1/catalog/*` endpoints remain separate from the product API.
