Travelmode Visa Intelligence API
Last verified: 2026-06-20 (Task #389 — Visa Intelligence API docs).
This directory holds the public contract for the Visa Intelligence feature of the Travelmode developer platform. The OpenAPI spec is the source of truth; the markdown guides below add narrative guidance and worked examples.
Status: v1. The public surface covers deterministic requirement checks, the published rule set, the official-source catalog (sources + documents), and a change-detection feed with customer-managed webhooks. The Visa feature is published in the developer portal at
/developers/visaon the deployed app (e.g. https://travelmode.ai/developers/visa). Typed client SDKs are auto-generated from this spec — seesdks/typescript/andsdks/python/.
Admin-only routes under /api/admin/visa/** are intentionally not
documented here — this directory covers only the customer-facing
/v1/visa/** surface.
Hosted developer portal
Every file in this directory is published under the Visa feature of the portal, e.g. https://travelmode.ai/developers/visa:
| URL | What it serves |
|---|---|
/developers/visa | Visa feature overview (this README). |
/developers/visa/<slug> | Each markdown guide (getting-started, authentication, rate-limits, changes-webhooks, errors). |
/developers/visa/reference | Interactive OpenAPI 3.1 reference (Stoplight Elements) with built-in Authorize and Try It panels. |
/developers/visa/openapi.yaml | Canonical YAML spec, served raw. |
/developers/visa/openapi.json | Same spec, JSON-encoded for tooling. |
The portal is a Next.js route under app/developers/ that reads this
directory at runtime via the feature registry
(app/developers/lib/features/). There is no separate publish step: the
moment a change to openapi.yaml or any *.md file lands on main and
the deploy build runs (npm run build), the live portal serves the new
content. The deploy build also runs npm run check:openapi, which fails
the deploy if any feature spec is invalid — so a broken spec never
reaches production.
Files
| File | What it contains |
|---|---|
openapi.yaml | OpenAPI 3.1 spec — every Visa path, schema, error code, header, and example. Validated by npm run check:openapi. |
getting-started.md | First request, base URL, auth quickstart, first visa check. |
authentication.md | API keys, scopes, customer-vs-master-key model. |
rate-limits.md | Per-key hourly quota, headers, 429 handling. |
changes-webhooks.md | Polling the change feed and subscribing with signed webhooks. |
errors.md | Every error code, status, and example envelope. |
Quick links
- Auth:
X-Visa-Intel-Key: vsk_live_...(orAuthorization: Bearer) — seeauthentication.md. - Error envelope: flat
{ error, code, details?, requiredScope?, retryAfter? }— seeerrors.md. - Scopes:
visa:check,visa:changes,visa:sources,visa:health— seeauthentication.md. - Snapshots (
/v1/visa/sources/{cc}/snapshots) are admin-cookie gated, not API-key gated — seeauthentication.md. - Customer self-serve key management and onboarding:
docs/visa-intel-customer-onboarding.md.
Validating the spec
npm run check:openapi
check:openapi parses every feature's OpenAPI YAML through
@apidevtools/swagger-parser, which dereferences $refs and runs the
standard OpenAPI 3.x structural validator. The validator runs as part of
npm run check.