REST API v1

Query your flight, publish proofs, check leaderboard status, and connect scripts or automations to Fly in Public.

For AI assistants, start with the skill setup and hosted OAuth MCP. Use API tokens for scripts, custom clients, and advanced bearer-token MCP fallback.

Authentication

All bearer-token requests use the Authorization header:

Authorization: Bearer fip_...

/api/v1/* endpoints accept either a logged-in session cookie or a bearer token. Token management is session-only. The advanced MCP endpoint at /api/mcp uses bearer tokens; the hosted /mcp endpoint uses OAuth.

Base URL

https://flyinpublic.com/api/v1

All endpoints return JSON. Timestamps are ISO 8601 strings unless noted otherwise.

Versioning

API version	`v1`
Docs version	`2026-05-23`
Base path	`/api/v1`
Stability	Additive fields may be added to `v1`; breaking changes get a new path.

v1 changelog

Date	Change
`2026-05-23`	Planned proofs added: schedule future proof tasks with due dates, then complete them by publishing or linking a real proof. New endpoints under /api/v1/planned-proofs, matching MCP lifecycle tools (create/list/update/cancel/complete/link), and Telegram commands (/plan, /planproof, /proofs_planned, /done). Planned proofs never change altitude until completed.
`2026-05-18`	External status surfaces now expose altitude in meters and return both leaderboard ranks: longest flight and highest altitude. Leaderboard APIs and MCP leaderboard_top accept a metric selector for the two tabs.
`2026-05-16`	POST /api/v1/proofs now auto-fills message, platform, and publishedAt from the URL (X, YouTube, TikTok, Reddit, Open Graph) when not supplied. Explicit body fields still win. Same enrichment applies to the MCP add_proof tool and the Telegram /proof command.
`2026-05-15`	Public user and public proof read endpoints added, with matching MCP tools and Telegram commands for learning from other public builders.
`2026-05-14`	Hosted OAuth MCP added at /mcp, advanced bearer-token MCP retained at /api/mcp, Telegram bot-first linking added with /telegram/connect, and the in-repo Fly in Public skill plus /docs/skills introduced.

Endpoints

Method	Path	Description
`GET`	`/api/v1/me`	Viewer profile, project, and Telegram link state.
`GET`	`/api/v1/bird/state`	Live flight state with `altitudeMeters`, status, latest proof, crash deadline, and both leaderboard ranks.
`GET`	`/api/v1/proofs`	Your proofs, most recent first.
`POST`	`/api/v1/proofs`	Create a proof. Body: `{ url, message?, platform?, publishedAt? }`. Missing fields are auto-filled from the link (X, YouTube, TikTok, Reddit, or Open Graph metadata). Anything you send explicitly wins.
`GET`	`/api/v1/leaderboard`	Public leaderboard entries with sanitized public user and latest-proof summaries. Only flights currently in the air are ranked. Query: `metric=longest\|altitude`.
`GET`	`/api/v1/leaderboard/me`	Your selected-tab rank, both leaderboard ranks, and a page of nearby entries. Query: `metric=longest\|altitude`.
`GET`	`/api/v1/users/:username`	Public user profile and current flight state.
`GET`	`/api/v1/users/:username/proofs`	Public user proofs, most recent first. Query: `limit`, `since`, `cursor`.
`GET`	`/api/v1/users/:username/proofs/:proofId`	One public proof by username and proof id.
`GET`	`/api/v1/planned-proofs`	List your planned proofs, ordered by due date. Query: `status`, `upcoming=true`.
`POST`	`/api/v1/planned-proofs`	Schedule a planned proof. Body: `{ description, dueAt, platform?, context?, reminderAt?, reminderMinutesBefore? }`. Defaults to a reminder 1 hour before due time; pass an empty reminder field to disable it. Does not affect altitude.
`GET`	`/api/v1/planned-proofs/:id`	Get one planned proof.
`PATCH`	`/api/v1/planned-proofs/:id`	Update fields, or set status to planned, missed, or cancelled.
`DELETE`	`/api/v1/planned-proofs/:id`	Cancel a planned proof (kept on record as cancelled).
`POST`	`/api/v1/planned-proofs/:id/complete`	Complete it with `{ url, message? }` to publish a new proof, or `{ proofId }` to link an existing one. Publishing updates altitude normally.
`GET`	`/api/v1/tokens`	List API tokens with prefix, last-used time, and recent daily usage. Session-only.
`POST`	`/api/v1/tokens`	Create or revoke tokens with `_intent=create` or `_intent=revoke`. Session-only.
`POST`	`/api/v1/telegram/link`	Generate a Telegram link code. Session-only.
`POST`	`/api/v1/telegram/unlink`	Disconnect Telegram. Session-only.

Altitude and leaderboard units

Use flightState.altitudeMeters or flightState.altitudeLabel for user-facing altitude display.
flightState.altitude remains the internal 0-100 engine value for compatibility. Do not display it as altitude in a client UI.
The compatibility conversion is 10 meters per internal point.
Leaderboard ranks have two metrics: longest for longest flight and altitude for highest peak altitude.

Example requests

curl -H "Authorization: Bearer $FIP_TOKEN" \
  https://flyinpublic.com/api/v1/bird/state

curl -X POST \
  -H "Authorization: Bearer $FIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/post","message":"Shipped today!"}' \
  https://flyinpublic.com/api/v1/proofs

Example proof response

{
  "proof": {
    "id": "proof_...",
    "url": "https://example.com/post",
    "platform": "Website",
    "message": "Shipped today!",
    "publishedAt": "2026-05-14T13:00:00.000Z"
  }
}

Rate limits

There are no hard public rate limits yet. Token usage is tracked so you can spot which clients are active and revoke any client that misbehaves.

Error responses

`401`	Missing, malformed, or revoked bearer token.
`404`	Resource or route not found.
`422`	Invalid proof URL, duplicate proof, or invalid submitted fields.
`500`	Unexpected server error. Retry later or contact support.