> ## Documentation Index
> Fetch the complete documentation index at: https://docs.animo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

# Events

## Overview

Events represent online or offline gatherings for a company. The API supports listing, creating, updating events, and managing cohosts. Organizing events also expose [event page](event-pages.md) and [comms template](comms.md) endpoints. Ticket types and orders are nested under organizing events — see [Ticket types](ticket-types.md) and [Orders](orders.md).

**Subscription:** Pro plan required. Upgrade at [https://app.animo.co/admin/settings/billing](https://app.animo.co/admin/settings/billing).

## Public event URL

```
https://app.animo.co/{company-slug}/event/{event-slug}
```

Use `slug` from companies and `id` from the event resource. Not returned by the API — see [Conventions — Public URLs](../conventions.md#public-urls).

## Event ID and slug behavior

On **create**, the event `id` is derived from `name` (e.g. `"AI Demo Days · HR Edition"` → `ai-demo-days-hr-edition`). A `slug` sent in the request body is **ignored**.

On **update**, `slug` can be set explicitly via `PATCH`.

This differs from ticket types, where the supplied `slug` is honored on create. See [Conventions — Slug behavior](../conventions.md#slug-behavior-events-vs-ticket-types).

## Endpoints

### List events

* **Method:** `GET`
* **Path:** `/api/v1/{company}/events`
* **Scope:** `events:read`
* **Subscription:** `USE_API`

#### Path parameters

| Name      | Type   | Description  |
| --------- | ------ | ------------ |
| `company` | string | Company sqid |

#### Query parameters

| Name   | Type    | Description                            |
| ------ | ------- | -------------------------------------- |
| `q`    | string  | Filter by event name (substring match) |
| `page` | integer | Page number                            |

#### Response `200`

```json theme={null}
{
  "data": [
    {
      "id": "product-launch-2026",
      "name": "Product Launch 2026",
      "date_start": "2026-04-25T09:00:00.000+00:00",
      "date_end": "2026-04-26T18:00:00.000+00:00",
      "created_at": "2026-03-01T12:00:00.000+00:00",
      "attendance_mode": "offline",
      "company_role": "organizing",
      "timezone": "America/Montevideo",
      "privacy_policy": "https://example.com/privacy",
      "locale": "en",
      "requires_ticket_assignment": false,
      "city": {
        "name": "Montevideo",
        "latitude": -34.9011,
        "longitude": -56.1645,
        "google_place_id": "ChIJ..."
      },
      "country": {
        "name": "Uruguay",
        "alpha2Code": "UY",
        "alpha3Code": "URY"
      },
      "venue": {
        "name": "Convention Center",
        "google_place_id": "ChIJ...",
        "url": "https://example.com",
        "maps_url": "https://maps.google.com/...",
        "address": "Main St 1",
        "latitude": -34.9011,
        "longitude": -56.1645
      },
      "cohosts": []
    }
  ],
  "links": { "...": "..." },
  "meta": { "...": "..." }
}
```

#### Response fields

| Field                        | Type         | Description                                                                                                           |
| ---------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `id`                         | string       | Event slug                                                                                                            |
| `name`                       | string       | Event name                                                                                                            |
| `date_start`                 | string       | Start datetime (ISO 8601)                                                                                             |
| `date_end`                   | string       | End datetime (ISO 8601)                                                                                               |
| `created_at`                 | string       | Creation timestamp                                                                                                    |
| `attendance_mode`            | string       | `online` or `offline`                                                                                                 |
| `company_role`               | string       | `organizing` or `attending`                                                                                           |
| `timezone`                   | string       | IANA timezone identifier                                                                                              |
| `privacy_policy`             | string\|null | Privacy policy URL                                                                                                    |
| `locale`                     | string       | Supported locale code                                                                                                 |
| `requires_ticket_assignment` | boolean      | Whether tickets must be assigned to attendees                                                                         |
| `city`                       | object\|null | City details (offline events)                                                                                         |
| `country`                    | object\|null | Country details                                                                                                       |
| `venue`                      | object\|null | Venue details                                                                                                         |
| `cohosts`                    | array        | List of cohost objects                                                                                                |
| `page`                       | object       | Event page content — present on **show** and **update** for organizing events only. See [Event pages](event-pages.md) |

#### Errors

| Status | When                                           |
| ------ | ---------------------------------------------- |
| `401`  | Missing or invalid token                       |
| `403`  | Missing scope, subscription, or company access |

***

### Create event

* **Method:** `POST`
* **Path:** `/api/v1/{company}/events/create`
* **Scope:** `events:create` (in addition to `events:read` on the route group)
* **Subscription:** `USE_API`

#### Request body

See the request body table below for field requirements.

```json theme={null}
{
  "date_start": "2026-04-25 09:00",
  "date_end": "2026-04-26 18:00",
  "city": "Montevideo",
  "province": "Montevideo",
  "country": "Uruguay",
  "venue": "Convention Center",
  "venue_address": "Main St 1",
  "name": "Product Launch 2026",
  "slug": "product-launch-2026",
  "attendance_mode": "offline",
  "timezone": "America/Montevideo",
  "locale": "en",
  "company_role": "organizing",
  "privacy_policy": "https://example.com/privacy",
  "tax_country": "UY",
  "requires_ticket_assignment": false
}
```

| Field                        | Required      | Description                                                                                             |
| ---------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| `date_start`                 | Yes           | Format `Y-m-d H:i`                                                                                      |
| `date_end`                   | Yes           | Format `Y-m-d H:i`, must be >= `date_start`                                                             |
| `name`                       | Yes           | Event name (max 255 chars)                                                                              |
| `attendance_mode`            | Yes           | `online` or `offline`                                                                                   |
| `locale`                     | Yes           | Supported locale enum value                                                                             |
| `company_role`               | Yes           | `organizing` or `attending`                                                                             |
| `city`                       | If offline    | City name                                                                                               |
| `province`                   | If offline    | Province/region                                                                                         |
| `country`                    | If offline    | Country name                                                                                            |
| `venue`                      | No            | Venue name                                                                                              |
| `venue_address`              | No            | Venue street address                                                                                    |
| `slug`                       | No            | **Ignored on create** — event `id` is auto-derived from `name`. Use `PATCH` to set slug after creation. |
| `timezone`                   | If online     | IANA timezone                                                                                           |
| `privacy_policy`             | No            | Valid URL                                                                                               |
| `tax_country`                | No            | ISO 3166-1 alpha-2 country code                                                                         |
| `requires_ticket_assignment` | If organizing | Boolean                                                                                                 |

#### Response `201`

Returns a single `EventResource` in the `data` envelope.

#### Errors

| Status | When                          |
| ------ | ----------------------------- |
| `422`  | Validation failure            |
| `403`  | Missing `events:create` scope |

***

### Show event

* **Method:** `GET`
* **Path:** `/api/v1/{company}/events/{event}`
* **Scope:** `events:read`
* **Subscription:** `USE_API`

#### Path parameters

| Name      | Type   | Description  |
| --------- | ------ | ------------ |
| `company` | string | Company sqid |
| `event`   | string | Event slug   |

#### Response `200`

Same shape as a single item from the list response. Organizing events include a nested `page` object.

***

### Update event

* **Method:** `PATCH`
* **Path:** `/api/v1/{company}/events/{event}`
* **Scope:** `events:update`
* **Subscription:** `USE_API`

#### Request body

All fields are optional (partial update). See the request body table below for field requirements.

```json theme={null}
{
  "name": "Updated Event Name",
  "date_start": "2026-05-01 10:00",
  "date_end": "2026-05-01 18:00",
  "google_place_id": "ChIJ...",
  "venue_google_place_id": "ChIJ...",
  "venue": "New Venue",
  "venueAddress": "New Address",
  "slug": "updated-slug",
  "attendance_mode": "online",
  "timezone": "Europe/Amsterdam",
  "locale": "nl",
  "company_role": "organizing",
  "privacy_policy": "https://example.com/privacy",
  "tax_country": "NL",
  "requires_ticket_assignment": true
}
```

#### Response `200`

Returns the updated `EventResource`.

***

### Add cohost

* **Method:** `POST`
* **Path:** `/api/v1/{company}/events/{event}/cohosts`
* **Scope:** `events:update`
* **Subscription:** `USE_API`

#### Request body

```json theme={null}
{
  "name": "Partner Org",
  "privacy_policy": "https://partner.example.com/privacy",
  "position": 1
}
```

| Field            | Required | Description                    |
| ---------------- | -------- | ------------------------------ |
| `name`           | Yes      | Cohost display name            |
| `privacy_policy` | No       | Valid URL (max 512 chars)      |
| `position`       | No       | Sort position (integer, min 1) |

#### Response `200`

Returns the parent event with updated `cohosts` array.

***

### Update cohost

* **Method:** `PATCH`
* **Path:** `/api/v1/{company}/events/{event}/cohosts/{cohost}`
* **Scope:** `events:update`
* **Subscription:** `USE_API`

#### Request body

Same fields as add cohost; `name` is optional on update.

#### Response `200`

Returns the parent event with updated `cohosts` array.

***

### Delete cohost

* **Method:** `DELETE`
* **Path:** `/api/v1/{company}/events/{event}/cohosts/{cohost}`
* **Scope:** `events:update`
* **Subscription:** `USE_API`

#### Response `200`

Returns the parent event with the cohost removed.

## Not implemented

* `DELETE /api/v1/{company}/events/{event}` — not exposed

## Related

* [Authentication](../authentication.md)
* [Conventions](../conventions.md)
* [Event pages](event-pages.md)
* [Comms templates](comms.md)
* [Ticket types](ticket-types.md)
* [Orders](orders.md)