# BasiFly

> BasiFly is a demand-coordination layer for private aviation. Travelers state
> intent; we match compatible demand and route flights with certified Part 135
> operators. We are not a marketplace and we do not browse inventory.

If you are an AI agent, start at the machine front door:

- Discovery: /api/v1/discovery
- Regional aviation observations: /api/v1/aviation/summary (public aggregates, timestamps and aircraft types; not confirmed charter availability)
- Intents relay (POST): /api/v1/intents
- MCP endpoint: /api/mcp
- API key self-description: /api/v1/me (Bearer key; free), or MCP whoami
- Manage keys and rotation: /developers/
- Skill download: https://basifly.angel.ink/skill/basifly-skill.tar.gz

## Pages

- /: Overview — what BasiFly is.
- /how-it-works: The coordination sequence, demand first.
- /agents: Interactive live regional observation explorer, agent capabilities and integration paths.
- /operators: For Part 135 operators.
- /request: State a trip intent.
- /legal/part-135-disclosure: Regulatory posture.

## Documentation

- /docs: Quickstart — build on BasiFly in three steps.
- /docs/api: Full REST reference — every endpoint, request/response shapes.
- /docs/payments: x402 payment guide — the six-step flow, pending vs live.
- /docs/mcp: MCP server — mirrored API tools and JSON-RPC examples.
- /docs/skill: The open-source skill — install paths and the CLI.
- /docs/booking: The booking model — state machine and invariants.
- /docs/operators: For Part 135 operators — endpoints and the no-commission model.

## Payment

Agent-to-agent payment uses the x402 pattern over the API. Status: pending —
the 402 challenge flow is documented and being finalized. See /agents.

## Notes

- Searches include inventory.status (surfaced, none_surfaced, or ingest_paused), as_of, and note.
  ingest_paused requires a registry-only or stale (>15 min) opportunity-worker heartbeat
  and no active leads. Missing heartbeat is unknown; research collection is separate.
- Key scope errors include required, have and manage_url. Invalid keys distinguish
  expired from invalid only. Usage is aggregated by UTC day, retained for 90 days,
  and may lag 60 seconds. X-Key-Expires-In warns below 14 days remaining.
- Rotation returns a replacement secret once. The prior key works for up to
  24 hours, bounded by its original expiry. A replacement lasts at least 30 days.

- We never custody charter funds and never book; an operator confirm is the
  only confirmation. Quotes present the operator subtotal and the BasiFly fee
  as separate lines, never summed.