> For the complete documentation index, see [llms.txt](https://help.runonrufus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.runonrufus.com/public-api/specifications/events.md).

# Events

## List events

> Requires \`READ\` or \`READ\_WRITE\` api key access type.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Events"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"parameters":{"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page."},"LimitEvents":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"description":"Max items per page (events)."}},"schemas":{"EventsListResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/EventSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["description","result","pagination"]}},"required":["body"]},"EventSummary":{"type":"object","additionalProperties":false,"properties":{"event_token":{"type":"string"},"name":{"type":"string","nullable":true},"edition":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"start_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","nullable":true}},"required":["event_token"]},"Pagination":{"type":"object","additionalProperties":false,"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"required":["page","limit","total","has_more"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/events":{"get":{"tags":["Events"],"summary":"List events","description":"Requires `READ` or `READ_WRITE` api key access type.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/LimitEvents"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get event by token

> Requires \`READ\` or \`READ\_WRITE\` api key access type.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Events"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"schemas":{"EventGetResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","properties":{"description":{"type":"string"},"result":{"type":"object","description":"Event details (fields follow RRM schema; large object).","additionalProperties":true}},"required":["description"]}},"required":["body"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/events/{event_token}":{"get":{"tags":["Events"],"summary":"Get event by token","description":"Requires `READ` or `READ_WRITE` api key access type.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventGetResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## List participants by event

> Requires \`READ\` or \`READ\_WRITE\` api key access type.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Events"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"parameters":{"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page."},"LimitParticipants":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000},"description":"Max items per page (participants)."},"ParticipantBib":{"name":"bib","in":"query","required":false,"schema":{"type":"string"},"description":"Filter participants by bib."},"ParticipantChip":{"name":"chip","in":"query","required":false,"schema":{"type":"string"},"description":"Filter participants by chip."},"ParticipantRaceToken":{"name":"race_token","in":"query","required":false,"schema":{"type":"string"},"description":"Filter participants by race_token."},"ParticipantStatus":{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"Filter participants by status."}},"schemas":{"ParticipantsListResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["description","result","pagination"]}},"required":["body"]},"ParticipantSummary":{"type":"object","additionalProperties":false,"properties":{"event_token":{"type":"string"},"participant_token":{"type":"string"},"name":{"type":"string"},"lastname":{"type":"string","nullable":true},"bib":{"type":"string","nullable":true},"chip":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true},"dob":{"type":"string","format":"date-time","nullable":true},"yob":{"type":"integer","nullable":true},"country":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"age_group":{"type":"string","nullable":true},"team":{"type":"string","nullable":true},"club":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"telephone":{"type":"string","nullable":true},"group_id":{"type":"string","nullable":true},"race_token":{"type":"string","nullable":true},"custom_fields":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/CustomField"}},"individual_start_time":{"type":"string","nullable":true}},"required":["event_token","participant_token","name"]},"CustomField":{"type":"object","additionalProperties":false,"properties":{"field_name":{"type":"string"},"value":{"type":"string","nullable":true}},"required":["field_name","value"]},"Pagination":{"type":"object","additionalProperties":false,"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"required":["page","limit","total","has_more"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/events/{event_token}/participants":{"get":{"tags":["Events"],"summary":"List participants by event","description":"Requires `READ` or `READ_WRITE` api key access type.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/LimitParticipants"},{"$ref":"#/components/parameters/ParticipantBib"},{"$ref":"#/components/parameters/ParticipantChip"},{"$ref":"#/components/parameters/ParticipantRaceToken"},{"$ref":"#/components/parameters/ParticipantStatus"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantsListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Create participant

> Requires \`WRITE\` or \`READ\_WRITE\` api key access type.\
> \
> Participant corrections (PATCH/DELETE) are intentionally not exposed in the public API.<br>

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Events"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"schemas":{"CreateParticipantRequest":{"allOf":[{"$ref":"#/components/schemas/Participant"}]},"Participant":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"lastname":{"type":"string","nullable":true},"bib":{"type":"string","nullable":true},"chip":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true},"dob":{"type":"string","format":"date-time","nullable":true},"yob":{"type":"integer","nullable":true},"country":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"age_group":{"type":"string","nullable":true},"team":{"type":"string","nullable":true},"club":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"telephone":{"type":"string","nullable":true},"group_id":{"type":"string","nullable":true},"race_token":{"type":"string","nullable":true},"custom_fields":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/CustomField"}},"individual_start_time":{"type":"string","nullable":true,"description":"HH:mm:ss"}},"required":["name","bib"]},"CustomField":{"type":"object","additionalProperties":false,"properties":{"field_name":{"type":"string"},"value":{"type":"string","nullable":true}},"required":["field_name","value"]},"CreateParticipantResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"event_token":{"type":"string"},"participant_token":{"type":"string"},"result":{"type":"object","additionalProperties":true}},"required":["description","event_token","participant_token"]}},"required":["body"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"PayloadTooLarge":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/events/{event_token}/participants":{"post":{"tags":["Events"],"summary":"Create participant","description":"Requires `WRITE` or `READ_WRITE` api key access type.\n\nParticipant corrections (PATCH/DELETE) are intentionally not exposed in the public API.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateParticipantRequest"}}}},"responses":{"201":{"description":"Participant inserted succesfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateParticipantResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Forbidden (includes plan enforcement)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Conflict (duplicate bib/chip/participant)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get participant by token

> Requires \`READ\` or \`READ\_WRITE\` api key access type.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Events"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"schemas":{"ParticipantGetResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"result":{"$ref":"#/components/schemas/ParticipantSummary"}},"required":["description","result"]}},"required":["body"]},"ParticipantSummary":{"type":"object","additionalProperties":false,"properties":{"event_token":{"type":"string"},"participant_token":{"type":"string"},"name":{"type":"string"},"lastname":{"type":"string","nullable":true},"bib":{"type":"string","nullable":true},"chip":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true},"dob":{"type":"string","format":"date-time","nullable":true},"yob":{"type":"integer","nullable":true},"country":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"age_group":{"type":"string","nullable":true},"team":{"type":"string","nullable":true},"club":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"telephone":{"type":"string","nullable":true},"group_id":{"type":"string","nullable":true},"race_token":{"type":"string","nullable":true},"custom_fields":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/CustomField"}},"individual_start_time":{"type":"string","nullable":true}},"required":["event_token","participant_token","name"]},"CustomField":{"type":"object","additionalProperties":false,"properties":{"field_name":{"type":"string"},"value":{"type":"string","nullable":true}},"required":["field_name","value"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/events/{event_token}/participants/{participant_token}":{"get":{"tags":["Events"],"summary":"Get participant by token","description":"Requires `READ` or `READ_WRITE` api key access type.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantGetResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```