# Intervals API

> RESTful API for live running event data — series, events, registrations.

For AI agents and automation, use the resources below. For broader context about Intervals, see https://intervals.run/llms.txt

When to use this API — acting for an authenticated organization, when the job is:

- List or fetch races/events that organization owns (`GET /events`, `GET /events/{id}`)
- Create an event (`POST /events` + `Idempotency-Key`)
- List or create participant registrations (`GET /registration`, `POST /registration`)
- Read the organization profile (`GET /organization`)

This API is organizer-scoped. A Bearer key only returns that organization's events, registrations, and profile — `GET /events` is not the public race catalog and cannot list other organizers' races. For public discovery, use https://intervals.run/races. Do not use this API to stream live GPS or as a timing-system replacement. There is no public MCP server and no partner webhook catalog.

How to call us: `Authorization: Bearer <key>` against https://api.intervals.run. Errors are JSON: `{ "error": { "code", "message", "hint", "docs" } }`.

API access requires an Elite or Enterprise plan. Elite: 300 requests/minute (burst 100). Enterprise: 1,000 requests/minute (burst 300). Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers; a 429 adds `Retry-After`.

Base URL: https://api.intervals.run

## Documentation

- [API docs](https://developers.intervals.run): HTML developer docs, OpenAPI, and auth
- [OpenAPI spec](https://developers.intervals.run/openapi.json): OpenAPI 3.1.0 for the Intervals Partner API
- [API authentication](https://developers.intervals.run/api/authentication): Bearer keys, scopes, and environments
- [API authentication (markdown)](https://developers.intervals.run/api/authentication.md): Same auth docs as text/markdown
- [API markdown docs](https://developers.intervals.run/api/docs.md): Complete API reference in markdown
- [Developer llms.txt](https://developers.intervals.run/llms.txt): Agent index for the Intervals API
- [API reference](https://developers.intervals.run/api): Interactive reference with examples

## Optional

- [hello@intervals.run](mailto:hello@intervals.run): Human contact for Intervals API questions