> For the complete documentation index, see [llms.txt](https://developers.goevent.live/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.goevent.live/craft-the-future-ticketing-experience.md).

# Craft the Future Ticketing Experience

## API Documentation - Developers V1.0

Base URL: `https://cloud.goevent.live/developers/v1.0`

**Headers required for all requests**

```http
Content-Type: application/json
Authorization: Bearer <token>
```

***

### Table of contents

1. [List Events](#1-list-events)
2. [Get Single Event](#2-get-single-event)
3. [Create Event](#create-event)
4. [List Tickets](#3-list-tickets)
5. [Create Price](#3-list-tickets)
6. [Create Tickets](#4-create-tickets)
7. [List Participants](#5-list-participants)

{% stepper %}
{% step %}

### 1. List Events

Retrieve all events where the authenticated user has admin role.

Endpoint: `GET /events`

Query Parameters:

| Parameter | Type   | Required | Description                         | Default |
| --------- | ------ | -------- | ----------------------------------- | ------- |
| page      | number | No       | Page number                         | 1       |
| limit     | number | No       | Number of items per page (max: 100) | 20      |

Response:

```json
{
  "events": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Concert de Jazz",
      "slug": "concert-de-jazz",
      "path": "/concert-de-jazz",
      "dateStart": "2024-06-15T20:00:00.000Z",
      "dateEnd": "2024-06-16T02:00:00.000Z",
      "location": "Paris, France",
      "publish": true,
      "cover": {
        "square": "https://res.cloudinary.com/genielabel/image/upload/c_fill,w_200,h_200,g_auto/abc123.jpg",
        "thumb": "https://res.cloudinary.com/genielabel/image/upload/c_thumb,w_400,h_300/abc123.jpg",
        "medium": "https://res.cloudinary.com/genielabel/image/upload/c_scale,w_800/abc123.jpg",
        "original": "https://res.cloudinary.com/genielabel/image/upload/abc123.jpg"
      },
      "checkoutUrl": "https://www.goevent.live/e/concert-de-jazz/checkout",
      "siteUrl": "https://www.goevent.live/e/concert-de-jazz"
    }
  ],
  "paginate": {
    "hasNextPage": true,
    "nextPage": 2
  }
}
```

Example Request:

{% code title="curl" %}

```bash
curl --location --request GET 'https://cloud.goevent.live/developers/v1.0/events?page=1&limit=20' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'
```

{% endcode %}
{% endstep %}

{% step %}

### 2. Get Single Event

Retrieve a single event with its tickets by event ID.

Endpoint: `GET /event/{id}`

Path Parameters:

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| id        | string | Yes      | Event ID (ObjectId) |

Response:

```markdown
{
  "event": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Concert de Jazz",
    "slug": "concert-de-jazz",
    "path": "/concert-de-jazz",
    "dateStart": "2024-06-15T20:00:00.000Z",
    "dateEnd": "2024-06-16T02:00:00.000Z",
    "location": "Paris, France",
    "publish": true,
    "cover": {
      "square": "https://res.cloudinary.com/genielabel/image/upload/c_fill,w_200,h_200,g_auto/abc123.jpg",
      "thumb": "https://res.cloudinary.com/genielabel/image/upload/c_thumb,w_400,h_300/abc123.jpg",
      "medium": "https://res.cloudinary.com/genielabel/image/upload/c_scale,w_800/abc123.jpg",
      "original": "https://res.cloudinary.com/genielabel/image/upload/abc123.jpg"
    },
    "checkoutUrl": "https://www.goevent.live/e/concert-de-jazz/checkout",
    "siteUrl": "https://www.goevent.live/e/concert-de-jazz"
  },
  "tickets": [
    {
      "id": "65fff7aada40be007f09ee95",
      "name": "VIP",
      "available": true,
      "quantity": 100
    },
    {
      "id": "65fff7aada40be007f09ee96",
      "name": "Standard",
      "available": true,
      "quantity": 250
    }
  ]
}
```

Example Request:

{% code title="curl" %}

```bash
curl --location --request GET 'https://cloud.goevent.live/developers/v1.0/event/67212707e47ff56741acb3a6' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'
```

{% endcode %}
{% endstep %}

{% step %}

### Create Event

Create a new event for the authenticated user.

**Endpoint:** `POST /events/create`

**Request Body Parameters:**

| Parameter   | Type    | Required | Description                                              |
| ----------- | ------- | -------- | -------------------------------------------------------- |
| name        | string  | Yes      | Event name                                               |
| description | string  | No       | Event description                                        |
| dateStart   | string  | No       | Start date (ISO 8601)                                    |
| dateEnd     | string  | No       | End date (ISO 8601)                                      |
| type        | string  | No       | Event type (default: "event")                            |
| address     | string  | No       | Event address                                            |
| dateType    | string  | No       | Date type: "classic" or "recurrent" (default: "classic") |
| city        | string  | No       | City                                                     |
| country     | string  | No       | Country                                                  |
| location    | string  | No       | Full location string                                     |
| publish     | boolean | No       | Published status (default: false)                        |
| currency    | string  | No       | Currency code (default: "EUR")                           |

**Request Body:**

```json
{
  "name": "Concert de Jazz",
  "description": "Une soir\u00e9e jazz inoubliable",
  "dateStart": "2024-06-15T20:00:00.000Z",
  "dateEnd": "2024-06-16T02:00:00.000Z",
  "type": "event",
  "address": "123 Rue de la Musiques",
  "dateType": "classic",
  "city": "Paris",
  "country": "France",
  "location": "Paris, France",
  "publish": false,
  "currency": "EUR"
}

```

{% endstep %}

{% step %}

### &#x20;Upload Cover

Upload a cover image for an event. Uses multipart/form-data.

**Endpoint:** `POST /events/cover`

**Request Body (multipart/form-data):**

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| eventId   | string | Yes      | Event ID (ObjectId)          |
| file      | file   | Yes      | Image file (JPEG, PNG, etc.) |

**Response:**

```json
{
  "success": true,
  "cover": {
  
    "url": "https://res.cloudinary.com/genielabel/image/upload/v1234567890/abc123def456.jpg",
 
  }
}
```

**Example Request:**

```bash
curl --location --request POST 'https://cloud.goevent.live/developers/v1.0/events/cover' \
--header 'Authorization: Bearer <token>' \
--form 'eventId=65fff7aada40be007f09ee95' \
--form 'file=@/path/to/image.jpg'
```

***

{% endstep %}

{% step %}

### List Tickets

Retrieve all tickets (prices) available for a specific event.

Endpoint: `GET /tickets`

Query Parameters:

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| eventId   | string | Yes      | Event ID (ObjectId) |

Response:

```json
{
  "tickets": [
    {
      "id": "65fff7aada40be007f09ee95",
      "name": "VIP",
      "available": true,
      "quantity": 100
    },
    {
      "id": "65fff7aada40be007f09ee96",
      "name": "Standard",
      "available": true,
      "quantity": 250
    }
  ]
}
```

Example Request:

{% code title="curl" %}

```bash
curl --location --request GET 'https://cloud.goevent.live/developers/v1.0/tickets?eventId=67212707e47ff56741acb3a6' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'
```

{% endcode %}
{% endstep %}

{% step %}

### Create Price

Create a new price (ticket type) for an event.

**Endpoint:** `POST /prices/create`

**Request Body:**

```json
{
  "eventId": "67212707e47ff56741acb3a6",
  "name": "Early Bird",
  "price": 25.00,
  "currency": "EUR",
  "quantity": 100,
  "available": true
}
```

**Request Body Parameters:**

| Parameter | Type    | Required | Description                            |
| --------- | ------- | -------- | -------------------------------------- |
| eventId   | string  | Yes      | Event ID (ObjectId)                    |
| name      | string  | Yes      | Price name (e.g., "Early Bird", "VIP") |
| price     | number  | Yes      | Price amount                           |
| currency  | string  | No       | Currency code (default: "EUR")         |
| quantity  | number  | No       | Available quantity (default: 0)        |
| available | boolean | No       | Availability status (default: true)    |

**Response:**

```json
{
  "success": true,
  "price": {
    "id": "65fff7aada40be007f09ee95",
    "name": "Early Bird",
    "price": 25,
    "currency": "EUR",
    "quantity": 100,
    "available": true,
    "eventId": "67212707e47ff56741acb3a6"
  }
}
```

**Example Request:**

```bash
curl --location --request POST 'https://cloud.goevent.live/developers/v1.0/prices/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "eventId": "67212707e47ff56741acb3a6",
    "name": "Early Bird",
    "price": 25.00,
    "currency": "EUR",
    "quantity": 100,
    "available": true
}'
```

***

{% endstep %}

{% step %}

### Create Tickets

Create tickets for an event. Supports:

* Anonymous tickets
* Tickets with existing participant (by participantId)
* Tickets with new participant data

Endpoint: `POST /tickets/create`

Request Body:

```json
{
  "eventId": "643e7b194937913299554a7d",
  "tickets": [
    { "ticket_id": "65fff7aada40be007f09ee95", "quantity": 2 }
  ],
  "participant": {
    "participantId": "697f54811fc6cd47e04c39c3"
  }
}
```

Request Body Parameters:

| Parameter                 | Type   | Required | Description                        |
| ------------------------- | ------ | -------- | ---------------------------------- |
| eventId                   | string | Yes      | Event ID (ObjectId)                |
| tickets                   | array  | Yes      | Array of ticket objects            |
| tickets\[].ticket\_id     | string | Yes      | Price/Ticket ID                    |
| tickets\[].quantity       | number | Yes      | Number of tickets                  |
| participant               | object | No       | Participant data (optional)        |
| participant.participantId | string | No       | Existing participant ID (optional) |
| participant.last\_name    | string | No       | Participant last name              |
| participant.first\_name   | string | No       | Participant first name             |
| participant.email         | string | No       | Participant email                  |
| participant.phone         | string | No       | Participant phone                  |

Response:

```json
{
  "success": true,
  "participant": {
    "id": "697f54811fc6cd47e04c39c3",
    "last_name": "Doe",
    "first_name": "John",
    "email": "john@example.com",
    "phone": "+1234567890",
    "address": null
  },
  "tickets": [
    {
      "name": "VIP",
      "url": "https://goeventcloud2.s3.amazonaws.com/ticket-123.pdf?signature=...",
      "quantity": 2
    }
  ]
}
```

Example Requests:

With existing participant:

{% code title="curl" %}

```bash
curl --location --request POST 'https://cloud.goevent.live/developers/v1.0/tickets/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "eventId": "643e7b194937913299554a7d",
    "tickets": [
      { "ticket_id": "65fff7aada40be007f09ee95", "quantity": 2 }
    ],
    "participant": {
      "participantId": "697f54811fc6cd47e04c39c3"
    }
}'
```

{% endcode %}

With new participant:

{% code title="curl" %}

```bash
curl --location --request POST 'https://cloud.goevent.live/developers/v1.0/tickets/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "eventId": "643e7b194937913299554a7d",
    "tickets": [
      { "ticket_id": "65fff7aada40be007f09ee95", "quantity": 2 }
    ],
    "participant": {
      "last_name": "Doe",
      "first_name": "John",
      "email": "john@example.com",
      "phone": "+1234567890"
    }
}'
```

{% endcode %}

Anonymous ticket:

{% code title="curl" %}

```bash
curl --location --request POST 'https://cloud.goevent.live/developers/v1.0/tickets/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "eventId": "643e7b194937913299554a7d",
    "tickets": [
      { "ticket_id": "65fff7aada40be007f09ee95", "quantity": 1 }
    ]
}'
```

{% endcode %}
{% endstep %}

{% step %}

### &#x20;List Participants

Retrieve all participants for a specific event.

Endpoint: `GET /participants`

Query Parameters:

| Parameter | Type   | Required | Description                         | Default |
| --------- | ------ | -------- | ----------------------------------- | ------- |
| eventId   | string | Yes      | Event ID (ObjectId)                 | -       |
| page      | number | No       | Page number                         | 1       |
| limit     | number | No       | Number of items per page (max: 100) | 50      |

Response:

```json
{
  "participants": [
    {
      "id": "697f54811fc6cd47e04c39c3",
      "last_name": "Doe",
      "first_name": "John",
      "email": "john@example.com",
      "phone": "+1234567890",
      "address": null,
      "confirmed": true,
      "created": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "697f54811fc6cd47e04c39c4",
      "last_name": "Smith",
      "first_name": "Jane",
      "email": "jane@example.com",
      "phone": "+1234567891",
      "address": "123 Main St",
      "confirmed": true,
      "created": "2024-01-16T14:20:00.000Z"
    }
  ],
  "paginate": {
    "hasNextPage": false,
    "nextPage": null
  }
}
```

Example Request:

{% code title="curl" %}

```bash
curl --location --request GET 'https://cloud.goevent.live/developers/v1.0/participants?eventId=67212707e47ff56741acb3a6&page=1&limit=50' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'
```

{% endcode %}
{% endstep %}
{% endstepper %}

### Error Responses (expandable)

<details>

<summary>Invalid ID</summary>

```json
{
  "error": "ID is not correct"
}
```

</details>

<details>

<summary>Event Not Found</summary>

```json
{
  "error": "Event not found"
}
```

</details>

<details>

<summary>Unauthorized (not admin)</summary>

```json
{
  "error": "Unauthorized"
}
```

</details>

<details>

<summary>Missing Required Field</summary>

```json
{
  "error": "Event ID is required"
}
```

</details>

<details>

<summary>Ticket Generation Failed</summary>

```json
{
  "error": "Failed to generate tickets"
}
```

</details>

### Notes

* All endpoints require a valid JWT token in the Authorization header
* User must have `admin` role on the event to access its data
* Pagination defaults to 20 items per page for events, 50 for participants