API Conventions · Developers

Every endpoint in the Dailybot public API follows the same conventions for identifiers, timestamps, field casing, pagination, and versioning. Learn them once here and every reference page will read exactly as you expect.

Identifiers

Every resource has a globally unique `uuid` (RFC 4122 v4). UUIDs are stable, opaque, and the safe key to use in your integration. Some resources also have a numeric `id` for legacy compatibility — prefer `uuid` for anything new.

Timestamps

All timestamps are ISO-8601 in UTC with millisecond precision (e.g. `2026-07-02T14:33:19.412Z`). Fields ending in `_at` are timestamps; fields ending in `_date` are date-only (`YYYY-MM-DD`). We never emit local-time strings.

Field casing

All JSON keys are `snake_case` (`first_name`, `created_at`). URL path segments are `kebab-case` (`/pending-invitations/`, `/agent-reports/`). Query parameters are `snake_case` (`include_email`, `only_active`).

Pagination

Two pagination styles ship in the API. `limit` + `offset` for classic browse endpoints (users, teams, kudos). `page` + `page_size` for indexed pagination (mood, forms). Every list response is wrapped in `{ count, next, previous, results }`; walk `next` until it is `null`.

Versioning

The public API is versioned by URL prefix (`/v1/`). Additive changes (new endpoints, new optional fields, new enum values that fall back to defaults) may land at any time. Breaking changes ship behind a new prefix (`/v2/`) with a minimum 6-month sunset window on the prior version. See [/developers/api-changelog](/developers/api-changelog) for the running log.

Idempotency

All `GET`, `PATCH`, `DELETE` requests are idempotent by HTTP semantics — retrying them is safe. `POST` requests that create a resource are, in the general case, *not* idempotent; a naive retry after a network blip can create duplicate resources. When you retry after a 5xx or network error, always re-read the resource by its natural key (email, name, external id) first and only re-create if the read returns 404. Retry policy details live at [/developers/errors#retry-policy](/developers/errors#retry-policy).

null vs. missing

A field set to `null` explicitly means "this attribute has no value". A field that is absent from the response means "the caller does not have permission to see it" or "the field was not requested via an include-flag". Do not treat the two identically.