Base URL and format

Environments

All requests use HTTPS (TLS 1.2 or newer). Plain-HTTP requests are refused.

The API version is carried in the path (e.g. /v1/users); only v1 is currently published.

Auth model

• Partner-scoped endpoints (token issuance, user creation, tenant administration, queue configuration) authenticate with the tenant API key in the taih-tenant-key header.
• Member-scoped endpoints (anything under /v1/users/{user_id}/… unless explicitly marked otherwise) authenticate with a member bearer token in the authorization: Bearer <access_token> header.
• Never send both headers on the same request.

Standard headers

Header names are case-insensitive; examples are shown in lowercase for consistency.

accept: application/json
content-type: application/json
authorization: Bearer <access_token>
taih-tenant-key: <tenant_api_key>

The choice of taih-tenant-key vs authorization: Bearer is determined per endpoint.

Resource conventions

• JSON request and response field names use snake_case.
• Path parameter placeholders (e.g. {user_id}) use snake_case.
• URL path segments use kebab-case (e.g. /workout-plans, /health-score).
• IDs are UUIDs unless otherwise documented.
• Enum values use snake_case.

Dates and timestamps

• Timestamps (instants in time; e.g. created_at, updated_at, scheduled_at) use ISO 8601 UTC strings, for example 2026-03-16T08:00:00Z. Responses are always UTC; clients convert to local for display.
• Dates (calendar days; e.g. test_date, birthday, daily metric date) use YYYY-MM-DD with no time-of-day or timezone, for example 2026-03-10.
• Daily metric buckets (steps, sleep, workouts, body, vitals, etc.) are keyed by the user's local calendar day, derived from the user's stored timezone; not UTC. A date of 2026-03-10 means the user's local March 10, so a workout starting at 11pm Pacific stays on March 10.
• Date-window query params (start_date, end_date) are interpreted in the user's local timezone and are inclusive on both ends. Inputs must be plain YYYY-MM-DD strings; sending a timezone offset or time-of-day component returns 422 validation_error.

Pagination

All list endpoints support offset-based pagination unless otherwise documented.

Query parameters

• limit: integer, default 25, max 100, unless otherwise documented.
• offset: integer, default 0.

Paginated response shape

{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0
  }
}

Validation rules

• If limit is less than 1 or greater than 100, return 422 validation_error.
• If offset is negative, return 422 validation_error.

Filtering & sorting

List endpoints may support endpoint-specific filters and sorting. Unless otherwise documented:

• Exact-match filters are passed as query parameters.
• Date-window filters use start_date and end_date.
• Unknown filter parameters return 400 invalid_request.
• sort_by / sort_order are available per-endpoint; unsupported sort fields return 422 validation_error.

Request tracing

Clients may include a W3C traceparent header (or legacy x-request-id) to propagate trace context. The API echoes the received header in the response and includes it in server logs.

Success response conventions

• Collection reads: { "data": [...], "pagination": { ... } }
• Single-resource reads: { "data": { ... } }
• Create operations: 201 Created with { "data": { ... } }
• Update operations: 204 No Content
• Delete operations: 204 No Content unless otherwise documented

Request idempotency

• POST endpoints accept an optional Idempotency-Key request header (case-insensitive) so partners can safely retry after a network error without the request being processed twice.
• The server keys the response on this header value (scoped to the authenticated tenant or member). Subsequent requests with the same key return the original response without re-processing the request body.
• Reusing an Idempotency-Key with a different request body for the same endpoint returns 409 conflict.
• Keys should be partner-generated UUIDs and are retained for 24 hours, after which the same key may be reused for a new request.