Calendar, notifications and devices

These endpoints serve Rokn's mobile app and any integration that needs the same data. Every path is under /api/v1/workspaces/{slug} and follows the usual rules: bearer credential, the workspace in the path, problem-details errors.

Calendar

GET …/calendar-events?from=…&to=… (scope calendar:read) returns everything that starts in the half-open window [from, to), at most 93 days, sorted by start: stored events plus items generated from tasks due, invoices due, milestones and asset renewals. Filter with owner_user_id (that person's events and assigned tasks), client_id or project_id. Send the user's own day as two instants for "today".

GET /api/v1/workspaces/acme/calendar-events?from=2026-10-05T00:00:00%2B02:00&to=2026-10-06T00:00:00%2B02:00
Authorization: Bearer <token>

GET …/calendar-events/{id} returns one stored event. A generated item is read through its own resource (the task, invoice, milestone or asset).

Notifications

GET …/notifications lists the caller's own notifications, read and unread, newest first; add unread=true for unread only. POST …/notifications/{id}/read marks one read and POST …/notifications/read-all marks all of them. Scopes notifications:read and notifications:write. These act for a person, so they need an OAuth token: an API key is refused.

Each notification has a target — { entityType, entityId }, such as a task, ticket, invoice, contract or calendar_event — to open when it is tapped, or null for a workspace-wide notice.

Push devices

An app that receives push notifications through Expo registers the phone with PUT …/push-devices/{token} and a body of { "platform": "ios" | "android", "appVersion": "…" }, and removes it on sign-out with DELETE …/push-devices/{token}. Both are idempotent and need notifications:write on an OAuth token. Pushes carry names but never amounts, and their data names the workspace and the record to open. Fifteen minutes before a timed event on a person’s own calendar, they also get an appointment reminder (type appointment.reminder, pushed by default) whose target is that calendar_event.

Caller-ID directory

GET …/caller-id-directory (scope clients:read) returns every phone number the workspace knows — clients, their contacts and open leads — in E.164 with the label to show on an incoming call. Leads are included only for members who may read leads. Send the response's ETag back as If-None-Match: an unchanged directory answers 304 with no body. A 404 means the person no longer has this workspace, so its entries should be removed from the phone.

Rokn's own apps

Requests from Rokn's own apps count against a separate per-workspace budget of 600 requests a minute on every plan, so an integration can never use up the app's budget, nor the app yours. GET …/me reports it as limits.firstPartyRequestsPerMinute. The assistant scope and the assistant's own endpoints are available only to Rokn's apps.