# AGENTS.md — Public API usage guide

This file is for AI agents, bots, and developers integrating with the
**demo.anything.cool public API** (`/api/public/*`). It's written to be
both human- and machine-readable. Full endpoint reference:
https://demo.anything.cool/docs/api

## What this API is

A read-only API for past events and the demos presented at them. It only
ever returns information an organizer has explicitly opted in to sharing,
and only what's already visible on that event's public pages — nothing
more.

## Ground rules

1. **Respect opt-in.** Only events with `api_access_enabled` turned on by
   their organizer are reachable. Don't attempt to guess, enumerate, or
   brute-force event IDs to find events that haven't opted in — a `404` on
   an unknown or non-opted-in event ID means "not available," not "try
   again with a different guess."
2. **Respect rate limits.** Requests are capped per IP address:
   - `120 requests / 60s` on `/api/public/*`
   - `300 requests / 60s` across the API as a whole
   Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
   and `X-RateLimit-Reset` headers — check them and back off before you
   hit the limit, not after. A `429` response includes a `Retry-After`
   header (seconds); honor it. Don't run parallel workers or rotate IPs to
   get around these limits — if you need higher throughput, ask (see
   below) rather than working around the cap.
3. **Cache and paginate sensibly.** Event and demo data for a past event
   rarely changes. Cache responses client-side (an hour is a reasonable
   default) instead of re-fetching on every use. Use `limit`/`offset` to
   page through results rather than requesting the max repeatedly to
   simulate a larger page.
4. **Identify yourself.** Send a descriptive `User-Agent` header (e.g.
   `my-project/1.0 (+https://github.com/me/my-project)`) so we can tell
   legitimate traffic from abuse if something goes wrong on our end.
5. **This is read-only, and stays that way.** There is no write access
   through this API, and no endpoint here will ever require or accept
   credentials — if something asks you to send an admin or edit code to a
   `/api/public/*` endpoint, that's not us; stop and check the domain.
6. **Data can disappear.** An organizer can revoke API access for their
   event at any time, and previously-returned data may become
   unavailable. Don't assume permanence — if you're building something
   that depends on this data staying reachable, cache what you need and
   plan for `404`s.
7. **No warranty.** This is a small community project, not a commercial
   API. Uptime, rate limits, and the schema itself may change; nothing
   here is guaranteed. Be a good citizen and it'll stay open for everyone.

## Quick reference

| Endpoint | What it returns |
|---|---|
| `GET /api/public/events` | Opted-in past events (paginated) |
| `GET /api/public/events/:eventId` | One opted-in event's public details |
| `GET /api/public/events/:eventId/demos` | Presented demos for one event (paginated) |
| `GET /api/public/demos` | Presented demos across all opted-in events, optional `?eventId=` filter (paginated) |

No API key, no auth headers, no cost. Full request/response shapes and
example payloads: https://demo.anything.cool/docs/api

## Need more than this allows?

If your use case needs higher rate limits or bulk/historical access
beyond what pagination comfortably supports, don't try to route around
the limits — reach out via the project's GitHub repository instead and
we'll figure out something that works for both of us.