# Flypost API

> Flypost is an open-house and local-event registry. Use this API to discover nearby open houses by location, publish events from natural language, verify buyer attendance, and collect post-visit feedback.

Base URL: https://api.goflypost.com
OpenAPI spec: https://api.goflypost.com/openapi.json

## Public endpoints (no auth required)

- GET /v1/events/near?lat=&lng=&radius_mi=: Discover open houses and events near a coordinate. Returns name, dates, address, organizer, and listing URL.
- GET /v1/events/:event_id: Fetch a single event by its Flypost ID.
- Events may contain an occurrences[] array for multi-slot events with fields: occurrenceId, startDate, endDate, label, local.date, local.startTime, local.endTime.
- POST /api/chat: Web Concierge — ask a natural-language question about nearby events. Pass { message, lat, lng, conversationHistory? }. Returns { success, message (markdown), timestamp }. Conditional on ENABLE_CONCIERGE=true.
- POST /api/chat/stream: SSE streaming version of Web Concierge. Same request body. Returns text/event-stream with events: {"type":"connected"}, {"type":"token","content":"..."}, {"type":"done","duration":ms}, {"type":"error","message":"..."}. Conditional on ENABLE_CONCIERGE=true.
- GET /api/chat/health: Web Concierge health check.
- GET /e/:slug/:fpid: Public HTML share page for an event.
- GET /e/:slug/:fpid/calendar.ics: Download event as iCal file.

## Authenticated endpoints

Pass your write token in the x-flypost-write-token header, or a Firebase ID token as Bearer.

- POST /api/parse-and-publish: Publish an event from free-text (Instagram caption, MLS note, etc.). Pass { naturalLanguageInput }.
- POST /v1/events/upsert: Publish or update a structured event object.

## Rate limits

- Discovery (public): 100 req / 15 min per IP
- Write endpoints: 50 req / 15 min per IP
- /api/chat, /api/chat/stream: 20 req / 15 min per IP (shared)