Write to the card's people
const url = 'http://localhost:8000/api/clients/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/thread/messages/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"text":"How did the run feel?"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8000/api/clients/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/thread/messages/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "text": "How did the run feel?" }'Plain text up to 4,000 characters, and an optional reference. A reference is a kind and ids — session, session_moment (params.at_ms), metric (params.metric_key), report, plan_step (params.step_id); the server builds the card. Its subject must be this card’s (400 reference_not_found otherwise). release: true shares the referenced session or report with the client’s side in the same send (400 release_not_applicable without one; 409 not_releasable / report_covers_other_athletes posts nothing). 400 empty_message with neither text nor a reference. 403 not_a_team_member for staff, who read and do not write; 409 no_client_access while nobody on the client’s side holds access.
A coach of the card’s team. Every route answers 404 while client access is switched off on the environment, and 404 client_not_found for a card of another team; a partner API key and a client’s own account get 403. Reading stays open on every plan; posting and editing are 402 on a read-only team or a plan without client access; deleting one’s own message is not. 429 past the account’s rate (chat_read 240/min for reads, chat_post 30/min for writes).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”The cards’ language: en · ru · es.
metric (default) · imperial.
Request Body
Section titled “Request Body”POST /api/clients/<id>/thread/messages/ (ThreadMessageInput).
object
Plain text, at most 4000 characters; links become clickable on render, nothing else is interpreted.
A kind and ids — never content: the server builds the card.
object
document is the server’s own (the document_shared notice): 400 reference_not_allowed.
session- Sessionsession_moment- Moment of a sessionmetric- Metric of a sessionreport- Reportplan_step- Plan stepdocument- Document on the athlete
The session, the Solutions run, or the plan (for plan_step).
object
session_moment: the second, in ms.
metric: a metric row of the session, or a bilateral stem.
plan_step: the step of the plan.
Share the referenced session or report with the client’s side in the same send (contract change 2): without it, an unshared result reads as a placeholder there.
Examples
A message
{ "text": "How did the run feel?"}Discuss a result, sharing it
{ "text": "Look at your cadence here.", "reference": { "kind": "session", "subject_id": "5e2b9c41-7d3a-4f80-9b6e-1c0d2e3f4a51" }, "release": true}POST /api/clients/<id>/thread/messages/ (ThreadMessageInput).
object
Plain text, at most 4000 characters; links become clickable on render, nothing else is interpreted.
A kind and ids — never content: the server builds the card.
object
document is the server’s own (the document_shared notice): 400 reference_not_allowed.
session- Sessionsession_moment- Moment of a sessionmetric- Metric of a sessionreport- Reportplan_step- Plan stepdocument- Document on the athlete
The session, the Solutions run, or the plan (for plan_step).
object
session_moment: the second, in ms.
metric: a metric row of the session, or a bilateral stem.
plan_step: the step of the plan.
Share the referenced session or report with the client’s side in the same send (contract change 2): without it, an unshared result reads as a placeholder there.
POST /api/clients/<id>/thread/messages/ (ThreadMessageInput).
object
Plain text, at most 4000 characters; links become clickable on render, nothing else is interpreted.
A kind and ids — never content: the server builds the card.
object
document is the server’s own (the document_shared notice): 400 reference_not_allowed.
session- Sessionsession_moment- Moment of a sessionmetric- Metric of a sessionreport- Reportplan_step- Plan stepdocument- Document on the athlete
The session, the Solutions run, or the plan (for plan_step).
object
session_moment: the second, in ms.
metric: a metric row of the session, or a bilateral stem.
plan_step: the step of the plan.
Share the referenced session or report with the client’s side in the same send (contract change 2): without it, an unshared result reads as a placeholder there.
Responses
Section titled “Responses”One message (ThreadMessage).
object
The author’s participant id; null once their account is gone.
coach- Coachathlete- Athleteguardian- Parent or guardian
Coach side: a name, else an address. Client side: a name only, never an address — empty when the person gave none.
Empty once deleted, and for a shared result nobody reviewed.
kind: session — a whole session.
object
True: kind alone — the card cannot be shown to this reader (or its subject is gone).
The discriminator.
session- session
kind: session_moment — a moment of a session’s clip.
object
True: kind alone — the card cannot be shown to this reader (or its subject is gone).
The discriminator.
session_moment- session_moment
Where in the clip, in milliseconds.
kind: metric — one metric of a session.
object
True: kind alone — the card cannot be shown to this reader (or its subject is gone).
The discriminator.
metric- metric
The value as the session reads it, with its unit.
kind: report — a Solutions report.
object
True: kind alone — the card cannot be shown to this reader (or its subject is gone).
The discriminator.
report- report
kind: plan_step — a step of an agent’s plan. The coach side reads
its title, the agent and the agent thread; the client side its place in
the plan and whether it is done (the title is “Plan step N” — AI text
stays coach-only).
object
True: kind alone — the card cannot be shown to this reader (or its subject is gone).
The discriminator.
plan_step- plan_step
Client side: its place in the plan.
Client side: marked done.
Coach side only.
Coach side only.
kind: document — a document on the athlete a coach shared (#2693
S5), carried only by the document_shared notice. Never its file name,
the problem it is filed under or who uploaded it.
object
True: kind alone — the card cannot be shown to this reader (or its subject is gone).
The discriminator.
document- document
medical, imaging, clearance, consent_form, insurance or other.
The coach’s title; may be empty — name it by its kind.
The date on the paper.
result_shared- Result sharedclient_upload- Client sent a clipupload_refused- Client’s clip refused: team out of analysesdocument_shared- Document shared
Null for a message someone wrote.
result_shared- Result sharedclient_upload- Client sent a clipupload_refused- Client’s clip refused: team out of analysesdocument_shared- Document shared
Soft delete: the row stays and reads “message deleted”.
Examples
{ "id": "3f2a1b0c-0000-4000-8000-0000000000d3", "author_id": "c0ac4000-0000-4000-8000-0000000000c1", "author_role": "coach", "author_name": "Kim Larsen", "text": "Nice cadence on this one — let's keep the stride short next week.", "reference": { "kind": "session", "placeholder": false, "session_id": "5e2b9c41-7d3a-4f80-9b6e-1c0d2e3f4a51", "activity": "running", "title": "Treadmill check", "recorded_at": "2026-11-02T09:40:00Z", "thumbnail_url": null }, "event": null, "created_at": "2026-11-02T10:16:00Z", "edited_at": null, "deleted": false}object
Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).
Examples
400 — nothing to say
{ "detail": "empty_message"}400 — not this card's
{ "detail": "reference_not_found"}object
Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).
Example generated
{ "detail": "example"}The team is read-only, or its plan does not include client access.
object
One of eight canonical strings. The front-end paywall switches copy + CTA on this value (exact string equality — do not localise). quota_exhausted / seat_limit_reached / client_limit_reached / feature_not_in_plan lead to an upgrade CTA; subscription_suspended leads to a Billing Portal CTA so the buyer can update their payment method; exercise_not_in_plan leads to a contact-us CTA — the movement list is sales-managed, no tier adds to it (#2030). trial_expired / access_ended mean the team is read-only (#2901): everything opens, nothing new is created; they lead to a subscribe CTA and always carry reset_at: null.
quota_exhausted- Session quota for the period reached 0subscription_suspended- Stripe dunning in flight (past_due / unpaid)seat_limit_reached- Adding another team member would exceed plan.max_seatsclient_limit_reached- Adding another Client would exceed plan.max_client_profilesfeature_not_in_plan- The tier does not include this whole feature surfaceexercise_not_in_plan- The (activity, exercise) is not in the team’s exercise grantstrial_expired- The team is read-only: its self-serve trial endedaccess_ended- The team is read-only: its paid plan or granted access ended
ISO-8601 UTC timestamp the team’s current period ends. Null when the team has no live subscription (legacy un-migrated row). On Free + paid this is the renewal moment; quota refreshes to exactly plan.session_quota (NOT additive — leftover sessions don’t roll over).
The active plan’s role string (free, starter, professional, organization, strategic). Same value as current_role — kept as two separate fields for forward-compatibility with a future named-plan split where current_plan could carry an SKU and current_role the tier label.
The active plan’s role string. See current_plan.
Which feature surface is locked. Present ONLY on feature_not_in_plan, so one modal can name what’s gated without a detail string per feature (#773). The only value today is agents (aikynetix/agents/services.py::AGENTS_FEATURE).
Example
{ "detail": "quota_exhausted"}object
Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).
Examples
403 — staff
{ "detail": "not_a_team_member"}403 — a client's own account
{ "detail": "client_account"}object
Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).
Examples
404 — not a card of the team
{ "detail": "client_not_found"}object
409 — the request conflicts with current state. detail is a stable code (e.g. reanalyze_in_flight, already_on_plan, email_in_use). Some 409s carry extra context fields alongside detail; those are documented on the specific endpoint that emits them.
Examples
409 — nobody to talk to
{ "detail": "no_client_access"}object
429 — throttled: this account’s (or address’s) rate for the route is used up; try again after wait seconds, which Retry-After repeats. A route with a limit of its own answers its own code instead, documented there.
With throttled: whole seconds until the next request can pass.
Example generated
{ "detail": "example", "wait": 1}