---
title: "Create a Discord scheduled event"
method: POST
path: "/v1/discord/guilds/{guildId}/events"
tags: ["Discord"]
---

# Create a Discord scheduled event

`POST /v1/discord/guilds/{guildId}/events`

Create a guild scheduled event. Three event types, selected via the
discriminator on `entity.type`:

  - `external` — off-platform (Zoom, in-person, livestream). Requires
    both `location` and `endsAt`. Most common type for scheduler
    integrations.
  - `voice` — hosted in a Discord voice channel. Requires `channelId`.
  - `stage` — hosted in a Discord stage channel. Requires `channelId`.

Bot needs MANAGE_EVENTS in the guild. Existing installs (pre-events
PR) need a re-invite OR a server admin manually granting the
permission — see route header for details.

## Path parameters

- `guildId` string, required

## Request body

- object
  - `accountId` string, required
  - `name` string, required
  - `description` string
  - `startsAt` string, date-time, required — ISO 8601 start time. Must be in the future.
  - `entity` union, required
    - object
      - `type` 'external', required
      - `location` string, required — Where the event takes place (e.g. "Zoom link", "123 Main St")
      - `endsAt` string, date-time, required
    - object
      - `type` 'voice', required
      - `channelId` string, required — Voice channel snowflake.
      - `endsAt` string, date-time
    - object
      - `type` 'stage', required
      - `channelId` string, required — Stage channel snowflake.
      - `endsAt` string, date-time
  - `imageDataUri` string — Optional cover image as a base64 data URI.

## Response `200`

Event created.

- object
  - `data` DiscordScheduledEvent — Discord guild scheduled event. Returned by /v1/discord/guilds/{guildId}/events endpoints. Fields below are the subset Zernio consumes — Discord may return more (e.g. creator, image hash) which we pass through verbatim.
    - `id` string — Event snowflake ID
    - `guild_id` string
    - `channel_id` string, nullable — Voice/stage channel ID; null for external events.
    - `creator_id` string, nullable
    - `name` string
    - `description` string, nullable
    - `scheduled_start_time` string, date-time
    - `scheduled_end_time` string, date-time, nullable — Required for external events; optional for voice/stage.
    - `privacy_level` 2 — Always 2 (GUILD_ONLY) — Discord deprecated PUBLIC events.
    - `status` 1 | 2 | 3 | 4 — 1=SCHEDULED, 2=ACTIVE, 3=COMPLETED, 4=CANCELED
    - `entity_type` 1 | 2 | 3 — 1=STAGE_INSTANCE, 2=VOICE, 3=EXTERNAL
    - `entity_id` string, nullable
    - `entity_metadata` object, nullable
      - `location` string — External event location string.
    - `user_count` integer — Number of members who RSVP'd. Only present when withUserCount=true on list.
    - `image` string, nullable — Cover image hash; build URL via cdn.discordapp.com.

## Other responses

- `400` — Validation error (missing required fields for the chosen entity type, malformed snowflake, past startsAt, etc.).
- `401` — Unauthorized
- `404` — Discord account not found.
- `502` — Bot lacks MANAGE_EVENTS in the guild.

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)