Organizer API

This document collects and standardizes the API documentation for Organizers.

Authentication

Bearer Token (Sanctum Personal Access Tokens)
Required scope: organizer-api
Access restricted to the organizador_id of the token owner

Supervisor

Bearer Token (Sanctum Personal Access Tokens)
Required scope: supervisor-api
Access to participants of all events

Rate limiting

RateLimiter: organizer-api
Default value: 60 req/min, configurable per organizer

Endpoints

GET /api/v1/organizer/participants

Retrieves participants from the authenticated organizer’s events.

GET /api/v1/supervisor/participants

Retrieves participants from all events (requires Supervisor or Administrator role). Parameters (query): same as the organizer’s. Cursor pagination (recommended for large volumes):

pagination=cursor enables cursor pagination.
per_page page size (recommended 1000–2000 for 20k+).
Response includes meta.cursor.next_cursor and meta.cursor.prev_cursor.
With cursor, only order_by=id is allowed.

Examples:

# Get all participants
curl -H "Authorization: Bearer <TOKEN_SUPERVISOR>" "https://TU_DOMINIO/api/v1/supervisor/participants?per_page=2000"

# First page with cursor (recommended)
curl -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN_SUPERVISOR>" \
  "https://TU_DOMINIO/api/v1/supervisor/participants?pagination=cursor&per_page=2000"

# Next page with cursor
curl -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN_SUPERVISOR>" \
  "https://TU_DOMINIO/api/v1/supervisor/participants?pagination=cursor&per_page=2000&cursor=<NEXT_CURSOR>"

Parameters (query):

participant_id (optional, integer) - Filter by a specific participant ID
event_id (optional, integer) - Filter by event ID
status (optional, string) - Filter by participant status
bib (optional, string) - Filter by BIB number
from (optional, Y-m-d) - Start date to filter by creation date
to (optional, Y-m-d) - End date to filter by creation date
search (optional, string) - Search by name, last name, email, phone, locator, notes
order_by (optional, string) - Sort field: id|created_at|status|bib|evento_id
order_dir (optional, string) - Sort direction: asc|desc
per_page (optional, integer) - Number of items per page (respects configuration limits)

Response: collection of ParticipantResource with meta.filters. Examples:

# Get all participants
curl -H "Authorization: Bearer <TOKEN>" "https://TU_DOMINIO/api/v1/organizer/participants?per_page=50"

# Get a specific participant by ID
curl -H "Authorization: Bearer <TOKEN>" "https://TU_DOMINIO/api/v1/organizer/participants?participant_id=123"

# Filter by a specific event
curl -H "Authorization: Bearer <TOKEN>" "https://TU_DOMINIO/api/v1/organizer/participants?event_id=456"

# Combine filters
curl -H "Authorization: Bearer <TOKEN>" "https://TU_DOMINIO/api/v1/organizer/participants?event_id=456&status=active&per_page=20"

Per-organizer configuration

Table: organizer_api_settings

enabled
rate_limit_per_minute
default_page_size
max_page_size
ip_allowlist

Roadmap

New endpoints under /api/v1/organizer/*
Versioning via header or v2 prefix
Auto-generated OpenAPI/Swagger

POST /api/v1/organizer/participants

Updates participants by id (bulk, batched). Only non-autogenerated fields are allowed.

POST /api/v1/supervisor/participants

Updates participants by id (bulk, batched). Only non-autogenerated fields are allowed. Requires Supervisor or Administrator role and supervisor-api scope. Bulk upload (best practices):

Large batches are accepted (e.g. 20k). If the updates array exceeds 1000 elements, the server splits it into chunks and processes them in the background via the queue.
Immediate response with 202 Accepted and chunk metadata. Check the logs to see progress.
Sizes ≤1000 are processed synchronously with a 200 response.

Body (JSON) and response: same as the organizer endpoint. cURL example:

curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN_SUPERVISOR>" \
  -d '{
    "updates": [
      {"id": 123, "bib": "A-102"},
      {"id": 124, "observations": "Nota"}
    ]
  }' \
  "https://TU_DOMINIO/api/v1/supervisor/participants"

Bulk example (will receive 202 Accepted):

curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN_SUPERVISOR>" \
  -d @payload_20000.json \
  "https://TU_DOMINIO/api/v1/supervisor/participants"

Authorization: Bearer Token (Sanctum) with organizer-api scope.
Roles: Organizer or Administrator.
Additional security: Optional X-Organizer-Id header to reinforce ownership.
Validations: JSON only; suspicious content is rejected (script, javascript:, on* handlers, data:text/html) in the competition_results and details objects.

Fields allowed per participant:

bib (String, optional) - Participant’s BIB number
observations (String, optional) - General observations about the participant
participation_notes (String, optional) - Specific participation notes
competition_results (JSON Object, optional) - Competition results in JSON format
details (JSON Object, optional) - Additional participant details in JSON format

Prohibited fields (rejected): evento_id, locator, order_id, user_id, created_by, updated_by, deleted_by, status. Body (JSON):

{
  "updates": [
    {
      "id": 123,
      "bib": "A-102",
      "observations": "Llegó con retraso de 2m",
      "participation_notes": "Usa chip nuevo",
      "competition_results": {
        "tiempo_chip": "00:45:12",
        "posicion_final": 12
      },
      "details": {
        "talla": "M"
      }
    },
    { "id": 124, "observations": "Nota actualizada" }
  ]
}

Response 200:

{
  "data": [
    { "id": 123, "updated": true },
    { "id": 124, "updated": false, "message": "No se enviaron campos actualizables" }
  ],
  "errors": [
    { "id": 999, "code": "ORGAPI_404_NOT_FOUND", "message": "Participante no encontrado" }
  ],
  "meta": { "updated_count": 1, "failed_count": 1 }
}

cURL example:

curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Organizer-Id: <ID_ORGANIZADOR>" \
  -d '{
    "updates": [
      {"id": 123, "bib": "A-102"},
      {"id": 124, "observations": "Nota"}
    ]
  }' \
  "https://TU_DOMINIO/api/v1/organizer/participants"

Core

APIs

Features

Frontend

Guides

Commands

Performance

Organizer api

Organizer API

Authentication

Supervisor

Rate limiting

Endpoints

GET /api/v1/organizer/participants

GET /api/v1/supervisor/participants

Per-organizer configuration

Roadmap

POST /api/v1/organizer/participants

POST /api/v1/supervisor/participants

​Organizer API

​Authentication

​Supervisor

​Rate limiting

​Endpoints

​GET /api/v1/organizer/participants

​GET /api/v1/supervisor/participants

​Per-organizer configuration

​Roadmap

​POST /api/v1/organizer/participants

​POST /api/v1/supervisor/participants

Organizer API

Authentication

Supervisor

Rate limiting

Endpoints

GET /api/v1/organizer/participants

GET /api/v1/supervisor/participants

Per-organizer configuration

Roadmap

POST /api/v1/organizer/participants

POST /api/v1/supervisor/participants