Intervals Developers
API Reference
Sign inGet API key
IntroductionAuthenticationErrorsPaginationRate LimitsIdempotency

Endpoints

GETYour organizationGETAll eventsGETRetrieve an eventPOSTCreate an eventGETAll registrationsPOSTRegister a participantGETAll recurrencesGETAll collectionsGETRetrieve a collectionGETEvents in a collection
Changelog
Sign inGet API key

API Reference

Errors

The API uses conventional HTTP status codes and returns a machine-readable error code in a consistent JSON shape.

Status codes

200Success
201Created
400Bad Request
401Unauthorized
402Plan limit reached
403Forbidden (missing scope)
404Not Found
409Conflict
422Validation Error
429Rate Limited
500Internal Error

Error shape

Every error response has a top-level error object with a machine-readable code, a human-readable message, and — for validation failures — a field-keyed errors map.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "errors": {
      "email": ["Invalid email address"]
    }
  }
}

Error codes

Branch on error.code — the value is stable across releases.

CodeStatusWhen it happens
UNAUTHORIZED401Missing or invalid API key.
FORBIDDEN403The key lacks the scope this endpoint requires.
API_ACCESS_REQUIRED403The organization's plan doesn't include API access — upgrade to Elite or Enterprise.
IDEMPOTENCY_KEY_REQUIRED400A POST endpoint was called without a required Idempotency-Key header.
BAD_REQUEST400Malformed JSON body, or an unrecognized Intervals-Version header.
NOT_FOUND404The resource doesn't exist, or belongs to another organization.
VALIDATION_ERROR422Query params or body failed validation — see the errors map.
INVALID_PACE_GROUP422The paceGroup isn't one the event declares.
PAID_RUN_REQUIRES_CHECKOUT422The run is sold through Intervals checkout — register for it via the native flow, not the API. The API registers free runs only.
CONFLICT409An Idempotency-Key was reused with a different request body. Don't retry — fix the key.
IDEMPOTENCY_KEY_IN_PROGRESS409A request with the same Idempotency-Key is still in flight. Safe to retry shortly.
ALREADY_REGISTERED409That email is already registered for the event run.
PLAN_LIMIT_EXCEEDED402A plan entitlement was exceeded. Upgrade to raise the limit.
RATE_LIMIT_EXCEEDED429Too many requests — retry after the Retry-After header.
INTERNAL_ERROR500Unexpected server error. Retry; if it persists, contact support with the request id.

Request IDs

Every response includes an X-Request-Id header. Include it when contacting support so we can trace the exact request.

Common errors

Invalid API key (401)

Check that your key is active and the Bearer prefix is included in the Authorization header.

Missing scope (403)

Your key doesn’t have the scope this endpoint requires. Check the endpoint’s required scope and add it to your key in the manage portal.

Rate limited (429)

Wait the number of seconds in the Retry-After response header, then retry with exponential backoff. See the Rate Limits page for per-plan allowances.

AuthenticationPagination