COcounselhealth
/v1/end-user-jwt

Create a new thread for a user

Creates a new thread for the specified user and returns the full thread object (same shape as GET by id). The thread_id field is included for backwards compatibility and can be passed to the signedAppUrl endpoint via the open_thread action.

Responds 201 when a thread was created and 200 when an existing unused thread was returned instead, so a repeated call does not accumulate empty threads. Reuse is enabled per organization and never happens when initial_messages are supplied.

post/v1/user/threads/

Request

  • Base URL
    https://api.counselhealth.com (the document declares no server; this is the origin it was published from)
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring
Example:550e8400-e29b-41d4-a716-446655440000

Optional idempotency key. Repeat requests with the same key and body return the original result.

Request body

modulestring
agent_contextobject
metadataobject

Custom key-value metadata for threads. Max 25 keys, each value ≤ 1800 characters. Keys must be alphanumeric with underscores/hyphens only.

Example request

{
  "module": "get_care",
  "initial_messages": [
    {
      "body": "Hello, how are you?",
      "role": "patient"
    }
  ],
  "metadata": {
    "external_session_id": "abc123",
    "plan": "pro",
    "linked_thread_title": "Lightheadedness when standing"
  }
}

Response

No thread was created — an existing unused thread matching this request (same module, smart pill, metadata and agent_context, with no messages from the user) was returned instead. Enabled per organization; requests that seed initial_messages always create.

idstring uuid required
patient_idstring uuid required
mode'AI' | 'PHYSICIAN' required
display_namestring nullable required
module'get_advice' | 'order_lab' | 'refill_medication' | 'review_my_results' | 'get_care' | 'lifestyle_conditions' | 'get_care_quickly' | 'symptom_radar' | 'review_lab_results' | 'bp_signals' | 'cycle_insights' | 'cycle_insights_ttc' | 'optimize_lifestyle' | 'get_treatment' nullable required

The chat module the thread is in. Nullable as chats started with a set of messages may have no module. May change over the life of the thread; a change emits thread.updated.

status'unclaimed' | 'assigned' | 'active' | 'closed' required
created_atstring date-time required
last_activity_timestring date-time required
expires_atstring date-time nullable required
updated_atstring date-time required
terminated_atstring date-time nullable required
termination_reason'emergency' | 'malicious_action' nullable required
sla_start_atstring date-time nullable
metadataobject nullable

Custom key-value metadata for threads. Max 25 keys, each value ≤ 1800 characters. Keys must be alphanumeric with underscores/hyphens only.

thread_idstring uuid

Example response

{
  "module": "get_care",
  "metadata": {
    "external_session_id": "abc123",
    "plan": "pro",
    "linked_thread_title": "Lightheadedness when standing"
  },
  "thread_id": "550e8400-e29b-41d4-a716-446655440000"
}

Changes

No recorded changes to this operation across all 1 revision of this API.