> ## Documentation Index > Fetch the complete documentation index at: https://docs.signupbreeze.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an event > Creates an event and, optionally, all of its shifts in the same call — which is usually what you want, since an event with no shifts has nothing to sign up for. Send an `Idempotency-Key` header. Repeating a create with the same key replays the original response instead of creating a second event. Requires the `events:write` scope. ## OpenAPI ````yaml https://api.signupbreeze.com/openapi.yaml post /v1/events openapi: 3.0.3 info: title: SignUpBreeze API description: >- Manage events, shifts, and signups programmatically — from your own scripts, an automation platform, or an AI agent. ## Authentication Every request needs a bearer token, which an organization owner or admin creates under **Organization settings → API**. Tokens belong to the organization rather than to the person who created one, so an admin leaving does not break a live integration. Each token carries a set of scopes, and every endpoint states the scope it requires. A request whose token lacks the scope is refused with `403`. **Every token expires**, after at most a year and by default after exactly that. An expired token is refused with `401`, the same as a revoked one, so plan to create a replacement before the expiry date shown in settings — nothing using the old token keeps working past it. ## Rate limiting Requests are throttled per API token, not per organization — issuing more tokens does not raise the ceiling. The limit varies by plan: 30 requests/min on Free and Calendar, 120 on Starter, 300 on Pro. Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Exceeding the limit returns `429`, with `Retry-After` and `X-RateLimit-Reset` added to that response so you know when to try again. ## Idempotency Writes accept an `Idempotency-Key` header. Send the same key again and the original response is replayed rather than the write happening twice — worth using anywhere a retry is possible, which is most places an agent is involved. ## Pagination Collections are cursor paginated. Follow `meta.next_cursor` rather than assuming page numbers. ## Scoping Everything a token can reach belongs to its organization. Another organization's record answers `404` rather than `403`, so a token cannot be used to discover that it exists. version: 1.0.0 servers: - url: https://api.signupbreeze.com security: - default: [] tags: - name: Events description: >- Create and manage events. Every endpoint is scoped to the organization that owns the token — another organization's event responds `404`, not `403`, so a token cannot be used to discover that it exists. - name: Organization description: |- The organization a token belongs to. - name: Shifts description: >- The time slots volunteers sign up for. Shift times are wall-clock strings like `14:30`, interpreted in the parent event's timezone against its start date — you never send a date or an offset for a shift. - name: Signups description: >- Who has signed up. Read-only in v1: signups are created through the public event page, which is deliberately the only way a volunteer is added. externalDocs: description: SignUpBreeze documentation url: https://docs.signupbreeze.com/api-reference/introduction paths: /v1/events: post: tags: - Events summary: Create an event description: >- Creates an event and, optionally, all of its shifts in the same call — which is usually what you want, since an event with no shifts has nothing to sign up for. Send an `Idempotency-Key` header. Repeating a create with the same key replays the original response instead of creating a second event. Requires the `events:write` scope. operationId: createAnEvent parameters: - in: header name: Idempotency-Key description: '' example: a7f3c1e0-2b44-4f6e-9c1d-8e5b0a2d7f31 schema: type: string requestBody: required: true content: application/json: schema: type: object properties: title: type: string description: The event's name. example: Fall Festival description: type: string description: A longer description. Markdown is not rendered. example: Our annual fundraiser. nullable: true location: type: string description: A street address, or a URL for a virtual event. example: 12 Main St nullable: true is_virtual: type: boolean description: '' example: true location_lat: type: number description: Must be between -90 and 90. example: -89 nullable: true location_lng: type: number description: Must be between -180 and 180. example: -179 nullable: true location_data: type: object description: '' example: null properties: {} nullable: true start_date: type: string description: The day the event starts, as YYYY-MM-DD. example: '2026-09-12' end_date: type: string description: The last day, for multi-day events. Capped by your plan. example: '2026-09-13' nullable: true timezone: type: string description: An IANA timezone. Shift times are interpreted in it. example: America/Los_Angeles is_published: type: boolean description: Publish immediately. Defaults to false. example: true theme: type: string description: '' example: forest-green enum: - purple-indigo - ocean-blue - sunset-orange - forest-green - rose-pink - slate-charcoal - golden-hour - midnight nullable: true badge_label: type: string description: Must not be greater than 255 characters. example: g nullable: true shifts: type: array description: The shifts volunteers sign up for. example: - [] items: type: object nullable: true properties: title: type: string description: What the shift is called. example: Grill Master location: type: string description: Must not be greater than 255 characters. example: m nullable: true start_time: type: string description: Wall-clock start as HH:MM, in the event's timezone. example: '09:00' nullable: true end_time: type: string description: Wall-clock end as HH:MM. Must be after start_time. example: '11:00' nullable: true capacity: type: integer description: How many volunteers are needed. example: 4 required: - title - capacity required: - title - start_date - timezone responses: '201': description: '' content: application/json: schema: type: object example: data: id: 019ff256-eccd-70b9-8fb9-f8a45ef4a38e title: Eius et animi. description: >- Fugiat sunt nihil accusantium harum mollitia. Deserunt aut ab provident perspiciatis quo omnis nostrum. Adipisci quidem nostrum qui commodi incidunt iure. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci. slug: eius-et-animi-372 location: |- 981 Nitzsche Route Apt. 203 Madisenborough, MT 77824 is_virtual: false start_date: '2026-11-11T09:07:51+00:00' end_date: '2026-11-11T10:11:09+00:00' timezone: UTC is_published: false public_url: http://localhost/e/eius-et-animi-372 slots: - id: 019ff256-ecce-71f3-b7d6-5a60e0d781c3 event_id: 019ff256-eccd-70b9-8fb9-f8a45ef4a38e title: Clean-up Crew location: null is_virtual: false start_time: '2026-11-02T05:34:27+00:00' end_time: '2026-11-02T07:34:27+00:00' capacity: 8 filled: 0 remaining: 8 created_at: '2026-08-11T19:40:10+00:00' updated_at: '2026-08-11T19:40:10+00:00' created_at: '2026-08-11T19:40:10+00:00' updated_at: '2026-08-11T19:40:10+00:00' properties: data: type: object properties: id: type: string example: 019ff256-eccd-70b9-8fb9-f8a45ef4a38e title: type: string example: Eius et animi. description: type: string example: >- Fugiat sunt nihil accusantium harum mollitia. Deserunt aut ab provident perspiciatis quo omnis nostrum. Adipisci quidem nostrum qui commodi incidunt iure. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci. slug: type: string example: eius-et-animi-372 location: type: string example: |- 981 Nitzsche Route Apt. 203 Madisenborough, MT 77824 is_virtual: type: boolean example: false start_date: type: string example: '2026-11-11T09:07:51+00:00' end_date: type: string example: '2026-11-11T10:11:09+00:00' timezone: type: string example: UTC is_published: type: boolean example: false public_url: type: string example: http://localhost/e/eius-et-animi-372 slots: type: array example: - id: 019ff256-ecce-71f3-b7d6-5a60e0d781c3 event_id: 019ff256-eccd-70b9-8fb9-f8a45ef4a38e title: Clean-up Crew location: null is_virtual: false start_time: '2026-11-02T05:34:27+00:00' end_time: '2026-11-02T07:34:27+00:00' capacity: 8 filled: 0 remaining: 8 created_at: '2026-08-11T19:40:10+00:00' updated_at: '2026-08-11T19:40:10+00:00' items: type: object properties: id: type: string example: 019ff256-ecce-71f3-b7d6-5a60e0d781c3 event_id: type: string example: 019ff256-eccd-70b9-8fb9-f8a45ef4a38e title: type: string example: Clean-up Crew location: type: string example: null nullable: true is_virtual: type: boolean example: false start_time: type: string example: '2026-11-02T05:34:27+00:00' end_time: type: string example: '2026-11-02T07:34:27+00:00' capacity: type: integer example: 8 filled: type: integer example: 0 remaining: type: integer example: 8 created_at: type: string example: '2026-08-11T19:40:10+00:00' updated_at: type: string example: '2026-08-11T19:40:10+00:00' created_at: type: string example: '2026-08-11T19:40:10+00:00' updated_at: type: string example: '2026-08-11T19:40:10+00:00' '422': description: '' content: application/json: schema: oneOf: - description: validation failed type: object example: message: The title field is required. errors: title: - The title field is required. properties: message: type: string example: The title field is required. errors: type: object properties: title: type: array example: - The title field is required. items: type: string - description: the plan's active-event limit is reached type: object example: message: Your plan allows a maximum of 3 active events. error: plan_limit_reached limit: limit_type: active_events current_count: 3 max_allowed: 3 properties: message: type: string example: Your plan allows a maximum of 3 active events. error: type: string example: plan_limit_reached limit: type: object properties: limit_type: type: string example: active_events current_count: type: integer example: 3 max_allowed: type: integer example: 3 components: securitySchemes: default: type: http scheme: bearer description: >- Create a token under Organization settings → API. Tokens are shown once, on creation. They belong to the organization, not to you, so they keep working if you leave the team. API access is included on every plan; the rate limit depends on the plan. ````