Events
Company events: list what is coming up, add, reschedule and remove.
Company events: list what is coming up, add, reschedule and remove.
Generated from the OpenAPI spec by
npm run docs:api -w api. Do not edit this page — change the decorators inapps/api/src/and regenerate.
Conventions
- Auth — a session on every route: the cookie on web, the bearer token on mobile. See Authentication.
- Errors — every non-2xx response has the body described in Errors.
- Types — a
?after a field name means it is optional;| nullmeans it is present but may be null.
Endpoints
GET /api/v1/events — Upcoming events
Soonest first, past events excluded. A plain array capped by limit, not a page.
| Query | Type | Required | Notes |
|---|---|---|---|
limit | number | no | Rows per page. Defaults to 20, capped at 50. |
Returns 200 → CompanyEventResponse[]
| Error | When |
|---|---|
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
POST /api/v1/events — Add an event
Open to anyone signed in, the same way posting is. Send startsAt as ISO 8601 with the device’s offset — it is stored as timestamptz, so an event created in one timezone reads correctly in another.
Body — WriteEventDto
Returns 201 → CompanyEventResponse
| Error | When |
|---|---|
400 | The request was rejected. message is an array of field errors when validation failed. |
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
PATCH /api/v1/events/{eventId} — Reschedule an event
Only the time may change. Renaming or moving it is a different event — create that one and remove this. Requires canManage on the event.
| Path parameter | Type | Notes |
|---|---|---|
eventId | string |
Body — RescheduleEventDto
Returns 200 → CompanyEventResponse
| Error | When |
|---|---|
400 | The request was rejected. message is an array of field errors when validation failed. |
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
404 | No such event. |
DELETE /api/v1/events/{eventId} — Remove an event
Your own, or anything if you are a super admin.
| Path parameter | Type | Notes |
|---|---|---|
eventId | string |
Returns 204 → no body
| Error | When |
|---|---|
401 | No valid session. Clear the stored token and sign in again. |
403 | Signed in, but not allowed to do this. |
404 | No such event. |
Data models
CompanyEventResponse
| Field | Type | Notes |
|---|---|---|
id | string | |
title | string | |
startsAt | string ISO 8601 | Stored with its offset, so it reads correctly in any timezone. |
endsAt | string ISO 8601 | null | |
location | string | Empty string when unset, never null. |
createdBy | MentionResponse | |
canManage | boolean | Whether the viewer may reschedule or remove this one — their own event, or anything if they are a super admin. Drive the edit affordance off this rather than comparing ids yourself. |
MentionResponse
| Field | Type | Notes |
|---|---|---|
id | string | |
name | string | |
image | string | null |
WriteEventDto
| Field | Type | Notes |
|---|---|---|
title | string | ≤ 120 chars |
startsAt | string | ISO 8601, sent by the browser with its offset. Stored as timestamptz, so an event scheduled in one timezone reads correctly in another. |
endsAt? | string | |
location? | string | ≤ 120 chars |
RescheduleEventDto
| Field | Type | Notes |
|---|---|---|
startsAt | string | |
endsAt? | string |