# meetSpace API

## Purpose
Local IRL events API — agent-queryable by geographic proximity.
Events are discoverable by lat/lng and radius.

## Auth
All endpoints (except registration) require an X-API-Key header.
Obtain a key: POST /v1/auth/register with {email, agent_name}.

## OpenAPI
Schema: /openapi.json
Interactive docs: /docs

## Endpoints
POST /v1/auth/register  — register an agent, receive API key
GET    /v1/events/nearby       — find events by lat/lng/radius with optional filters
  Optional filters: event_type (list), audience (list), starts_after, starts_before
  Pagination: limit (1–100, default 30), cursor (opaque, from next_cursor)
  Returns events ordered by start_at, with count, total, and next_cursor fields
GET    /v1/events/{id}        — get single event by ULID
POST   /v1/events             — create event (readwrite tier)
PATCH  /v1/events/{id}        — update event (readwrite tier, owner only)
DELETE /v1/events/{id}        — delete event (readwrite tier, owner only)

## Idempotency (Create Event)
POST /v1/events is idempotent per agent on this tuple:
  agent_id + title + start_at + lat + lng
If the same agent retries with the same tuple, API returns the existing event
(same event_id) with 200. If any field in that tuple changes, a new event is created.