API Reference

Idempotency

POST endpoints support idempotent requests via the Idempotency-Key header. This prevents duplicate resource creation on network retries.

How it works

Send an Idempotency-Key header with a unique string (UUID recommended). If the same key is sent again with the same request body, the API returns the cached response instead of creating a duplicate.

curl -X POST \
  -H "Authorization: Bearer INTERVALS_PARTNER_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"name": "Saturday 5K", "type": "race", "date": "2026-03-15", "slug": "saturday-5k"}' \
  https://api.intervals.run/v1/partner/events

Conflict detection

If the same idempotency key is sent with a different request body, the API returns a 409 Conflict error. This protects against accidental key reuse across different operations.

{
  "error": {
    "code": "CONFLICT",
    "message": "Idempotency key already used with different request body"
  }
}

Supported endpoints

The following POST endpoints accept an Idempotency-Key header.

POST /events
POST /events/:id/participants