# Flypost Ask - Read-Only Discovery API (llm.txt v1)

service_name: Flypost Ask
service_purpose: >
  Flypost Ask provides read-only discovery of real estate events (open houses, garage sales, 
  estate sales) via geographic search. This surface is for event discovery only and does not 
  support event creation or modification. All responses provide full-fidelity location and 
  event details.

primary_audience: machine-agents (LLMs, AI assistants)
human_audience: developers building event discovery applications

base_url: https://api.goflypost.com
canonical_openapi: https://ask.goflypost.com/openapi.json

## Core Discovery Endpoints

### GET /v1/events/near
Description: >
  Retrieve events near a latitude/longitude within a specified radius.
  Supports optional date range filtering.

Query Parameters:
  - lat: number (required) - Latitude in decimal degrees (-90 to 90)
  - lng: number (required) - Longitude in decimal degrees (-180 to 180)
  - radius: number (optional) - Search radius in kilometers (0-100, default: 10)
  - start: string (optional) - Filter events starting on/after this date (ISO 8601)
  - end: string (optional) - Filter events ending on/before this date (ISO 8601)

Response Shape:
  success: boolean
  schemaVersion: string
  events: array of DiscoveryEvent objects
  meta:
    count: integer
    radiusKm: number

### GET /v1/events/{event_id}
Description: >
  Retrieve a single event by its unique event identifier.

Path Parameters:
  - event_id: string (required) - Unique event identifier

Response Shape:
  success: boolean
  schemaVersion: string
  event: DiscoveryEvent object

## DiscoveryEvent Schema

The DiscoveryEvent follows a strict what/where/when structure:

what:
  type: event category (open_house, garage_sale, estate_sale, etc.)
  label: optional human-readable event name

where:
  latitude: number (full precision)
  longitude: number (full precision)
  address: string (complete address)

when:
  start: ISO 8601 date-time
  end: ISO 8601 date-time

Additional fields:
  - eventId: unique identifier
  - dataHash: SHA-256 hash for integrity verification
  - externalListingUrl: URL to external listing (can be null)
  - source: optional provenance information (kind, url)

## Authentication

Authentication: Not required
Rate Limits:
  - 100 requests per 15 minutes per IP

## LLM Usage Recommendations

1. Use GET /v1/events/near when users ask for events near a location
2. Use GET /v1/events/{event_id} when users reference a specific event
3. Do not hallucinate event data - always call the API
4. Include date range filters when users specify time constraints
5. This is a DISCOVERY-ONLY surface - do not attempt to create or modify events
6. For event publishing, direct users to post.goflypost.com

## Health Check

GET /health - Service health status

## Versioning

API Version: v1 (discovery)
Stability: stable
Breaking changes: Will be announced via new version endpoints

## Support

Technical Support: support@goflypost.com
Documentation: https://goflypost.com/docs
Security Issues: support@goflypost.com