API Documentation

Introduction

larpdatabase.com collects and documents larp events, organizations, campaigns, crew and cast internationally.

The REST API v1 allows organizations to manage their content programmatically, integrating with their own tools and automating the operations normally performed through the management panel.

Through the API you can:

• Create, update and delete draft events
• Manage crew and cast of your events
• Create, update and delete draft campaigns
• Request publication of events and campaigns

Every organization contributing through the API helps us keep the larp database more complete and up to date.

Authentication

All API requests require a Bearer token. Generate one from your profile settings.

Include these headers in every request:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json

Rate Limits

When a limit is exceeded, the API returns 429 Too Many Requests with a retry_after field.

Response Format

All responses follow a consistent JSON envelope:

{
    "success": true,
    "message": "OK",
    "data": { ... },
    "meta": { "current_page": 1, "last_page": 3, "per_page": 15, "total": 42 },
    "links": { "first": "...", "last": "...", "prev": null, "next": "..." }
}

meta and links are only present in paginated responses (list endpoints).

Error Codes

Validation errors include a detailed errors object:

{
    "success": false,
    "message": "Validation failed.",
    "errors": {
        "nome": ["The nome field is required."],
        "data_fine": ["The data fine must be after or equal to data inizio."]
    }
}

Returns a list of all available event genres.

This endpoint does not require authentication and is mounted at /api/v1/genres.

Example

curl -X GET "https://www.larpdatabase.com/api/v1/genres" \
  -H "Accept: application/json"

Response Example

{
    "success": true,
    "data": [
        { "id": 1, "name": "Fantasy", "name_en": "Fantasy" },
        { "id": 2, "name": "Fantascienza", "name_en": "Sci-Fi" }
    ]
}

Returns a paginated list of events for the team.

Query Parameters

Example

curl -X GET "https://www.larpdatabase.com/api/v1/teams/1/events?status=draft" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Required permission: events:read

Creates a new event in draft status.

Body Parameters

Example

curl -X POST "https://www.larpdatabase.com/api/v1/teams/1/events" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "The Great larp",
    "abstract": "An epic adventure...",
    "genere": [1, 3],
    "tipologia": "one shot",
    "run": "1",
    "lingua": ["it", "en"],
    "data_inizio": "2026-07-01",
    "data_fine": "2026-07-03",
    "durata": 3,
    "tipo_durata": "giorni",
    "numero_partecipanti": 50,
    "costo": 100,
    "location": "41.9028,12.4964"
  }'

Required permission: events:write | Subject to daily creation limit

Returns a single event by ID. The event must belong to the specified team.

Required permission: events:read

Updates an existing event. Only send the fields you want to change. Accepts application/json.

Accepts the same fields as Create Event, except locandina. To manage the poster image use the dedicated endpoints below.

Example

curl -X PUT "https://www.larpdatabase.com/api/v1/teams/1/events/123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"nome": "Updated Title", "costo": 120}'

Required permission: events:write

Uploads or replaces the poster image for an event. Send as multipart/form-data.

Body Parameters

Example

curl -X POST "https://www.larpdatabase.com/api/v1/teams/1/events/123/locandina" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "locandina=@/path/to/poster.jpg"

Required permission: events:write

Removes the poster image from an event.

Example

curl -X DELETE "https://www.larpdatabase.com/api/v1/teams/1/events/123/locandina" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Required permission: events:write

Deletes an event. Only draft events can be deleted. Returns 409 for non-draft events.

Required permission: events:write

Submits a draft event for review. Changes status from draft to pending. Only works on draft events.

Required permission: events:write

Returns all crew members for an event, ordered by sort_order.

Response Example

{
    "success": true,
    "data": [
        {
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "entity_type": "person",
            "first_name": "Mario",
            "last_name": "Rossi",
            "role": "Director",
            "user_id": null,
            "is_organizer": true,
            "sort_order": 0,
            "evento_id": 123,
            "created_at": "2026-04-29T10:00:00+00:00",
            "updated_at": "2026-04-29T10:00:00+00:00"
        }
    ]
}

Required permission: events:read

Adds a crew member to an event. The response includes the uuid assigned — store it to use in future PUT/DELETE/reorder calls.

Body Parameters

Example

