# BD Event API Documentation

Base URL: `https://events.gomievibes.online`

The public event catalog itself is the primary machine interface — every page serves both HTML and Markdown (`Accept: text/markdown`, see [markdown.md](markdown.md)). The JSON APIs below support the community + submission features in the web UI.

> **Machine-readable:** an [OpenAPI 3.0 spec](openapi.json) describes these endpoints for tooling. Authentication details are in [auth.md](auth.md); the Telegram bot webhook is documented in [webhooks.md](webhooks.md).

## Conventions

- All responses are JSON: `{"ok": true, ...}` or `{"ok": false, "error": "..."}`.
- Error status codes: `400` invalid action, `401` unauthorized, `404` not found, `422` validation error, `500` server error.
- Write endpoints require a CSRF token obtained from GET `bootstrap` (cookie-based session) and are rate-limited per visitor (hashed IP + visitor key). Public responses never expose raw email/Zalo.

## Community — `/api/community.php`

| Method | Params | Description |
| --- | --- | --- |
| GET | `action=bootstrap` | Returns `{ok, csrf}` — the CSRF token for this visitor session. |
| GET | `action=summary` & `event_id=N` | RSVP summary for an event (attendance counts, public attendee profiles). |
| GET | `action=comments` & `event_id=N` | Public discussion comments for an event. |
| POST | `action=rsvp`, `event_id`, `status=going\|interested\|none`, profile fields | Set your attendance status for an event (creates a private profile on first use). |
| POST | `action=comment`, `event_id`, `intent=find_companion\|networking\|question\|review`, `body` | Post a public comment (requires an RSVP profile; `review` only on past events). |

## Submissions — `/api/submissions.php`

Suggest an event by pasting its URL; an AI assistant extracts facts, an admin reviews, then it is published.

| Method | Params | Description |
| --- | --- | --- |
| POST | `action=submit`, `url=https://...` | Validates the URL (SSRF-protected), extracts event facts, returns `{ok, submission_id, status: processing\|published\|duplicate\|needs_review, event_id?}`. |
| GET | `id={submission_id}` | Poll the submission's status/preview (own submissions only). |

## Subscriptions — `/api/subscriptions.php`

| Method | Params | Description |
| --- | --- | --- |
| POST | `action=subscribe`, `event_id=N`, `email=...`, `notify_registration=1`, `notify_updates=1` | Subscribe an email to notifications for one event (explicit consent; stored hashed; unsubscribe supported). |

## Telegram webhook — `/api/telegram.php`

Private endpoint for the BD Event Telegram bot. Requires header `X-Telegram-Bot-Api-Secret-Token` matching the configured webhook secret; returns `401` otherwise. Accepts standard Telegram `update` payloads: a message containing a link triggers event extraction, an image stores a flyer, plain text is saved as notes.

## Developer notes

- Read-only, no-CSRF access to catalog data: use `/` and `/secc.php` with `Accept: text/markdown`, or `/sitemap.xml` for the URL list.
- The SQLite database at `/data/` is never served publicly (blocked by nginx).
- Contact: see the [contact page](/contact).