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

# Create Event

> Create a new event in your organization

# Create Event

Creates a new event in your organization. A default "General Admission"
ticket class is created automatically with the price (or free flag) from
the request body so the event is immediately bookable.

Requires the `events:write` scope.

## Idempotency

Pass an `Idempotency-Key` header (max 255 chars) to make POST retries safe. The first request executes the create; subsequent requests with the same key within 24 hours replay the original response verbatim — including the original status code — and add an `Idempotent-Replay: true` response header. Keys are scoped per API key, so two integrations can use the same key value without collision.

Two concurrent requests with the same key return `409 idempotent_request_in_progress` to the second caller.

## Request Body

<ParamField body="name" type="string" required>
  Event name (max 200 chars).
</ParamField>

<ParamField body="start" type="object" required>
  <Expandable>
    <ParamField body="utc" type="string" required>ISO-8601 datetime, or a local `YYYY-MM-DDTHH:mm` string interpreted in `timezone`.</ParamField>
    <ParamField body="timezone" type="string">IANA timezone (e.g. `America/New_York`). Defaults to UTC.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="end" type="object" required>
  <Expandable>
    <ParamField body="utc" type="string" required>Same formats as `start.utc`. Must be after `start`.</ParamField>
    <ParamField body="timezone" type="string">Must match `start.timezone` if provided.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="location" type="string" required>
  Physical address, OR a virtual meeting URL (`https://...`). When a URL
  is provided the event is flagged as virtual and the URL is stored as
  the meeting link.
</ParamField>

<ParamField body="currency" type="string">
  ISO-4217 currency code. Defaults to the organization's currency.
</ParamField>

<ParamField body="capacity" type="integer">
  Maximum number of tickets that can be sold. `0` or omitted means unlimited.
</ParamField>

<ParamField body="ticket_price" type="number">
  Price for the default General Admission ticket class. `0` or omitted means free.
</ParamField>

<ParamField body="require_approval" type="boolean">
  Whether registrations require organizer approval. Defaults to `false`.
</ParamField>

<ParamField body="is_private" type="boolean">
  Whether the event is hidden from public listings. Defaults to `false`.
</ParamField>

<ParamField body="description" type="string">
  Long-form description shown on the event page.
</ParamField>

<ParamField body="space_identifier" type="string">
  Space the event belongs to. Defaults to `GENERAL`.
</ParamField>

## Response

Returns the created event with `201 Created`.

<ResponseField name="data" type="object">
  Same schema as [Get Event](/api-reference/events/get-event).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    -H "X-API-KEY: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Summer Launch Party",
      "start": { "utc": "2026-07-15T18:00", "timezone": "America/New_York" },
      "end":   { "utc": "2026-07-15T22:00", "timezone": "America/New_York" },
      "location": "Convention Center, New York",
      "capacity": 250,
      "ticket_price": 0
    }' \
    "https://www.gomry.com/api/v1/events"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "AbCdEfGhIjKlMnOpQrSt",
      "name": "Summer Launch Party",
      "status": "active",
      "registration_status": "open",
      "currency": "usd",
      "capacity": 250,
      "tickets_sold": 0,
      "start": { "utc": "2026-07-15T22:00:00.000Z", "timezone": "America/New_York" },
      "end":   { "utc": "2026-07-16T02:00:00.000Z", "timezone": "America/New_York" },
      "venue": { "name": "Convention Center, New York", "address": "Convention Center, New York", "city": null, "state": null, "country": null },
      "created_at": "2026-05-24T10:00:00.000Z",
      "updated_at": "2026-05-24T10:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "end must be after start"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "insufficient_scope",
    "message": "This API key does not have 'write' access to 'events'.",
    "required_scope": "events:write"
  }
  ```
</ResponseExample>