A prompt, rules files and a Claude Code skill that teach a coding assistant the API, and the whole documentation as Markdown.

A coding assistant writes a good FlightByte integration when it reads these docs instead of guessing from what it saw in training. Everything here helps it do that: a prompt to start with, rules your repository keeps for every later session, a skill for Claude Code, and the documentation in a form a model reads best.

Every docs page also has Copy as Markdown, Open in ChatGPT and Open in Claude under its title, for when one page is all the context you need.

Start with a prompt

Paste this into Claude Code, Cursor, Copilot, Codex or a chat assistant, in the repository you want to integrate. It points the assistant at the full documentation and names the parts that are easy to get wrong.

Integration prompt

Integrate the FlightByte flight status API into this project.

First read https://flightbyte.dev/llms-full.txt, the complete documentation as Markdown. Use https://flightbyte.dev/openapi.json for exact request and response schemas. Then:

1. Keep the API key server-side, in an environment variable named FLIGHTBYTE_KEY, and send it in the x-api-key header to https://api.flightbyte.dev/v1.
2. Look flights up with GET /v1/flights/{carrier}/{flightNumber}/{date}, where date is the local departure date at the origin (YYYY-MM-DD). When a flight number operates more than one leg that day, choose one with the origin parameter.
3. To be told about changes, create a subscription with POST /v1/subscriptions, send an Idempotency-Key header, and store the secret from the response: it is shown in full only once.
4. Add a webhook endpoint that verifies the x-flightbyte-signature header (HMAC-SHA256 of "<t>.<raw body>" with the subscription secret) on the raw request body before parsing it, rejects timestamps more than five minutes old, answers 2xx within ten seconds and deduplicates deliveries on the event id.
5. Handle the error envelope: retry 429 after Retry-After, retry 502 and 503 with backoff, and do not retry other 4xx responses.

Ask me which flights to track and where webhooks should be delivered if the code does not make it clear. Show me a plan before changing files.

Rules for your repository

A prompt lasts one conversation. A rules file is read at the start of every session, so the assistant keeps the essentials even when nobody mentions FlightByte.

AGENTS.md or CLAUDE.md

Add this section to AGENTS.md at the root of your repository, which Codex, Cursor, GitHub Copilot and many other agents read, or to CLAUDE.md for Claude Code.

AGENTS.md

## FlightByte API

This project uses the FlightByte flight status API. Read the docs rather than guessing: https://flightbyte.dev/llms-full.txt has all of it, any page is Markdown at https://flightbyte.dev/docs/<page>.md, and the OpenAPI document is https://flightbyte.dev/openapi.json.

- Base URL `https://api.flightbyte.dev/v1`. Send the key in the `x-api-key` header from the `FLIGHTBYTE_KEY` environment variable. The key is a server-side secret: never ship it to a browser or a mobile app.
- A flight is addressed by carrier, flight number and the local departure date at the origin: `GET /v1/flights/TK/1848/2026-09-12`. Leading zeros in the number are ignored.
- One number can fly several legs a day. Lookups list them under `alternates`; pass `origin` (an IATA code such as `IST`) to pick one. A subscription for an ambiguous number without `origin` is refused with `400` and the list of `legs`.
- Branch on `status.phase` (`scheduled`, `boarding`, `departed`, `en_route`, `landed`, `arrived`, `cancelled`, `diverted`, `redirected`, `unknown`), not on `status.code`. For a single departure or arrival time use `bestTimeUtc`.
- Watch a flight with `POST /v1/subscriptions` and `{ carrier, flightNumber, date, webhookUrl, events?, metadata? }`, with an `Idempotency-Key` header so a retry does not create a second one. Store the returned `secret`: it is shown in full only in that response.
- Webhooks: verify `x-flightbyte-signature: t=<unix>,v1=<hex>`, where `v1` is HMAC-SHA256 of `"<t>.<raw body>"` with the subscription secret, on the raw bytes before JSON parsing, in constant time, with the timestamp within 300 seconds. Answer `2xx` within 10 seconds and do the work afterwards. Deduplicate on the event `id` and do not assume order. `metadata` comes back in every delivery.
- Test an endpoint with `POST /v1/subscriptions/{id}/test`, then read `GET /v1/subscriptions/{id}/deliveries`. Change types and payloads: https://flightbyte.dev/docs/webhooks.md.
- Errors share one envelope (`statusCode`, `error`, `message`, `requestId`). Retry `429` after `Retry-After` and `502` or `503` with backoff; `400`, `401` and `404` answer the same until the request changes. `402` with `"code": "watched_flight_limit"` means the plan's monthly watched-flight cap is reached.

