> ## 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. # List events > Returns the organization's events, soonest-starting last. Cursor paginated: follow `meta.next_cursor` rather than assuming page numbers. Requires the `events:read` scope. ## OpenAPI ````yaml https://api.signupbreeze.com/openapi.yaml get /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: get: tags: - Events summary: List events description: >- Returns the organization's events, soonest-starting last. Cursor paginated: follow `meta.next_cursor` rather than assuming page numbers. Requires the `events:read` scope. operationId: listEvents parameters: - in: query name: published description: Filter to published or draft events only. Omit for both. example: true required: false schema: type: boolean description: Filter to published or draft events only. Omit for both. example: true - in: query name: per_page description: Results per page, capped at 100. example: 25 required: false schema: type: integer description: Results per page, capped at 100. example: 25 - in: query name: cursor description: The cursor from a previous response's `meta.next_cursor`. example: null required: false schema: type: string description: The cursor from a previous response's `meta.next_cursor`. example: null responses: '200': description: '' content: application/json: schema: type: object example: data: - id: 019ff256-ecab-7397-b236-ed7b9dd86d3a title: Adipisci quidem nostrum qui. description: >- Odit et et modi. Nostrum omnis autem et consequatur aut. Enim non facere tempora ex voluptatem laboriosam praesentium. Adipisci molestias fugit deleniti distinctio eum doloremque id. Aliquam veniam corporis dolorem mollitia deleniti nemo. Quia officia est dignissimos neque. Odio veritatis excepturi doloribus delectus fugit qui repudiandae. Est alias tenetur ratione. slug: adipisci-quidem-nostrum-qui-459 location: |- 80483 Kovacek Causeway Moiseschester, AZ 60787-7092 is_virtual: false start_date: '2026-09-22T05:51:00+00:00' end_date: '2026-09-22T12:39:57+00:00' timezone: UTC is_published: false public_url: http://localhost/e/adipisci-quidem-nostrum-qui-459 created_at: '2026-08-11T19:40:10+00:00' updated_at: '2026-08-11T19:40:10+00:00' - id: 019ff256-ecb9-7123-893a-6ddff5525435 title: Dolores quia maiores assumenda. description: >- Officiis corporis nesciunt ut. Iure impedit molestiae ut rem est esse sint. Molestiae sunt suscipit doloribus fugiat ut aut. Error neque recusandae et ipsam dolorem et ut dicta. Assumenda consequatur ut et sunt quisquam. Repellendus ut eaque alias ratione dolores. slug: dolores-quia-maiores-assumenda-728 location: |- 876 Orland Gateway West Fideltown, VT 26594 is_virtual: false start_date: '2026-10-27T07:53:33+00:00' end_date: '2026-10-27T11:59:04+00:00' timezone: UTC is_published: false public_url: http://localhost/e/dolores-quia-maiores-assumenda-728 created_at: '2026-08-11T19:40:10+00:00' updated_at: '2026-08-11T19:40:10+00:00' links: first: null last: null prev: null next: null meta: path: / per_page: 25 next_cursor: null prev_cursor: null properties: data: type: array example: - id: 019ff256-ecab-7397-b236-ed7b9dd86d3a title: Adipisci quidem nostrum qui. description: >- Odit et et modi. Nostrum omnis autem et consequatur aut. Enim non facere tempora ex voluptatem laboriosam praesentium. Adipisci molestias fugit deleniti distinctio eum doloremque id. Aliquam veniam corporis dolorem mollitia deleniti nemo. Quia officia est dignissimos neque. Odio veritatis excepturi doloribus delectus fugit qui repudiandae. Est alias tenetur ratione. slug: adipisci-quidem-nostrum-qui-459 location: |- 80483 Kovacek Causeway Moiseschester, AZ 60787-7092 is_virtual: false start_date: '2026-09-22T05:51:00+00:00' end_date: '2026-09-22T12:39:57+00:00' timezone: UTC is_published: false public_url: http://localhost/e/adipisci-quidem-nostrum-qui-459 created_at: '2026-08-11T19:40:10+00:00' updated_at: '2026-08-11T19:40:10+00:00' - id: 019ff256-ecb9-7123-893a-6ddff5525435 title: Dolores quia maiores assumenda. description: >- Officiis corporis nesciunt ut. Iure impedit molestiae ut rem est esse sint. Molestiae sunt suscipit doloribus fugiat ut aut. Error neque recusandae et ipsam dolorem et ut dicta. Assumenda consequatur ut et sunt quisquam. Repellendus ut eaque alias ratione dolores. slug: dolores-quia-maiores-assumenda-728 location: |- 876 Orland Gateway West Fideltown, VT 26594 is_virtual: false start_date: '2026-10-27T07:53:33+00:00' end_date: '2026-10-27T11:59:04+00:00' timezone: UTC is_published: false public_url: http://localhost/e/dolores-quia-maiores-assumenda-728 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-ecab-7397-b236-ed7b9dd86d3a title: type: string example: Adipisci quidem nostrum qui. description: type: string example: >- Odit et et modi. Nostrum omnis autem et consequatur aut. Enim non facere tempora ex voluptatem laboriosam praesentium. Adipisci molestias fugit deleniti distinctio eum doloremque id. Aliquam veniam corporis dolorem mollitia deleniti nemo. Quia officia est dignissimos neque. Odio veritatis excepturi doloribus delectus fugit qui repudiandae. Est alias tenetur ratione. slug: type: string example: adipisci-quidem-nostrum-qui-459 location: type: string example: |- 80483 Kovacek Causeway Moiseschester, AZ 60787-7092 is_virtual: type: boolean example: false start_date: type: string example: '2026-09-22T05:51:00+00:00' end_date: type: string example: '2026-09-22T12:39:57+00:00' timezone: type: string example: UTC is_published: type: boolean example: false public_url: type: string example: http://localhost/e/adipisci-quidem-nostrum-qui-459 created_at: type: string example: '2026-08-11T19:40:10+00:00' updated_at: type: string example: '2026-08-11T19:40:10+00:00' links: type: object properties: first: type: string example: null nullable: true last: type: string example: null nullable: true prev: type: string example: null nullable: true next: type: string example: null nullable: true meta: type: object properties: path: type: string example: / per_page: type: integer example: 25 next_cursor: type: string example: null description: >- Pass as `cursor` to fetch the next page. Null on the last page. prev_cursor: type: string example: null nullable: true '403': description: token is missing the events:read scope content: application/json: schema: type: object example: message: Invalid ability provided. properties: message: type: string example: Invalid ability provided. 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. ````