> ## 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.

# Animo API (v1)

> REST API for events, forms, orders, activations, and webhooks on Animo.

The Animo REST API lets external applications read and manage events, forms, orders, activations, and webhooks on behalf of Animo users.

**Base URL:** `https://app.animo.co/api/v1`

## For AI assistants

* [llms.txt](/llms.txt) — documentation index (start here)
* [llms-full.txt](/llms-full.txt) — full corpus in one file
* [For AI agents](for-ai-agents.md) — integration contract (what to orchestrate vs. never rebuild)

## Plan requirement

API access requires an active **Pro** plan on the company you want to integrate with. Upgrade or manage your subscription at:

**[https://app.animo.co/admin/settings/billing](https://app.animo.co/admin/settings/billing)**

Without a Pro plan, `GET /api/v1/companies` returns `200` with an **empty** `data` array (not `403`), and direct calls to company-scoped endpoints return `403`. Webhooks additionally require the Integrations feature (included on Pro and above).

All endpoints require a valid OAuth2 bearer token unless noted otherwise. See [Authentication](authentication.md) for how to obtain and use tokens.

## Quick start

1. **Create a personal access token** in the Animo admin panel (User settings → API tokens). Select the scopes your integration needs.
2. **List your companies** to get a company sqid:
   ```http theme={null}
   GET /api/v1/companies
   Authorization: Bearer {token}
   ```
3. **Call a company-scoped endpoint** using the company sqid from step 2:
   ```http theme={null}
   GET /api/v1/{company}/events
   Authorization: Bearer {token}
   ```

## Documentation

| Topic                                   | Description                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------------ |
| [Business case](business-case.md)       | Cost comparison — fully managed vs. custom site vs. building your own          |
| [Animo for AI agents](for-ai-agents.md) | Integration guide for AI coding agents — what to orchestrate vs. never rebuild |
| [Authentication](authentication.md)     | OAuth2, bearer tokens, scopes                                                  |
| [Conventions](conventions.md)           | IDs, dates, pagination, errors, subscriptions                                  |
| [Changelog](changelog.md)               | API version history                                                            |

### Endpoints

| Resource                                  | Description                                                    |
| ----------------------------------------- | -------------------------------------------------------------- |
| [User](endpoints/user.md)                 | Authenticated user profile                                     |
| [Companies](endpoints/companies.md)       | Companies available to the user                                |
| [Activations](endpoints/activations.md)   | Lead-generation activations                                    |
| [Events](endpoints/events.md)             | Events and cohosts                                             |
| [Event pages](endpoints/event-pages.md)   | Public event page content (tagline, description, header image) |
| [Comms templates](endpoints/comms.md)     | Registration email templates                                   |
| [Ticket types](endpoints/ticket-types.md) | Ticket types for organizing events                             |
| [Orders](endpoints/orders.md)             | Event orders (tickets)                                         |
| [Forms](endpoints/forms.md)               | Company forms and fields                                       |
| [Webhooks](endpoints/webhooks.md)         | Outbound webhook subscriptions                                 |

## Not yet available

The following are defined in code but **not exposed** via the API today:

* `GET` endpoints for leads, submissions, and meetings (scopes exist: `leads:read`, `submissions:read`, `meetings:read`)
* `DELETE /api/v1/{company}/events/{event}` (event delete)
* `DELETE` ticket types
* `DELETE /api/v1/{company}/event/{organizingEvent}/orders/{order}/cancel` (order cancel)
* `DELETE /api/v1/{company}/forms/{form}` (form delete — `forms:delete` scope exists but no route)

## Known API gaps

Issues discovered during live integration testing. These are API/code fixes, not doc typos:

| Issue                                        | Impact                                                                    | Workaround                                                                                                                                     |
| -------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Event `slug` ignored on create               | Event `id` is derived from `name`, not your supplied slug                 | Use the `id` in the create response; set slug via `PATCH` if needed                                                                            |
| No `public_url` in resources                 | Must string-build ticket/event URLs                                       | See [Conventions — Public URLs](conventions.md#public-urls)                                                                                    |
| `OrderResource` omits payment URL            | Paid order checkout link not in JSON                                      | Build checkout URL from order `id` — see [Orders](endpoints/orders.md)                                                                         |
| `orders/create` `form` payload               | Form answers not yet processed server-side                                | Only send order-level fields for now                                                                                                           |
| No submission/lead ingest endpoint           | Custom-built forms cannot `POST` into Animo; activations are read-only    | Embed/link the Animo-hosted activation form; receive data via webhooks                                                                         |
| `ActivationResource` omits linked event slug | Can't build the event-scoped activation URL from `GET /activations` alone | Use the company-scoped URL (always works), or fetch the event slug from `GET /events` — see [Conventions](conventions.md#activation-form-page) |