API reference

Current identity (user, role, client slug)

The caller's own editable profile

Update the caller's own profile (presentation + contact fields only)

Self-service editing. Accepts any subset of name, color (#rrggbb), jobTitle, bio, location, company; an empty string clears a field (name must stay non-empty). Never touches system level, status, email or client — those are admin-only.

VAPID public key for browser Web Push subscription

Pass as applicationServerKey to PushManager.subscribe(). Safe to expose — it's the public half of the server's VAPID keypair.

Register (or refresh) a browser push subscription for the caller

Body is the raw PushSubscription JSON from the browser's Push API (endpoint + keys.p256dh + keys.auth). Upserted by endpoint, so re-subscribing the same device is idempotent.

Remove a browser push subscription for the caller (e.g. when disabling notifications on a device)

List the caller's active API tokens

Create an API token (plaintext returned once)

Revoke an API token

Public-facing profile card for the hover popover on a user's initials

Any signed-in user may read any user's card. availability is non-null only when the user is on Float-synced leave today ({ status: 'out', until, type }).

AI writing assistant — rewrite a draft message for clarity (any authed user)

Rewrites the draft HTML to read clearly/professionally while preserving meaning. Uses Claude when ANTHROPIC_API_KEY is set, otherwise Cloudflare Workers AI; the result is re-sanitised against the message allow-list. 503 if no AI provider is configured.

Client overview: name + active projects

Each project has { id, name, slug, isRoot }. Exactly one project per client is the root 'General' space (isRoot: true, listed first) — client-level threads/files live there; inbound email and Basecamp migrations land in it.

Stream a signed agreement PDF (proxied from DocuSeal behind portal auth; tenancy-checked)

Everything-in-one-view dashboard payload

Recent messages + files (activity stream), pinned threads, unread thread IDs for the caller, support-hours burn-down per project (hidden unless the caller is a lead on a membership for this client, or staff-and-up; hoursLogged/hours-agreed figures are for that same audience — everyone else should render % spent, never raw hours), and federation summaries. Every project listing here excludes locked projects the caller hasn't been explicitly granted (membership_projects). Each stream message carries an attachments array ({ id, filename, content_type, size_bytes, url, thumbUrl }) for files attached to that message; stream.files is standalone Files-page uploads only — files attached to a message never appear there (no double-counting). federation.sprints has one entry per currently-active Jira sprint (a project can have more than one open at once) — { projectSlug, projectName, sprintId, name, startDate, endDate, counts, recentlyCompleted }. Fetch the full board for a card via GET .../projects/{projectSlug}/sprints/{sprintId}/board. newThreadEmail is the working inbound address for starting a new thread in this client's root "General" space by email — the bare {slug}@ address (routes via the portal.numiko.com catch-all Email Routing rule); null if EMAIL_REPLY_DOMAIN isn't configured.

Client-visible Confluence pages + DocuSeal agreements (allow-listed, cached)

Doc entries are summaries (no bodyHtml) — fetch a single document for its content.

One client-visible Confluence page with its sanitized body (tenancy-checked against the client's own visible docs)

Favicon for the client's website domain (proxied + cached)

Fetches the icon for the client's mapped website domain (derived from domain_mappings), caches it in KV, and streams the bytes so client domains are never leaked to a third-party favicon service. 404 when the client has no mapped domain or none could be fetched. Also surfaced as client.faviconUrl in the client-home and dashboard payloads.

Users who can be @mentioned / added as watchers for this client

Guests are excluded from the base list. Pass ?thread=<threadId> when composing inside an existing thread to also include guests watching that thread (isGuest: true) — guests are only mentionable there; the thread's own project is also used for roster filtering (see ?project). Pass ?project=<projectSlug> so a client/guest caller only sees staff/admin/super_admin rostered on that project (project_team) — a staff+ caller always sees every unrestricted staff account regardless (staff mentioning staff is never filtered; the roster only narrows what CLIENTS see). isNumiko is system_level >= staff.

The caller's watched threads (the whole world for a single-thread guest)

Candidate participants for the participant picker (new-thread composer + ThreadView sidebar)

This client's members plus staff-and-up (same universe as /mentionable, roster-filtered to this project for a non-staff caller) with the extra fields the picker needs: email, avatar colour, and isClientLead/isProjectLead flags for default pre-selection. isClientLead is a client-side membership primary contact; isProjectLead is this project's project_team roster primary contact. Excludes the caller and guest accounts (guests are added by typing their email, which the picker also accepts as free text).

Full board for one active sprint (client-facing substitute for Jira access)

To do / in progress / done columns of { key, summary, status, statusCategory, type } — no assignee, estimate, cost data or Jira link-out. Excludes internal-labelled and sub-task issues. Reads the same cache as the dashboard sprint cards (15-min cron refresh); 404 if the project or sprintId isn't a currently-active sprint on this client's project.

Recent JSM support requests per project (cached, link-outs to help centre)

Staff sidebar client list: every active client (staff-and-up see all of them) with a personal pinned flag and lastActivityAt (for Pinned / Recently active / All clients grouping)

Pin a client to the caller's staff sidebar

Unpin a client from the caller's staff sidebar

Staff root dashboard: combined activity feed across every active client (staff-and-up see all OPEN clients; locked/Private clients and locked projects excluded unless the caller holds a membership/grant)

Each stream message carries an attachments array ({ id, filename, content_type, size_bytes, url, thumbUrl }) for files attached to that message; stream.files is standalone Files-page uploads only. sidebar feeds the staff dashboard's right-column cards: activeClients (top ~6 by message count, last 14 days), awaitingReply (open threads whose newest message is from the client side, oldest-waiting first; when ANTHROPIC_API_KEY is configured, threads whose last client message is AI-classified as a closing remark such as 'thanks, all sorted' are filtered out — classification is cached per message, runs in the background never synchronously, and fails open so an unclassified message is never hidden), pendingDrafts (weekly AI-summary drafts awaiting PM publish/discard).

Assignable Jira users for the project (async assignee picker; staff)

Create fields for a project + issue type — drives the dynamic task form (staff)

Normalised Jira createmeta fields: { fieldId, name, required, kind, allowedValues }. kind ∈ string|text|option|user|sprint|labels|array-option|number|date. Summary/description/project/issuetype are handled by the form and omitted.

Jira issue types for the project's mapped Jira project (Numiko staff only)

From Jira createmeta. 404 if no jira_project_key mapped or the caller isn't staff.

Search the project's Jira issues (comment-on-existing picker; staff)

Key-shaped queries (CHAT-142 or a bare number) resolve by key; otherwise a summary contains-match, newest first. Scoped to the project's mapped Jira project.

Active + future sprints on the project's board (for the Sprint field; staff)

List threads (message counts, unread flag, opening/latest excerpts, participants) — paginated, newest 50 + pinned first

Each thread carries message_count, unread, and preview fields for the two-column card: first_excerpt (opening post), last_excerpt + last_message_id + last_author_name + last_at (latest reply), plus participants: [{ id, name, isNumiko, isGuest, email? }] (thread watchers, for the list's avatar stack). First page returns pinned threads plus the 50 most recently updated; when hasMore is true, pass the last thread's updated_at/id as ?before/?beforeId for the next page. Search covers all threads regardless of paging. newThreadEmail is the working inbound address for starting a thread here by email — non-null only for the client's root "General" project (the bare {slug}@ address), where inbound email actually lands.

Create a thread with its first message

Thread detail: messages (HTML + plain text + attachments) and watchers. Marks the thread read for the caller.

Returns the newest 100 messages ascending plus hasMoreOlder; pass ?before=<created_at> to page backwards. Each message carries author_color, edited_at and deleted_at (deleted messages return blanked body + no attachments).

Permanently delete a thread and all its content (Numiko staff only)

Irreversibly removes the thread with its messages, attached files (including stored objects), watchers and notifications, and drops it from search. For threads created by mistake — audit-logged. 403 for non-staff callers.

Draft an initial agency reply from the thread + linked Jira issues (staff only)

Sends the thread transcript and the status of any linked/mentioned Jira issues to Claude and returns a sanitised HTML draft of the agency's next reply, to seed the composer. Never posts anything. Gated three ways: Numiko staff only (404 otherwise), the client's per-client AI opt-in (clients.ai_summaries_enabled — 403 with { error: 'ai_disabled' } when off), and ANTHROPIC_API_KEY configured (503 otherwise). Shares the per-user hourly AI cap with /api/ai/improve (429 when exceeded).

Jira/JSM issues referenced in the thread, with live status

Parses issue keys (e.g. SUP-142) from the thread's messages and resolves each to { key, summary, status, statusCategory, type, url }. Client viewers only see issues from the project's own Jira project and never internal-labelled ones; Numiko staff see any referenced key. Best-effort — empty on source failure.

oEmbed rich previews for allow-listed links in the thread's messages

Scans the thread's message bodies for allow-listed provider links (Figma, YouTube, Vimeo, Loom) and returns normalised oEmbed metadata { url, provider, type, title, authorName, thumbnailUrl, embedUrl, aspectRatio } keyed by message id. Only structured metadata + a self-constructed embed URL are returned — never the provider's raw oEmbed html. Same visibility gating as /issues; best-effort and KV-cached.

Reply to a thread

Fans out notifications: in-app for all watchers, email per prefs (mentions cut through digest mode), Slack tag for mentioned Numiko staff.

Edit a message (author only, portal-composed messages)

Replaces the body (bodyHtml, sanitized server-side) and stamps edited_at. Only the author may edit, and only 'web'-sourced messages (409 for Slack/email-synced ones). If the message was mirrored to Slack, the Slack copy is chat.update-d in place.

Delete a message (author removes own; Numiko staff moderate any)

Published messages are soft-deleted (row kept, body cleared, removed from search, attachments hidden, tombstone shown). Unpublished AI drafts are hard-deleted (staff only); discarding a thread's only message also deletes the now-empty thread (threadDeleted: true in the response). Staff deleting another user's message is recorded in the audit log.

Add a message to an existing Jira issue as a comment (Numiko staff only)

Posts the message (or edited comment HTML) as an ADF comment on issueKey via the service account, with a link back to the message. The issue must belong to the project's mapped Jira project. Links the key to the message like jira-task does.

Create a Jira task from a message (Numiko staff only)

Creates an issue via the service account with summary + an ADF description (message text + a link back to the message). fields carries the dynamic form's Jira-native field values (priority/assignee/sprint/labels/…); project/issuetype/summary/description are set server-side. clientVisible=false adds the internal label. Links the created key to the message so it shows on the message + in the thread's Linked issues.

Publish a draft AI weekly summary to the client (Numiko staff only)

Drafts are generated by the Friday cron (source=ai_summary, draft=1) and invisible to clients until published. Publishing fans out notifications. DELETE the same path (without /publish) discards a draft.

Toggle a task-list checkbox in a message (persistent shared checklist)

Flips the Nth task item (document order) and re-sanitizes the stored HTML. Any user with access to the thread may tick items (same permission level as reacting). Ticking stamps who completed it and when (data-done-by/-name/-at); unchecking clears the stamp. Does not mark the message edited.

Add a watcher by email (creates a guest account if the email is unknown)

Client users and Numiko staff only (guests can't manage watchers). Unknown emails become a guest who sees exactly the threads they're added to — guests may be added to threads across projects and clients. Responds { ok: true, added: boolean }; when the email belongs to an existing account that can't be given thread access here (a client-level user of another client — who needs a membership, not a watcher row — or an archived account), a STAFF caller gets added:false with a reason ('other_client' | 'archived'), while a non-staff (client) caller gets added:true so the endpoint can't be used to probe account existence. Rate-limited per caller.

Add a watcher (any user with access to this client)

Guests may only target themselves (self-add to a thread they can already see — the 'join thread' affordance); they can't add anyone else. Broadcasts a live 'thread' event.

Remove a watcher

Guests may only remove themselves (leave a thread); anyone else who can add participants may also remove them. Broadcasts a live 'thread' event.

A guest's watched threads across all clients (guests only; 404 for other roles)

Move a file between folders (folderId: null → root)

Download/stream file content (tenancy-checked)

Submit extracted PDF text for search indexing (client-side pdfjs extraction)

text/plain body, max 200k chars. PDFs only; first writer wins (409 once set). The text feeds the FTS index so PDF content is searchable.

JPEG thumbnail (max 480px edge) for image files

Generated server-side (eagerly on upload, lazily otherwise). 404 for non-thumbable types — fall back to /raw or a type icon.

Delete an empty folder

Folder-aware file listing

Each file has threadId and, when it was attached to a specific message (thread share / email attachment), messageId — use both to deep-link to /{clientSlug}/{projectSlug}/messages/{threadId}#msg-{messageId}.

Upload a file (multipart/form-data: file, optional folderId)

Returns { id, url, isImage }. Reference the url in an <img> for inline embeds, or pass the id in attachmentIds when posting a message.

Create a folder (optionally nested via parentId)

Start a chunked (R2 multipart) upload for a large file

For files bigger than a single request can carry (>50 MB, up to 10 GB). Returns { fileId, partSize }: split the file into partSize-byte parts, PUT each to /uploads/{fileId}/parts/{n}, then POST /uploads/{fileId}/complete with the collected { partNumber, etag } list. Small files should use the direct multipart/form-data upload instead.

Abort a half-finished chunked upload

Finish a chunked upload — assemble parts into the file

Re-checks live project access before the file becomes real. Returns the same descriptor as the direct upload ({ id, url, isImage }).

Upload one part of a chunked upload (raw body)

1-based partNumber. Each part must be ≤50 MB; all but the final part must be ≥5 MB (R2 rule). Returns { partNumber, etag } — keep the etag for /complete.

Full-text search across threads, messages and files (single client; prefer /api/search)

FTS5-backed. Snippets mark highlights with ⟦…⟧. Results carry type, title, project and a URL.

Unified search across everything the caller can see (all system levels)

FTS5-backed, scoped by system level: staff-and-up span every active client (internal content included, but never a locked project without an explicit membership_projects grant, and never a locked/Private CLIENT without a membership on it); client-level users their own client(s) (client-visible only, same locked-project rule); guests only threads they watch. Covers threads, messages, files (including extracted PDF text), client-visible Confluence pages (type 'doc') and native documents (type 'native_doc'). Results always carry clientSlug/clientName + projectSlug/projectName. ?client=<slug> sorts that client's hits first; ?limit=1..40 (default 40) supports typeahead. Snippets mark highlights with ⟦…⟧.

Portal-wide full-text search across every client the staff caller can access (Numiko staff only)

Like the per-client search but spans every active client (staff-and-up see all OPEN clients; locked/Private clients and locked projects excluded unless the caller holds a membership/grant). Results add clientSlug/clientName for filtering. 403 for non-staff.

Caller's in-app notifications for this client (latest 30 + unread count)

Mark all of the caller's notifications for this client read

A guest's in-app notifications across all clients (guests only; 404 for other roles)

Mark all of a guest's notifications read, across all clients (guests only; 404 for other roles)

Cross-client in-app notifications for staff (every active client; locked/Private-client and locked-project threads excluded unless membership/grant held) — staff-and-up only

Mark all of the caller's notifications read across accessible clients (Numiko staff only)