Conventions

PagingCopy Anchor Link

Every cursor-paged list returns the same envelope:

{
  "items": [ … ],
  "nextCursor": "MjAyNi0wOS0xMFQwNzoxNjoyMy4wOTZafDAxSg",
  "total": 214
}

• Pass nextCursor back as ?cursor= for the next page.
• nextCursor: null means you have reached the end.
• limit defaults to 20, capped at 50. Anything larger is silently clamped.
• total is the size of the whole filtered set and is present on some lists only.

Cursors are opaque. Do not parse, construct or persist them across sessions.

Some short lists — notifications, events, teams, contributors, org chart — return a plain array capped by limit, not a page. They are marked as such below.

ErrorsCopy Anchor Link

Non-2xx responses are Nest error bodies:

{ "statusCode": 400, "message": "Write something before posting.", "error": "Bad Request" }

message is a string, or an array of strings when validation rejected several fields at once. Handle both:

val text = when (val m = body.message) {
    is List<*> -> m.firstOrNull()?.toString()
    else -> m?.toString()
} ?: "Something went wrong. Please try again."

The messages are written to be shown to the person as-is. Prefer them over your own generic copy.

Dates, ids, empty valuesCopy Anchor Link

• Timestamps are ISO 8601 with offset (2026-09-10T07:16:23.096Z). Send the device's own offset on write; the server stores timestamptz, so an event created in one timezone reads correctly in another.
• Two date-only fields — joinedOn on a profile and startedAt/endedAt on a timeline entry — are YYYY-MM-DD.
• Ids are opaque strings. Do not assume a format or an ordering.
• Text fields are "" when unset, never null. Objects and dates are null when absent. Model them accordingly — a non-null String with a default of "" is right for title, bio, location, preview, message, note.

Request bodiesCopy Anchor Link

Content-Type: application/json, except uploads (multipart/form-data).

Validation is strict: an unknown field is a 400, not an ignored key. Do not echo the whole object back on a PATCH — send only what changed. The one exception is PATCH /posts/{postId}, which takes the whole post (Writing a post).