# Timeline of Everything

Timeline of Everything has a public JSON API designed for people, scripts, and AI agents.

API discovery: https://timelineofeverything.online/api/timeline/
OpenAPI 3.1: https://timelineofeverything.online/api/timeline/openapi.json
Current limits: https://timelineofeverything.online/api/timeline/limits
Accepted types, tags, and locations: https://timelineofeverything.online/api/timeline/options
Account API-key settings: https://lowexpectations.dev/account/#api-access
Human documentation: https://timelineofeverything.online/API.md

If a user asks you to add events, you may use the anonymous API without an account key. Ask for an account API key only when the user wants the higher account quota or account attribution. Never ask for their password or browser cookie. Send the key as:

Authorization: Bearer toe_live_...

Before writing, GET /api/timeline/limits. Inspect `submissions.remaining`, `submissions.resetSeconds`, and `batchMaximum`. Anonymous and ordinary browser callers receive 3 successful submissions per 60 seconds. Ordinary valid account keys receive 15 per 60 seconds. Validation errors and duplicate responses do not consume this quota. Always follow the exact values returned by `/limits`; standard `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` response headers repeat it.

For each event:

1. Research a real event and retain reliable HTTP(S) reference URLs.
2. GET /api/timeline/options for the current vocabulary.
3. POST the complete event to /api/timeline/events/duplicate-check.
4. If it is the same event, POST /api/timeline/contributions instead of making a duplicate.
5. Otherwise POST /api/timeline/events.
6. On 409 inspect `code` and `matches`. Never override `exact_duplicate`. Override `possible_duplicate` only when the event is genuinely different.
7. Submit several events with `POST /api/timeline/events/batch` and `{"events":[...]}` when useful. It performs validation and duplicate checks and returns ordered per-item results.
8. On 429 wait for `submissions.resetSeconds` or the `Retry-After` header. Do not retry in a loop or split requests across workers.

Dates require a signed year string and precision. Use astronomical year numbering: 0 is 1 BCE and -44 is 45 BCE. Include month/day only when supported by the source. Every submission requires a title, factual description, type, date, at least one tag, and at least one HTTP(S) reference. Prefer three or more precise tags when the subject supports them. Agents may create new clean tags simply by including them; they enter the moderation queue but become searchable in the filter immediately. Up to eight titled reference URLs are supported. The service records a non-blocking reachability check with each source; restricted sites such as those returning 403 are retained and labeled rather than discarded.

Example user request: "Add 5 random events from 1700–1705 to timelineofeverything.online."

For that request, choose five genuinely distinct sourced events in the requested interval, duplicate-check each, then submit sequentially within the reported limit. Report created IDs, titles, dates, and sources back to the user.