{"openapi":"3.1.0","info":{"title":"Intervals API","version":"1.0.0","description":"API for integrations with Intervals. Manage events, series, and participants programmatically."},"servers":[{"url":"https://api.intervals.run","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/organization":{"get":{"operationId":"getOrganization","summary":"Your organization","description":"Retrieve the organization associated with your API key. Useful for verifying your credentials and checking your org profile.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"_id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Organization name"},"slug":{"type":"string","description":"URL slug"},"roles":{"type":"array","items":{"type":"string","enum":["organizer","sponsor","federation"]},"description":"Organization roles"},"plan":{"type":"string","enum":["free","premium","enterprise"],"description":"Subscription plan"}},"required":["_id","name","slug","roles","plan"],"additionalProperties":false,"description":"Organization details"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series":{"get":{"operationId":"listSeries","summary":"All series","description":"Retrieve a list of event series for your organization. Filter by slug to find a specific series. Series represent recurring events like weekly runs or monthly races.","tags":["Series"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"slug","schema":{"description":"Filter by URL slug (returns single result)","type":"string"},"description":"Filter by URL slug (returns single result)"},{"in":"query","name":"limit","schema":{"description":"Maximum number of series to return (1-100)","type":"integer","minimum":1,"maximum":100},"description":"Maximum number of series to return (1-100)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Series ID"},"name":{"type":"string","description":"Series name"},"slug":{"type":"string","description":"URL slug"},"organizationId":{"type":"string","description":"Owning organization ID"},"status":{"type":"string","enum":["active","paused","archived"],"description":"Series status"},"type":{"type":"string","enum":["runClub","raceSeries","parkrun","timeTrial"],"description":"Series type"},"description":{"description":"Series description","type":"string"},"address":{"description":"Series location","$ref":"#/components/schemas/AddressOutput"},"lat":{"description":"Latitude","type":"number"},"lng":{"description":"Longitude","type":"number"},"timezone":{"type":"string","description":"IANA timezone"},"schedule":{"type":"object","properties":{"frequency":{"type":"string","enum":["weekly","biweekly","monthly","custom"],"description":"Recurrence frequency"},"dayOfWeek":{"description":"Day of week (0=Sun, 6=Sat)","type":"integer","minimum":0,"maximum":6},"dayOfMonth":{"description":"Day of month (1-31)","type":"integer","minimum":1,"maximum":31},"startTime":{"type":"string","description":"Start time (HH:MM)"},"durationMinutes":{"description":"Duration in minutes","type":"number"}},"required":["frequency","startTime"],"additionalProperties":false,"description":"Schedule configuration"}},"required":["_id","name","slug","organizationId","status","type","timezone","schedule"],"additionalProperties":false},"description":"List of event series"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"All events","description":"Retrieve a list of events for your organization. Filter by type, series, or date range to narrow results.","tags":["Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"description":"Maximum number of events to return (1-100)","type":"integer","minimum":1,"maximum":100},"description":"Maximum number of events to return (1-100)"},{"in":"query","name":"type","schema":{"description":"Filter by event type","type":"string","enum":["race","runClub","timeTrial","other"]},"description":"Filter by event type"},{"in":"query","name":"seriesId","schema":{"description":"Filter by parent series ID","type":"string"},"description":"Filter by parent series ID"},{"in":"query","name":"dateFrom","schema":{"description":"Filter events on or after this date (YYYY-MM-DD)","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"description":"Filter events on or after this date (YYYY-MM-DD)"},{"in":"query","name":"dateTo","schema":{"description":"Filter events on or before this date (YYYY-MM-DD)","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"description":"Filter events on or before this date (YYYY-MM-DD)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Event ID"},"name":{"type":"string","description":"Event name"},"slug":{"type":"string","description":"URL slug"},"type":{"type":"string","enum":["race","runClub","timeTrial","other"],"description":"Event type"},"date":{"type":"string","description":"Event date (YYYY-MM-DD)"},"organizationId":{"type":"string","description":"Owning organization ID"},"seriesId":{"description":"Parent series ID","type":"string"},"startTime":{"description":"Start time (HH:MM)","type":"string"},"address":{"description":"Event location","$ref":"#/components/schemas/AddressOutput"},"lat":{"description":"Latitude","type":"number"},"lng":{"description":"Longitude","type":"number"},"description":{"description":"Event description","type":"string"},"websiteUrl":{"description":"Event website URL","type":"string"},"registrationUrl":{"description":"Registration page URL","type":"string"}},"required":["_id","name","slug","type","date","organizationId"],"additionalProperties":false},"description":"List of events"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createEvent","summary":"Create an event","description":"Add a new event to your organization. Supports idempotent requests via the Idempotency-Key header.","tags":["Events"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Event name"},"slug":{"type":"string","minLength":1,"description":"URL-friendly slug (must be unique within org)"},"type":{"type":"string","enum":["race","runClub","timeTrial","other"],"description":"Event type"},"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","description":"Event date (YYYY-MM-DD)"},"seriesId":{"description":"Parent event series ID","type":"string"},"endDate":{"description":"End date for multi-day events (YYYY-MM-DD)","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"startTime":{"description":"Start time (HH:MM or HH:MM:SS)","type":"string"},"endTime":{"description":"End time (HH:MM or HH:MM:SS)","type":"string"},"address":{"description":"Event location","$ref":"#/components/schemas/Address"},"lat":{"description":"Latitude","type":"number","minimum":-90,"maximum":90},"lng":{"description":"Longitude","type":"number","minimum":-180,"maximum":180},"description":{"description":"Event description","type":"string"},"websiteUrl":{"description":"Event website URL","type":"string","format":"uri"},"registrationUrl":{"description":"Registration page URL","type":"string","format":"uri"}},"required":["name","slug","type","date"]}}}},"responses":{"201":{"description":"Event created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string","description":"ID of the created event"}},"required":["eventId"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"operationId":"getEvent","summary":"Retrieve an event","description":"Retrieve a single event along with its associated runs (distance variants), including event details and an array of event runs.","tags":["Events"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","schema":{"type":"string","minLength":1,"description":"The event ID"},"required":true,"description":"The event ID"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"event":{"type":"object","properties":{"_id":{"type":"string","description":"Event ID"},"name":{"type":"string","description":"Event name"},"slug":{"type":"string","description":"URL slug"},"type":{"type":"string","enum":["race","runClub","timeTrial","other"],"description":"Event type"},"date":{"type":"string","description":"Event date (YYYY-MM-DD)"},"organizationId":{"type":"string","description":"Owning organization ID"},"seriesId":{"description":"Parent series ID","type":"string"},"startTime":{"description":"Start time (HH:MM)","type":"string"},"address":{"description":"Event location","$ref":"#/components/schemas/AddressOutput"},"lat":{"description":"Latitude","type":"number"},"lng":{"description":"Longitude","type":"number"},"description":{"description":"Event description","type":"string"},"websiteUrl":{"description":"Event website URL","type":"string"},"registrationUrl":{"description":"Registration page URL","type":"string"},"endDate":{"description":"End date for multi-day events (YYYY-MM-DD)","type":"string"},"endTime":{"description":"End time (HH:MM)","type":"string"}},"required":["_id","name","slug","type","date","organizationId"],"additionalProperties":false,"description":"Event details"},"runs":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Event run ID"},"eventId":{"type":"string","description":"Parent event ID"},"distanceMeters":{"type":"number","description":"Distance in meters"},"distanceStandard":{"type":"string","enum":["5K","10K","15K","Half Marathon","Marathon","50K","50M","100K","100M","Ultra","Other"],"description":"Standard distance label"},"distanceLabel":{"type":"string","description":"Display label for the distance"},"date":{"type":"string","description":"Run date (YYYY-MM-DD)"},"startTime":{"description":"Start time (HH:MM)","type":"string"},"eventStatus":{"description":"Run status","type":"string","enum":["scheduled","cancelled","postponed","rescheduled"]},"registrationUrl":{"description":"Registration URL","type":"string"},"registrationStatus":{"description":"Registration status","type":"string","enum":["open","closed","sold_out","unknown"]},"maxParticipants":{"description":"Maximum participants","type":"number"},"isVirtual":{"description":"Whether this is a virtual run","type":"boolean"},"isRelay":{"description":"Whether this is a relay","type":"boolean"},"isWalking":{"description":"Whether this is a walking event","type":"boolean"}},"required":["_id","eventId","distanceMeters","distanceStandard","distanceLabel","date"],"additionalProperties":false},"description":"Event runs (distance variants)"}},"required":["event","runs"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/registration":{"get":{"operationId":"listRegistrations","summary":"All registrations","description":"Retrieve a list of registrations for a specific event.","tags":["Registration"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"eventId","schema":{"type":"string","minLength":1,"description":"Filter by event ID (required)"},"required":true,"description":"Filter by event ID (required)"},{"in":"query","name":"limit","schema":{"description":"Maximum number of registrations to return (1-100)","type":"integer","minimum":1,"maximum":100},"description":"Maximum number of registrations to return (1-100)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","description":"Registration ID"},"eventId":{"type":"string","description":"Event ID"},"eventRunId":{"type":"string","description":"Event run ID"},"email":{"type":"string","description":"Participant email"},"name":{"description":"Participant name","type":"string"},"registrationType":{"type":"string","enum":["free","paid"],"description":"Registration type"},"registrationStatus":{"type":"string","enum":["confirmed","cancelled","waitlist","refunded"],"description":"Registration status"},"paceGroup":{"description":"Pace group assignment","type":"string"},"bibIdentifier":{"description":"Bib number","type":"string"},"checkedIn":{"description":"Whether participant has checked in","type":"boolean"}},"required":["_id","eventId","eventRunId","email","registrationType","registrationStatus"],"additionalProperties":false},"description":"List of registrations"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"registerParticipant","summary":"Register a participant","description":"Sign up a participant for an event run. The event is derived from the event run ID.","tags":["Registration"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"eventRunId":{"type":"string","minLength":1,"description":"ID of the event run (distance) to register for"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Participant email address"},"name":{"description":"Participant display name","type":"string"},"registrationType":{"type":"string","enum":["free","paid"],"description":"Registration type"},"status":{"default":"confirmed","description":"Registration status (defaults to confirmed)","type":"string","enum":["confirmed","cancelled","waitlist","refunded"]},"paceGroup":{"description":"Pace group assignment","type":"string"},"notes":{"description":"Additional notes","type":"string"}},"required":["eventRunId","email","registrationType"]}}}},"responses":{"201":{"description":"Participant registered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"participantId":{"type":"string","description":"ID of the registered participant"}},"required":["participantId"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Event run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Address":{"type":"object","properties":{"name":{"description":"Place name (e.g. 'Copley Square')","type":"string"},"streetAddress":{"type":"string"},"addressLocality":{"type":"string","description":"City (required)"},"addressRegion":{"description":"State or province","type":"string"},"postalCode":{"type":"string"},"addressCountry":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code (e.g. 'US')"}},"required":["addressLocality","addressCountry"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"},"errors":{"description":"Field-level validation errors","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"AddressOutput":{"type":"object","properties":{"name":{"description":"Place name (e.g. 'Copley Square')","type":"string"},"streetAddress":{"type":"string"},"addressLocality":{"type":"string","description":"City (required)"},"addressRegion":{"description":"State or province","type":"string"},"postalCode":{"type":"string"},"addressCountry":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code (e.g. 'US')"}},"required":["addressLocality","addressCountry"],"additionalProperties":false}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key obtained from your organization's manage portal at Settings > API."}}}}