{ "openapi": "3.0.3", "info": { "title": "Get Races", "description": "List of upcoming races.", "version": "1.0.0", "contact": { "name": "RunSignup API Support", "url": "https://runsignup.com/API", "email": "info@runsignup.com" } }, "servers": [ { "url": "https://api.runsignup.com/rest", "description": "Production API Server" } ], "tags": [ { "name": "Basic Race Information", "description": "APIs related to Basic Race Information" } ], "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "type": "object", "description": "Additional error details", "additionalProperties": true } }, "required": [ "error" ] }, "BadRequestError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "description": "Error indicating invalid request parameters or structure" } ] }, "UnauthorizedError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "description": "Error indicating authentication failure" } ] }, "ForbiddenError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "description": "Error indicating the authenticated user lacks required permissions" } ] }, "NotFoundError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "description": "Error indicating the requested resource does not exist" } ] }, "ServerError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "description": "Error indicating an unexpected server-side issue" } ] }, "RacesGetResponse": { "type": "object", "title": "Races List Response", "description": "Response schema for a list of races with detailed information", "properties": { "races": { "type": "array", "description": "List of races", "items": { "type": "object", "description": "Race entry with detailed information", "properties": { "race": { "type": "object", "description": "Detailed information about the race", "properties": { "race_id": { "type": "integer", "description": "Unique identifier for the race" }, "name": { "type": "string", "description": "Name of the race" }, "last_date": { "type": "string", "description": "Date when the race last occurred", "nullable": true, "format": "date" }, "last_end_date": { "type": "string", "description": "End date of the last race occurrence", "nullable": true, "format": "date" }, "next_date": { "type": "string", "description": "Date when the race will next occur", "nullable": true, "format": "date" }, "next_end_date": { "type": "string", "description": "End date of the next race occurrence", "nullable": true, "format": "date" }, "is_draft_race": { "type": "string", "description": "Whether the race is in draft status", "enum": [ "T", "F" ] }, "is_private_race": { "type": "string", "description": "Whether the race is private", "enum": [ "T", "F" ] }, "is_registration_open": { "type": "string", "description": "Whether registration is currently open", "enum": [ "T", "F" ] }, "created": { "type": "string", "description": "Date and time when the race was created", "format": "date-time" }, "last_modified": { "type": "string", "description": "Date and time when the race was last modified", "format": "date-time" }, "description": { "type": "string", "description": "HTML description of the race" }, "url": { "type": "string", "description": "URL to the race page" }, "external_race_url": { "type": "string", "description": "URL to an external race page, if applicable", "nullable": true }, "external_results_url": { "type": "string", "description": "URL to external race results, if applicable", "nullable": true }, "fb_page_id": { "type": "string", "description": "Facebook page ID associated with the race", "nullable": true }, "fb_event_id": { "type": "integer", "description": "Facebook event ID associated with the race", "nullable": true }, "address": { "type": "object", "description": "Location information for the race", "properties": { "street": { "type": "string", "description": "Street address of the race" }, "street2": { "type": "string", "description": "Additional street address information", "nullable": true }, "city": { "type": "string", "description": "City where the race is located" }, "state": { "type": "string", "description": "State or province where the race is located" }, "zipcode": { "type": "string", "description": "Postal code where the race is located" }, "country_code": { "type": "string", "description": "Two-letter country code" } }, "required": [ "street", "city", "state", "zipcode", "country_code" ] }, "timezone": { "type": "string", "description": "Timezone of the race location" }, "logo_url": { "type": "string", "description": "URL to the race logo image" }, "real_time_notifications_enabled": { "type": "string", "description": "Whether real-time notifications are enabled for the race", "enum": [ "T", "F" ] }, "waiver": { "type": "string", "description": "Race waiver text. Present when include_waiver=T", "x-response-field-inclusion": [ { "request-parameter": "include_waiver", "value": "T" } ] }, "waivers": { "type": "array", "description": "Array of race waivers. Present when include_multiple_waivers=T", "x-response-field-inclusion": [ { "request-parameter": "include_multiple_waivers", "value": "T" } ], "items": { "type": "object", "description": "Individual race waiver", "properties": { "waiver_id": { "type": "integer", "description": "Unique identifier for the waiver" }, "waiver_text": { "type": "string", "description": "Text content of the waiver" } }, "required": [ "waiver_id", "waiver_text" ] } }, "race_event_days": { "type": "array", "description": "Historical and scheduled race dates. Present when include_event_days=T", "x-response-field-inclusion": [ { "request-parameter": "include_event_days", "value": "T" } ], "items": { "type": "object", "description": "Individual race event day", "properties": { "race_event_days_id": { "type": "integer", "description": "Unique identifier for the race event day" }, "start_date": { "type": "string", "description": "Start date of the race event" }, "end_date": { "type": "string", "description": "End date of the race event" } }, "required": [ "race_event_days_id", "start_date", "end_date" ] } }, "postponed_cancelled_text": { "type": "string", "description": "Text describing race cancellation. Present when include_extra_date_info=T", "x-response-field-inclusion": [ { "request-parameter": "include_extra_date_info", "value": "T" } ] }, "postponed_to_date_text": { "type": "string", "description": "Text describing race postponement date. Present when include_extra_date_info=T", "x-response-field-inclusion": [ { "request-parameter": "include_extra_date_info", "value": "T" } ] }, "headings": { "type": "array", "description": "Race headings and content sections. Present when race_headings=T", "nullable": true, "x-response-field-inclusion": [ { "request-parameter": "race_headings", "value": "T" } ], "items": { "type": "object", "description": "Race heading information", "properties": { "heading_text": { "type": "string", "description": "Heading title text" }, "content": { "type": "string", "description": "HTML content for the heading", "nullable": true } }, "required": [ "heading_text" ] } }, "links": { "type": "array", "description": "Race links and descriptions. Present when race_links=T", "nullable": true, "x-response-field-inclusion": [ { "request-parameter": "race_links", "value": "T" } ], "items": { "type": "object", "description": "Race link information", "properties": { "link_text": { "type": "string", "description": "Text for the link" }, "url": { "type": "string", "description": "URL the link points to" }, "description": { "type": "string", "description": "HTML description of the link", "nullable": true } }, "required": [ "link_text", "url" ] } }, "events": { "type": "array", "description": "List of events associated with the race. Present when events=T", "x-response-field-inclusion": [ { "request-parameter": "events", "value": "T" } ], "items": { "type": "object", "description": "Race event information", "properties": { "event_id": { "type": "integer", "description": "Unique identifier for the event" }, "race_event_days_id": { "type": "integer", "description": "Identifier for the race event day" }, "name": { "type": "string", "description": "Name of the event" }, "details": { "type": "string", "description": "Detailed description of the event", "nullable": true }, "start_time": { "type": "string", "description": "Start time of the event" }, "end_time": { "type": "string", "description": "End time of the event", "nullable": true }, "age_calc_base_date": { "type": "string", "description": "Base date for age calculations", "nullable": true }, "registration_opens": { "type": "string", "description": "When registration opens for the event", "nullable": true }, "event_type": { "type": "string", "description": "Type of event" }, "distance": { "type": "string", "description": "Distance of the event", "nullable": true }, "volunteer": { "type": "string", "description": "Whether this is a volunteer event", "enum": [ "T", "F" ] }, "require_dob": { "type": "string", "description": "Whether date of birth is required", "enum": [ "T", "F" ] }, "require_phone": { "type": "string", "description": "Whether phone number is required", "enum": [ "T", "F" ] }, "registration_periods": { "type": "array", "description": "List of registration periods for the event", "items": { "type": "object", "description": "Registration period information", "properties": { "registration_opens": { "type": "string", "description": "When registration opens for this period" }, "registration_closes": { "type": "string", "description": "When registration closes for this period" }, "race_fee": { "type": "string", "description": "Fee for the race during this period", "format": "currency", "x-currency-symbol": "$", "x-decimal-places": 2, "pattern": "^\\$\\d+\\.\\d{2}$" }, "processing_fee": { "type": "string", "description": "Processing fee during this period", "format": "currency", "x-currency-symbol": "$", "x-decimal-places": 2, "pattern": "^\\$\\d+\\.\\d{2}$" } }, "required": [ "registration_opens", "registration_closes", "race_fee", "processing_fee" ] } }, "giveaway": { "type": "string", "description": "Giveaway item for the event", "nullable": true }, "giveaway_cutoff_date": { "type": "string", "description": "Cutoff date for giveaway eligibility. Present when include_giveaway_details=T", "nullable": true, "x-response-field-inclusion": [ { "request-parameter": "include_giveaway_details", "value": "T" } ] }, "giveaway_options": { "type": "array", "description": "List of available giveaway options for the event. Present when include_giveaway_details=T", "nullable": true, "x-response-field-inclusion": [ { "request-parameter": "include_giveaway_details", "value": "T" } ], "items": { "type": "object", "description": "Giveaway option information", "properties": { "giveaway_option_id": { "type": "integer", "description": "Unique identifier for the giveaway option" }, "giveaway_option_text": { "type": "string", "description": "Text description of the giveaway option" }, "additional_cost": { "type": "string", "description": "Additional cost for this giveaway option", "format": "currency", "x-currency-symbol": "$", "x-decimal-places": 2, "pattern": "^\\$\\d+\\.\\d{2}$" }, "giveaway_option_inventory_id": { "type": "integer", "description": "Inventory identifier for the giveaway option", "nullable": true } }, "required": [ "giveaway_option_id", "giveaway_option_text", "additional_cost" ] } } }, "required": [ "event_id", "race_event_days_id", "name", "start_time", "event_type", "volunteer", "require_dob", "require_phone", "registration_periods" ] } } }, "required": [ "race_id", "name", "is_draft_race", "is_private_race", "is_registration_open", "created", "last_modified", "description", "url", "address", "timezone", "real_time_notifications_enabled" ] } }, "required": [ "race" ] } } }, "required": [ "races" ], "example": { "races": [ { "race": { "race_id": 5606, "name": "PHP Unit Complex Partner Race", "last_date": null, "last_end_date": null, "next_date": "03/03/2033", "next_end_date": "03/03/2033", "is_draft_race": "F", "is_private_race": "F", "is_registration_open": "T", "created": "8/27/2020 07:37", "last_modified": "11/15/2021 14:54", "description": "

PHP Unit

", "url": "http://example.com/Race/NJ/Moorestown/PHPUnitComplexPartnerRace", "external_race_url": null, "external_results_url": null, "fb_page_id": null, "fb_event_id": null, "address": { "street": "300 Mill St", "street2": null, "city": "Moorestown", "state": "NJ", "zipcode": "08057", "country_code": "US" }, "timezone": "America/New_York", "real_time_notifications_enabled": "F", "waivers": [ { "waiver_id": 1, "waiver_text": "Main race waiver text..." }, { "waiver_id": 2, "waiver_text": "Additional waiver text..." } ], "race_event_days": [ { "race_event_days_id": 334879, "start_date": "6/14/2025 00:00", "end_date": "6/14/2025 00:00" }, { "race_event_days_id": 274224, "start_date": "8/10/2024 00:00", "end_date": "8/10/2024 00:00" }, { "race_event_days_id": 235666, "start_date": "8/12/2023 00:00", "end_date": "8/12/2023 00:00" } ], "events": [ { "event_id": 12345, "race_event_days_id": 334879, "name": "5K Run", "details": "A scenic 5K run through the park", "start_time": "8:00 AM", "end_time": "10:00 AM", "age_calc_base_date": "6/14/2025", "registration_opens": "1/1/2025 12:00 AM", "event_type": "Running", "distance": "5K", "volunteer": "F", "require_dob": "T", "require_phone": "T", "registration_periods": [ { "registration_opens": "1/1/2025 12:00 AM", "registration_closes": "6/13/2025 11:59 PM", "race_fee": "$25.00", "processing_fee": "$2.50" } ], "giveaway": "Race T-Shirt", "giveaway_cutoff_date": "5/1/2025", "giveaway_options": [ { "giveaway_option_id": 1, "giveaway_option_text": "Long Sleeve T-Shirt", "additional_cost": "$5.00", "giveaway_option_inventory_id": 101 }, { "giveaway_option_id": 2, "giveaway_option_text": "Hoodie", "additional_cost": "$15.00", "giveaway_option_inventory_id": 102 } ] } ] } } ] } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "query", "name": "api_key", "description": "RunSignup API Key" }, "apiSecret": { "type": "apiKey", "in": "query", "name": "api_secret", "description": "RunSignup API Secret" } } }, "paths": { "/races": { "get": { "tags": [ "Basic Race Information" ], "summary": "Get Races", "description": "List of upcoming races.", "operationId": "races", "parameters": [ { "name": "api_key", "in": "query", "description": "API Key", "required": false, "schema": { "type": "string" } }, { "name": "api_secret", "in": "query", "description": "API Secret", "required": false, "schema": { "type": "string" } }, { "name": "rsu_api_key", "in": "query", "description": "API v2 key. If used, you must send the API secret in an HTTP header named X-RSU-API-SECRET.", "required": false, "schema": { "type": "string" } }, { "name": "sp_api_key", "in": "query", "description": "Super partner API key. If used, you must send the API secret in an HTTP header named X-RSU-API-SECRET.", "required": false, "schema": { "type": "string" } }, { "name": "X-RSU-API-SECRET", "in": "header", "description": "API v2 or super partner secret.", "required": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Authorization Header. If using OAuth 2.0, fill this in with `Bearer `.", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Format of response. The default if not sent is `xml`, but `json` is preferred.", "required": false, "schema": { "type": "string", "enum": [ "xml", "json", "csv" ], "default": "xml" } }, { "name": "aflt_token", "in": "query", "description": "If set, this affiliate token will be appended to race URLs.", "required": false, "schema": { "type": "string" } }, { "name": "events", "in": "query", "description": "Includes race events in the output.", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "race_headings", "in": "query", "description": "Include race headings in the output.", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "race_links", "in": "query", "description": "Include race links in the output.", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "include_waiver", "in": "query", "description": "Should waiver be included?", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "include_multiple_waivers", "in": "query", "description": "Should multiple waivers be included?", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "include_event_days", "in": "query", "description": "Should information on events days (e.g. each race year) be included?", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "include_extra_date_info", "in": "query", "description": "Should extra information about cancellations and postponements be included?", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "include_giveaway_details", "in": "query", "description": "Should detailed giveaway information be included?", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "page", "in": "query", "description": "Page number to get.", "required": false, "schema": { "type": "integer", "default": "1" } }, { "name": "results_per_page", "in": "query", "description": "Number of results per page.", "required": false, "schema": { "type": "integer", "default": "50" } }, { "name": "sort", "in": "query", "description": "Sort by \"name\", \"date\", or \"end_date\" in ascending (\"ASC\") or descending (\"DESC\") order.", "required": false, "schema": { "type": "string", "default": "name ASC" } }, { "name": "name", "in": "query", "description": "Search by race name.", "required": false, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Searches for races that occur on or after a given date.", "required": false, "schema": { "type": "string", "default": "today" } }, { "name": "end_date", "in": "query", "description": "Searches for races that occur on or before a given date.", "required": false, "schema": { "type": "string" } }, { "name": "created_since", "in": "query", "description": "Searches for races that were created on or after a given date.", "required": false, "schema": { "type": "string" } }, { "name": "created_on_or_before", "in": "query", "description": "Searches for races that were created on or before a given date.", "required": false, "schema": { "type": "string" } }, { "name": "modified_since", "in": "query", "description": "Searches for races that were modified on or after a given date.", "required": false, "schema": { "type": "string" } }, { "name": "modified_on_or_before", "in": "query", "description": "Searches for races that were modified on or before a given date.", "required": false, "schema": { "type": "string" } }, { "name": "only_partner_races", "in": "query", "description": "Only get races linked to the partner using the API.", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "search_start_date_only", "in": "query", "description": "Only search race races based on start date, not end date.", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "only_races_with_results", "in": "query", "description": "Only get races that have results.", "required": false, "schema": { "type": "boolean", "enum": [ "T", "F" ], "default": "F" } }, { "name": "city", "in": "query", "description": "Search by city.", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Search by state.", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "Search by country.", "required": false, "schema": { "type": "string", "enum": [ "US", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ] } }, { "name": "event_type", "in": "query", "description": "Get races by event type.", "required": false, "schema": { "type": "string", "enum": [ "running_race", "virtual_race", "nonprofit_event", "running_only", "walking_only", "race_walk", "wheelchair", "triathlon", "duathlon", "bike_race", "bike_ride", "mountain_bike_race", "gravel_grinder", "fundraising_ride", "trail_race", "open_course_trail", "ultra", "hike", "obstacle_course", "adventure_race", "swim", "swim_run", "aqua_bike", "ski", "paddle_sports", "disc_golf", "clinic", "expo", "skate", "ruck", "other" ] } }, { "name": "min_distance", "in": "query", "description": "Minimum race distance to get.", "required": false, "schema": { "type": "number" } }, { "name": "max_distance", "in": "query", "description": "Maximum race distance to get.", "required": false, "schema": { "type": "number" } }, { "name": "distance_units", "in": "query", "description": "Units to use with distance.", "required": false, "schema": { "type": "string", "enum": [ "K", "M", "y", "m" ], "default": "K" } }, { "name": "zipcode", "in": "query", "description": "Searches for races within radius(required) miles from zipcode. US Only.", "required": false, "schema": { "type": "string" } }, { "name": "radius", "in": "query", "description": "Searches for races within radius miles from zipcode(required).", "required": false, "schema": { "type": "integer" } } ], "security": [ { "apiKey": [], "apiSecret": [] } ], "responses": { "200": { "description": "Races List Response - Response schema for a list of races with detailed information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RacesGetResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } }, "x-permissions": [ "affiliates", "partners", "race_directors", "timers" ] } } } }