Community Swap API
Version 1 · Download OpenAPI 3 JSON
Base path: /api/v1. Browse anonymously. Mutations require a matching Origin header, except the Meta webhook, which requires a signature over its raw body. Verified sessions use the HttpOnly swap_session cookie.
Import the contract into Swagger Editor, Postman or your client generator for complete request and response schemas.
| Method | Path | Purpose |
|---|---|---|
| GET | /health | Application and database health |
| GET | /openapi.json | This OpenAPI document |
| GET | /communities | List geographic namespaces and database feature flags |
| GET | /listings | Anonymous nearest-first inventory; overlapping communities share listings |
| POST | /listings | Post a free item at the saved location; expires in exactly seven days |
| GET | /listings/{id} | Get a visible listing without identity or exact coordinates |
| PATCH | /listings/{id} | Owner edits description; expiration stays unchanged; translation regenerated |
| DELETE | /listings/{id} | Owner marks item gone; irreversible through API |
| PATCH | /listings/{id}/status | Owner changes state: available ↔ reserved → gone |
| POST | /listings/{id}/contact | Verified, rate-limited contact handoff; demo returns no external URL |
| POST | /listings/{id}/report | Report once per verified user; three distinct reports hide listing |
| POST | /reports | Report a listing (alias) |
| GET | /me | Private profile including own exact location and nonexpired inventory |
| PUT | /me/location | Save private pickup location and stable coarse public area |
| POST | /auth/development/start | Localhost only: begin simulated provider verification; sets HttpOnly challenge cookie |
| POST | /auth/development/verify | Consume single-use challenge bound to browser cookie; sets session |
| POST | /auth/telegram | Validate Telegram signed Login Widget proof (5 minute age; no replay); sets session |
| POST | /auth/whatsapp | Request WhatsApp OTP; alias of /auth/whatsapp/start |
| POST | /auth/whatsapp/start | Send a five-minute OTP and set HttpOnly swap_whatsapp_challenge cookie; max three sends per phone/hour |
| POST | /auth/whatsapp/verify | Consume OTP using originating browser cookie; five attempts maximum; sets session cookie |
| GET | /whatsapp/webhook | Meta subscription challenge; verify token required |
| POST | /whatsapp/webhook | Signed raw-body Meta messages webhook; no browser Origin required; duplicates ignored |
| POST | /auth/logout | Revoke current session and clear cookie |