Cursor rules

Save this as .cursor/rules/flightbyte.mdc. With a description and alwaysApply: false, Cursor's agent pulls the rule in when a task matches it.

.cursor/rules/flightbyte.mdc

---
description: FlightByte flight status API: flight lookups, subscriptions, and verifying signed webhooks
alwaysApply: false
---

This project uses the FlightByte flight status API. Read the docs rather than guessing: https://flightbyte.dev/llms-full.txt has all of it, any page is Markdown at https://flightbyte.dev/docs/<page>.md, and the OpenAPI document is https://flightbyte.dev/openapi.json.

- Base URL `https://api.flightbyte.dev/v1`. Send the key in the `x-api-key` header from the `FLIGHTBYTE_KEY` environment variable. The key is a server-side secret: never ship it to a browser or a mobile app.
- A flight is addressed by carrier, flight number and the local departure date at the origin: `GET /v1/flights/TK/1848/2026-09-12`. Leading zeros in the number are ignored.
- One number can fly several legs a day. Lookups list them under `alternates`; pass `origin` (an IATA code such as `IST`) to pick one. A subscription for an ambiguous number without `origin` is refused with `400` and the list of `legs`.
- Branch on `status.phase` (`scheduled`, `boarding`, `departed`, `en_route`, `landed`, `arrived`, `cancelled`, `diverted`, `redirected`, `unknown`), not on `status.code`. For a single departure or arrival time use `bestTimeUtc`.
- Watch a flight with `POST /v1/subscriptions` and `{ carrier, flightNumber, date, webhookUrl, events?, metadata? }`, with an `Idempotency-Key` header so a retry does not create a second one. Store the returned `secret`: it is shown in full only in that response.
- Webhooks: verify `x-flightbyte-signature: t=<unix>,v1=<hex>`, where `v1` is HMAC-SHA256 of `"<t>.<raw body>"` with the subscription secret, on the raw bytes before JSON parsing, in constant time, with the timestamp within 300 seconds. Answer `2xx` within 10 seconds and do the work afterwards. Deduplicate on the event `id` and do not assume order. `metadata` comes back in every delivery.
- Test an endpoint with `POST /v1/subscriptions/{id}/test`, then read `GET /v1/subscriptions/{id}/deliveries`. Change types and payloads: https://flightbyte.dev/docs/webhooks.md.
- Errors share one envelope (`statusCode`, `error`, `message`, `requestId`). Retry `429` after `Retry-After` and `502` or `503` with backoff; `400`, `401` and `404` answer the same until the request changes. `402` with `"code": "watched_flight_limit"` means the plan's monthly watched-flight cap is reached.

A Claude Code skill

A skill is a longer brief that Claude Code loads by itself when a task touches FlightByte: lookups and leg selection, subscriptions, the webhook payload, signature verification in Node.js and Python, retries, errors, and a checklist to finish with.

Download SKILL.md, or install it from a terminal:

For this project

mkdir -p .claude/skills/flightbyte
curl -fsSL https://flightbyte.dev/skills/flightbyte/SKILL.md -o .claude/skills/flightbyte/SKILL.md

For every project on this machine

mkdir -p ~/.claude/skills/flightbyte
curl -fsSL https://flightbyte.dev/skills/flightbyte/SKILL.md -o ~/.claude/skills/flightbyte/SKILL.md

Commit the project copy and everyone working in the repository gets it.

The docs as Markdown

URL	What it is
`/llms.txt`	An index of every page with a one-line description, in the llms.txt convention.
`/llms-full.txt`	The docs, the API reference, the guides and the glossary in one Markdown file.
`/docs/<page>.md`	Any docs page as Markdown, for example `/docs/webhooks.md`. Reference pages are written out from their OpenAPI operation.
`/openapi.json`	The OpenAPI 3.0 document the reference is generated from. Import it into Postman or Insomnia, or generate a client from it.

An agent that asks for Markdown gets it at the page's own URL:

curl -H "Accept: text/markdown" https://flightbyte.dev/docs/webhooks

Build with AI