<!-- https://headless-lms.dev/docs/api/events -->

# Events

Live sessions at a set time: their details, location, recording and files

- [List events](https://headless-lms.dev/docs/api/events/listEvents): Requires `events:read`. Every event the caller holds `events:read` on, drafts and canceled included. `from` and `to` keep the events that overlap the range.
- [Create an event](https://headless-lms.dev/docs/api/events/createEvent): Requires `events:write`. The event starts as a draft. 400 when it ends before it starts.
- [Get an event](https://headless-lms.dev/docs/api/events/getEvent): Requires `events:read`.
- [Update an event](https://headless-lms.dev/docs/api/events/updateEvent): Requires `events:write`. Changes only the fields sent; `status` publishes or unpublishes it. `thumbnailAssetId` must be a ready library image (409 `conflict` otherwise); null clears it. A file it does not already use must be uploaded for it, or the caller needs `media:read` (403 otherwise). 409 `canceled` when the event is canceled.
- [Delete an event](https://headless-lms.dev/docs/api/events/deleteEvent): Requires `events:delete`. Its attendees lose it; its library files survive.
- [Cancel an event](https://headless-lms.dev/docs/api/events/cancelEvent): Requires `events:write`. Canceling is final. 409 `canceled` when it is already canceled.
- [List an event's files in order](https://headless-lms.dev/docs/api/events/listEventAssets): Requires `events:read`.
- [Attach a file to an event](https://headless-lms.dev/docs/api/events/addEventAsset): Requires `events:write`. Added last. 409 when the file is not a ready library file or is already attached. A file not uploaded for the event needs `media:read` (403 otherwise). Returns the event's files.
- [Reorder an event's files](https://headless-lms.dev/docs/api/events/reorderEventAssets): Requires `events:write`. Send every attached file id exactly once (409 otherwise). Returns the event's files.
- [Set a file's display name within an event](https://headless-lms.dev/docs/api/events/renameEventAsset): Requires `events:write`. Null falls back to the filename. Returns the event's files.
- [Remove a file from an event](https://headless-lms.dev/docs/api/events/removeEventAsset): Requires `events:write`. The library file itself survives. Returns the event's files.
- [List an event's attendees](https://headless-lms.dev/docs/api/events/listEventAttendees): Requires `events:read`. On the event or the org. The people attending, directly or through a bundle, by grant date. `source` is `bundle` for someone who attends only through a bundle.
- [Add an attendee to an event](https://headless-lms.dev/docs/api/events/addEventAttendee): Requires `access:write`, or `events:write` on the event or the org. Grants the event to the person, with source `manual`. Adding someone who already attends changes nothing. 404 when the event or the person does not exist; 409 `not_published`, `ended` or `full`.
- [Remove an attendee from an event](https://headless-lms.dev/docs/api/events/removeEventAttendee): Requires `access:write`, or `events:write` on the event or the org. Revokes the person's direct grant to the event. 404 when they have no direct active grant; someone who attends only through a bundle has none.
- [An event's attendance figures](https://headless-lms.dev/docs/api/events/getEventAnalytics): Requires `events:read`. On the event or the org. The attendees now and by source, the capacity, the revoked direct grants, and the current direct grants by grant date before the start.
- [List the events you can see](https://headless-lms.dev/docs/api/events/listMemberEvents): For a member of the organization. The published `public` events, and the published and canceled events you attend; with `events:read`, every published and canceled event it covers. Each as the event read returns it.
- [Create an event from the member app](https://headless-lms.dev/docs/api/events/createMemberEvent): Requires `events:write`. The event starts as a draft. 400 when it ends before it starts.
- [Get an event, with what you can do with it](https://headless-lms.dev/docs/api/events/getMemberEvent): With `events:read` on the event or the org: the event in any status. As an attendee, directly or through a bundle: the published or canceled event, with the recording after the end when replay is on. Otherwise a published `public` event without its location, files and recording. 404 for anything else.
- [Update an event you run](https://headless-lms.dev/docs/api/events/updateMemberEvent): Requires `events:write`. Changes only the fields sent; `status` publishes or unpublishes it. `thumbnailAssetId` must be a ready library image (409 `conflict` otherwise); null clears it. A file it does not already use must be uploaded for it, or the caller needs `media:read` (403 otherwise). 409 `canceled` when the event is canceled.
- [Delete an event you can delete](https://headless-lms.dev/docs/api/events/deleteMemberEvent): Requires `events:delete`. Its attendees lose it; its library files survive.
- [Download an event as a calendar file](https://headless-lms.dev/docs/api/events/getEventCalendar): An iCalendar file with the title, the times and the event page. The location and the meeting link are included when the event read returns them. 404 when the event read does.
- [List the attendees of an event you run](https://headless-lms.dev/docs/api/events/listMemberEventAttendees): Requires `events:read`. On the event or the org. The people attending, directly or through a bundle, by grant date. `source` is `bundle` for someone who attends only through a bundle.
- [Add an attendee to an event you run](https://headless-lms.dev/docs/api/events/addMemberEventAttendee): Requires `access:write`, or `events:write` on the event or the org. Grants the event to the person, with source `manual`. Adding someone who already attends changes nothing. 404 when the event or the person does not exist; 409 `not_published`, `ended` or `full`.
- [Cancel an event you run](https://headless-lms.dev/docs/api/events/cancelMemberEvent): Requires `events:write`. Canceling is final. 409 `canceled` when it is already canceled.
- [List the files of an event you run, in order](https://headless-lms.dev/docs/api/events/listMemberEventAssets): Requires `events:read`.
- [Attach a file to an event you run](https://headless-lms.dev/docs/api/events/addMemberEventAsset): Requires `events:write`. Added last. 409 when the file is not a ready library file or is already attached. A file not uploaded for the event needs `media:read` (403 otherwise). Returns the event's files.
- [Reorder the files of an event you run](https://headless-lms.dev/docs/api/events/reorderMemberEventAssets): Requires `events:write`. Send every attached file id exactly once (409 otherwise). Returns the event's files.
- [Set a file's display name within an event you run](https://headless-lms.dev/docs/api/events/renameMemberEventAsset): Requires `events:write`. Null falls back to the filename. Returns the event's files.
- [Remove a file from an event you run](https://headless-lms.dev/docs/api/events/removeMemberEventAsset): Requires `events:write`. The library file itself survives. Returns the event's files.
- [Register for an event](https://headless-lms.dev/docs/api/events/registerForEvent): Any active member of the organization registers themselves for a published `public` event that has not started, with source `self`. 403 when the event is `private`; 404 when it does not exist or is not published; 409 `already_registered`, `started` or `full`.
- [Cancel your registration for an event](https://headless-lms.dev/docs/api/events/cancelEventRegistration): Any active member of the organization revokes their own direct grant to the event, which frees the place. 404 when the caller has no direct active grant.
- [Remove an attendee from an event you run](https://headless-lms.dev/docs/api/events/removeMemberEventAttendee): Requires `access:write`, or `events:write` on the event or the org. Revokes the person's direct grant to the event. 404 when they have no direct active grant; someone who attends only through a bundle has none.
