{
  "openapi": "3.1.0",
  "info": {
    "title": "Animo API",
    "version": "1.1.0",
    "description": "Animo events platform API. Orchestrate setup and operations — never rebuild payments, VAT, invoicing, or form submission ingest. Read https://docs.animo.co/for-ai-agents before integrating.",
    "contact": {
      "name": "Animo support",
      "email": "support@animo.co",
      "url": "https://docs.animo.co"
    }
  },
  "servers": [
    {
      "url": "https://app.animo.co/api/v1",
      "description": "Production"
    }
  ],
  "x-mint": {
    "mcp": {
      "enabled": true
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "OAuth2 personal access token from User settings → API tokens"
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User sqid"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "job_title": {
            "type": "string",
            "nullable": true
          },
          "avatar": {
            "type": "string",
            "nullable": true
          },
          "linkedin_url": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Company": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Company sqid — use in API paths"
          },
          "slug": {
            "type": "string",
            "description": "Public URL slug"
          },
          "name": {
            "type": "string"
          },
          "tagline": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true
          },
          "logo": {
            "type": "string",
            "nullable": true
          },
          "brand_color": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Event slug (public URL segment)"
          },
          "name": {
            "type": "string"
          },
          "date_start": {
            "type": "string",
            "format": "date-time"
          },
          "date_end": {
            "type": "string",
            "format": "date-time"
          },
          "attendance_mode": {
            "type": "string",
            "enum": [
              "online",
              "offline"
            ]
          },
          "company_role": {
            "type": "string",
            "enum": [
              "organizing",
              "attending"
            ]
          },
          "locale": {
            "type": "string",
            "enum": [
              "en",
              "nl",
              "fr",
              "de",
              "pt",
              "es"
            ]
          },
          "requires_ticket_assignment": {
            "type": "boolean"
          },
          "timezone": {
            "type": "string",
            "nullable": true
          },
          "privacy_policy": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "TicketType": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "price": {
            "type": "string",
            "description": "Decimal string; 0 for free"
          },
          "currency": {
            "type": "string"
          },
          "vat_percentage": {
            "type": "number"
          },
          "availability": {
            "type": "integer"
          },
          "approval_required": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          },
          "form_id": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Order sqid"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "unit_amount": {
            "type": "integer",
            "description": "Minor currency units"
          },
          "currency": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "description": "ISO alpha-2"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "Form": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Form sqid"
          },
          "name": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "token": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/user": {
      "get": {
        "operationId": "getUser",
        "summary": "Get authenticated user",
        "description": "Returns the profile of the user associated with the bearer token.",
        "tags": [
          "User"
        ],
        "security": [
          {
            "bearerAuth": [
              "user:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "User profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/companies": {
      "get": {
        "operationId": "listCompanies",
        "summary": "List companies",
        "description": "Returns companies the authenticated user belongs to. Use company `id` (sqid) in subsequent API paths.",
        "tags": [
          "Companies"
        ],
        "security": [
          {
            "bearerAuth": [
              "companies:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated company list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Company"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/{company}/events": {
      "get": {
        "operationId": "listEvents",
        "summary": "List events",
        "tags": [
          "Events"
        ],
        "security": [
          {
            "bearerAuth": [
              "events:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Company sqid"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated events"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    },
    "/{company}/events/create": {
      "post": {
        "operationId": "createEvent",
        "summary": "Create event",
        "description": "Creates an event. Slug is derived from name on create — use PATCH to set a specific slug. For paid tickets, attendees pay through Animo hosted checkout; do not build payment UI.",
        "tags": [
          "Events"
        ],
        "security": [
          {
            "bearerAuth": [
              "events:read",
              "events:create"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "date_start",
                  "date_end",
                  "attendance_mode",
                  "locale",
                  "company_role"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "date_start": {
                    "type": "string",
                    "description": "Y-m-d H:i"
                  },
                  "date_end": {
                    "type": "string"
                  },
                  "attendance_mode": {
                    "type": "string",
                    "enum": [
                      "online",
                      "offline"
                    ]
                  },
                  "locale": {
                    "type": "string",
                    "enum": [
                      "en",
                      "nl",
                      "fr",
                      "de",
                      "pt",
                      "es"
                    ]
                  },
                  "company_role": {
                    "type": "string",
                    "enum": [
                      "organizing",
                      "attending"
                    ]
                  },
                  "requires_ticket_assignment": {
                    "type": "boolean"
                  },
                  "city": {
                    "type": "string"
                  },
                  "province": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created event",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/{company}/events/{event}": {
      "get": {
        "operationId": "getEvent",
        "summary": "Get event",
        "tags": [
          "Events"
        ],
        "security": [
          {
            "bearerAuth": [
              "events:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Event slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Event"
          }
        }
      },
      "patch": {
        "operationId": "updateEvent",
        "summary": "Update event",
        "tags": [
          "Events"
        ],
        "security": [
          {
            "bearerAuth": [
              "events:read",
              "events:update"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated event"
          }
        }
      }
    },
    "/{company}/event/{organizingEvent}/ticket-types": {
      "get": {
        "operationId": "listTicketTypes",
        "summary": "List ticket types",
        "tags": [
          "Ticket types"
        ],
        "security": [
          {
            "bearerAuth": [
              "events:read",
              "ticket-types:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "organizingEvent",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_form",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ticket types"
          }
        }
      }
    },
    "/{company}/event/{organizingEvent}/ticket-types/create": {
      "post": {
        "operationId": "createTicketType",
        "summary": "Create ticket type",
        "description": "Paid tickets require Mollie connected. Link attendees to hosted ticket URL — do not build checkout.",
        "tags": [
          "Ticket types"
        ],
        "security": [
          {
            "bearerAuth": [
              "events:read",
              "ticket-types:create"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "organizingEvent",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "price",
                  "vat_percentage"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "price": {
                    "type": "number"
                  },
                  "vat_percentage": {
                    "type": "number"
                  },
                  "description": {
                    "type": "string"
                  },
                  "form_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created ticket type"
          }
        }
      }
    },
    "/{company}/event/{organizingEvent}/orders/create/{ticketType}": {
      "post": {
        "operationId": "createOrder",
        "summary": "Create order",
        "description": "Creates a registration order. For paid tickets, redirect attendee to hosted checkout at /o/{order-id}/checkout — do not collect payment yourself.",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "bearerAuth": [
              "events:read",
              "orders:create"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "organizingEvent",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ticketType",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "first_name",
                  "last_name",
                  "email",
                  "country",
                  "is_business",
                  "quantity"
                ],
                "properties": {
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "country": {
                    "type": "string"
                  },
                  "is_business": {
                    "type": "boolean"
                  },
                  "quantity": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created order"
          }
        }
      }
    },
    "/{company}/forms": {
      "get": {
        "operationId": "listForms",
        "summary": "List forms",
        "tags": [
          "Forms"
        ],
        "security": [
          {
            "bearerAuth": [
              "forms:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated forms"
          }
        }
      }
    },
    "/{company}/forms/create": {
      "post": {
        "operationId": "createForm",
        "summary": "Create form",
        "description": "Defines a form for attachment to ticket types. Collect answers on Animo-hosted pages — do not POST submissions from custom frontends.",
        "tags": [
          "Forms"
        ],
        "security": [
          {
            "bearerAuth": [
              "forms:create"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "fields"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created form"
          }
        }
      }
    },
    "/{company}/activations": {
      "get": {
        "operationId": "listActivations",
        "summary": "List activations",
        "tags": [
          "Activations"
        ],
        "security": [
          {
            "bearerAuth": [
              "activations:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated activations"
          }
        }
      }
    },
    "/{company}/webhooks/attach": {
      "post": {
        "operationId": "attachWebhook",
        "summary": "Attach webhook",
        "description": "Requires Pro plan (USE_INTEGRATIONS). Persist webhook payloads locally — there is no GET backfill for submissions or leads.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "bearerAuth": [
              "submissions:subscribe"
            ]
          }
        ],
        "parameters": [
          {
            "name": "company",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "url",
                  "events"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created"
          },
          "403": {
            "description": "Pro plan required for integrations"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "User",
      "description": "Authenticated user"
    },
    {
      "name": "Companies",
      "description": "Company context"
    },
    {
      "name": "Events",
      "description": "Event management"
    },
    {
      "name": "Ticket types",
      "description": "Ticket types for organizing events"
    },
    {
      "name": "Orders",
      "description": "Registrations and orders"
    },
    {
      "name": "Forms",
      "description": "Form definitions"
    },
    {
      "name": "Activations",
      "description": "Lead-generation activations"
    },
    {
      "name": "Webhooks",
      "description": "Outbound webhooks (Pro)"
    }
  ]
}