Skip to main content
POST
Message my coach

Authorizations

Authorization
string
header
default:Bearer sandbox_any_token_works
required

A 15-minute token bound to one patient and one enrollment, issued by POST /v1/oauth/token with the token-exchange grant. Treat it as opaque. When it expires, exchange a fresh assertion; there is no refresh token.

Headers

Idempotency-Key
string
required

A unique key per logical request, for example a UUID. Retrying with the same key and the same body within 24 hours returns the first response (with Idempotent-Replayed: true) instead of creating a duplicate. The same key with a different body is refused with 422 idempotency_key_reused.

Required string length: 8 - 255

Path Parameters

conversation_id
string<uuid>
required

Body

application/json

Text, a photo, or both.

body
string
required
Required string length: 1 - 4000
Example:

"Nausea is better today. Can I swap dinner?"

photo_upload_id
string<uuid>

From POST /v1/patient/message-photos, after the photo was uploaded. One photo per message.

Example:

"9f3d5b71-2a4c-4e6f-8b0d-1c3e5a7b9d2f"

Response

Sent.

id
string<uuid>
required
Example:

"0190f5c4-2e3f-7a41-9b56-7c8d9e0f1a23"

conversation_id
string<uuid>
required
Example:

"0190f5c4-1d2e-7f30-8a45-6b7c8d9e0f12"

sender
object
required
body
string
required

Empty when the message was deleted.

Example:

"Great job on your protein yesterday. How is the nausea today?"

created_at
string<date-time>
required

ISO 8601 in UTC.

Example:

"2026-10-26T14:05:00Z"

deleted
boolean
required
Example:

false

reactions
object[]
required
edited_at
string<date-time> | null
Example:

null

seen_by_other_side
boolean

True when the other side has read up to this message.

Example:

true

attachment
object | null

A protocol card, a notice in the thread, or a photo the patient sent their coach.

feedback
object | null

The patient's rating, on the AI Coach's messages only.