Festivals API

The Festivals API allows you to manage and retrieve festival information.

List Festivals

Get a list of festivals.

Endpoint: GET /festivals

Headers:

• X-F-Authorization: Client token (required)

Query Parameters:

• map (optional): Set to true to use map / bounding-box mode instead of the full list (requires min_lat, max_lat, min_lng, max_lng; default limit 80, max 200). See below.
• page (optional): Page number, 1-based (default: 1)
• limit (optional): Page size (default: 20 for list, 80 for map mode; maximum: 100 list / 200 map)
• time (optional): upcoming (start_time on or after now) or past (end_time before now)
• country (optional): Case-insensitive exact match on country

Response: Paginated envelope with full festival payloads (including related places, gigs, tickets, etc.):

{
  "festivals": [
    {
      "id": "festival-id",
      "name": "Summer Music Festival",
      "description": "A great music festival",
      "venue": "Central Park",
      "address": "123 Main St",
      "country": "USA",
      "start_time": "2024-07-01T00:00:00Z",
      "end_time": "2024-07-03T23:59:59Z",
      "photo": "https://example.com/photo.jpg",
      "organizer": {
        "id": "organizer-id",
        "name": "Festival Organizer"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasMore": true
  }
}

Map mode (bounding box)

Return festivals whose coordinates.location lies inside a lat/lng bounding box. Use this from map UIs when the viewport changes (pan/zoom). Lighter payload than the full list (no nested gigs/places/tickets).

Endpoint: GET /festivals?map=true&...

Headers:

• X-F-Authorization: Client token (required)

Query Parameters:

• map=true (required for this mode)
• min_lat, max_lat, min_lng, max_lng (required): Bounding box (decimal degrees)
• time, country (optional): Same semantics as list GET /festivals
• page, limit (optional): Default limit 80, maximum 200

Response: Same { festivals, pagination } shape; each festival includes core fields such as id, name, photo, venue, country, coordinates, start_time, end_time, rank.

Get Festival

Get details of a specific festival.

Endpoint: GET /festivals/:id

Headers:

• X-F-Authorization: Client token (required)

Response:

{
  "id": "festival-id",
  "name": "Summer Music Festival",
  "description": "A great music festival",
  "venue": "Central Park",
  "address": "123 Main St",
  "country": "USA",
  "start_time": "2024-07-01T00:00:00Z",
  "end_time": "2024-07-03T23:59:59Z",
  "photo": "https://example.com/photo.jpg",
  "organizer": {
    "id": "organizer-id",
    "name": "Festival Organizer"
  },
  "gigs": [
    {
      "id": "gig-id",
      "artist": {
        "id": "artist-id",
        "name": "Artist Name"
      },
      "start_time": "2024-07-01T18:00:00Z",
      "end_time": "2024-07-01T20:00:00Z"
    }
  ],
  "places": [
    {
      "id": "place-id",
      "name": "Main Stage",
      "type": "stage"
    }
  ]
}

Create Festival

Create a new festival.

Endpoint: POST /festivals

Headers:

• X-F-Authorization: Client token (required)
• X-F-Authentication: User token (required)

Request Body:

{
  "name": "Summer Music Festival",
  "description": "A great music festival",
  "venue": "Central Park",
  "address": "123 Main St",
  "country": "USA",
  "area": "New York",
  "start_time": "2024-07-01T00:00:00Z",
  "end_time": "2024-07-03T23:59:59Z",
  "organizer_id": "organizer-id",
  "photo": "base64-encoded-image-or-url",
  "gigs": [
    {
      "artist_id": "artist-id",
      "place_id": "place-id",
      "start_time": "2024-07-01T18:00:00Z",
      "end_time": "2024-07-01T20:00:00Z"
    }
  ],
  "places": [
    {
      "name": "Main Stage",
      "type": "stage",
      "coordinates": {
        "lat": 40.7128,
        "lng": -74.0060
      }
    }
  ],
  "tickets": [
    {
      "name": "General Admission",
      "price": 100,
      "quantity": 1000
    }
  ]
}

Response: Returns the created festival object.

Update Festival

Update an existing festival.

Endpoint: PUT /festivals/:id

Headers:

• X-F-Authorization: Client token (required)
• X-F-Authentication: User token (required)

Request Body: Same as create, but all fields are optional.

Delete Festival

Delete a festival.

Endpoint: DELETE /festivals/:id

Headers:

• X-F-Authorization: Client token (required)
• X-F-Authentication: User token (required)

Response:

{
  "message": "Festival deleted successfully"
}