curl -X POST "https://www.larpdatabase.com/api/v1/teams/1/events/123/crew" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "person",
    "first_name": "Mario",
    "last_name": "Rossi",
    "role": "Director",
    "is_organizer": true
  }'

Response Example

{
    "success": true,
    "message": "Crew member added successfully.",
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "entity_type": "person",
        "first_name": "Mario",
        "last_name": "Rossi",
        "role": "Director",
        "user_id": null,
        "is_organizer": true,
        "sort_order": 0,
        "evento_id": 123,
        "created_at": "2026-04-29T10:00:00+00:00",
        "updated_at": "2026-04-29T10:00:00+00:00"
    }
}

Required permission: events:write

Updates a crew member. Only send the fields you want to change. Same fields as Add Crew.

{crew} is the uuid returned when the crew member was created.

Example

curl -X PUT "https://www.larpdatabase.com/api/v1/teams/1/events/123/crew/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"role": "Co-Director"}'

Required permission: events:write

Removes a crew member from the event.

{crew} is the uuid returned when the crew member was created.

Example

curl -X DELETE "https://www.larpdatabase.com/api/v1/teams/1/events/123/crew/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Required permission: events:write

Reorders crew members for an event. Pass an array of uuid + sort_order pairs.

Example

curl -X PUT "https://www.larpdatabase.com/api/v1/teams/1/events/123/crew/reorder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "order": [
      {"uuid": "550e8400-e29b-41d4-a716-446655440000", "sort_order": 0},
      {"uuid": "661f9511-f30c-52e5-b827-557766551111", "sort_order": 1},
      {"uuid": "772a0622-g41d-63f6-c938-668877662222", "sort_order": 2}
    ]
  }'

Required permission: events:write

Returns all cast members for an event.

Response Example

{
    "success": true,
    "data": [
        {
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "first_name": "Luca",
            "last_name": "Bianchi",
            "character": "King Aldric",
            "npc": false,
            "user_id": null,
            "evento_id": 123,
            "created_at": "2026-04-29T10:00:00+00:00",
            "updated_at": "2026-04-29T10:00:00+00:00"
        }
    ]
}

Required permission: events:read

Adds a cast member to an event. The response includes the uuid assigned to the new participant — store it to use in future PUT/DELETE calls.

Body Parameters

Example

curl -X POST "https://www.larpdatabase.com/api/v1/teams/1/events/123/cast" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Luca",
    "last_name": "Bianchi",
    "character": "King Aldric",
    "npc": false
  }'

Response Example

{
    "success": true,
    "message": "Cast member added successfully.",
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "Luca",
        "last_name": "Bianchi",
        "character": "King Aldric",
        "npc": false,
        "user_id": null,
        "evento_id": 123,
        "created_at": "2026-04-29T10:00:00+00:00",
        "updated_at": "2026-04-29T10:00:00+00:00"
    }
}

Required permission: events:write

Updates a cast member. Only send the fields you want to change. Same fields as Add Cast.

{participant} is the uuid returned when the cast member was created.

Example

curl -X PUT "https://www.larpdatabase.com/api/v1/teams/1/events/123/cast/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"character": "King Aldric the Bold"}'

Required permission: events:write

Removes a cast member from the event.

{participant} is the uuid returned when the cast member was created.

Example

curl -X DELETE "https://www.larpdatabase.com/api/v1/teams/1/events/123/cast/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Required permission: events:write

Returns a paginated list of campaigns for the team.

Query Parameters

Required permission: campaigns:read

Creates a new campaign in draft status.

Body Parameters

Example

curl -X POST "https://www.larpdatabase.com/api/v1/teams/1/campaigns" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "titolo": "The Great Campaign",
    "descrizione": "An epic multi-year adventure",
    "anno_inizio": 2026
  }'

Required permission: campaigns:write | Subject to daily creation limit

Returns a single campaign by ID.

Required permission: campaigns:read

Updates a campaign. Only send the fields you want to change. Same fields as Create Campaign, plus:

Required permission: campaigns:write

Deletes a campaign. Only draft campaigns can be deleted. Returns 409 for non-draft campaigns.

Required permission: campaigns:write

Submits a draft campaign for review. Changes status from draft to pending.

Required permission: campaigns:write