# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.goevent.live/craft-the-future-ticketing-experience.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.