Skip to content
AiKYNETIX

Create or resume a Kai thread

POST
/api/support/threads/
curl --request POST \
  --url http://localhost:8000/api/support/threads/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "product", "title": "", "subject_ref": { "kind": "session", "subject_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "additionalProperty": "example" }, "label": "" }, "attachment_refs": [ { "kind": "session_metrics", "subject_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "additionalProperty": "example" } } ] }'

Named, server-persisted Kai conversations, personal to the calling coach (never visible to teammates). A thread can be scoped to a subject — a session, one metric of a session, a video moment — and creating with the same subject_ref again RESUMES the existing thread (created: false) instead of duplicating it.

attachment_refs are typed references only: the server verifies the subject belongs to your team and builds an immutable data snapshot from the database — request bodies have no field for raw context content by design.

Feature-flagged: while support threads are disabled on the environment every route responds 404.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
lang
string

UI language (en / ru / es, default en) — localises attachment snapshot labels on create and retrieval + answers on message send.

Request Body

Section titled “Request Body”

Body of POST /api/support/threads/.

object
kind
string
Allowed values: product performance
title
string
"" <= 120 characters
subject_ref
object
kind
required
  • session - session
  • metric - metric
  • session_moment - session_moment
  • solution_run - solution_run
  • dashboard_insight - dashboard_insight
  • sessions_recent - sessions_recent
  • team_overview - team_overview
  • client_overview - client_overview
  • page - page
string
Allowed values: session metric session_moment solution_run dashboard_insight sessions_recent team_overview client_overview page
subject_id
string format: uuid
nullable
params
object
key
additional properties
label
string
"" <= 120 characters
attachment_refs
Array<object>

A typed context REFERENCE — never content. The server verifies team ownership and builds the snapshot from Postgres (Decision C), so this body has no field a client could smuggle numbers through.

object
kind
required
  • session_metrics - session_metrics
  • metric - metric
  • session_moment - session_moment
  • sessions_recent - sessions_recent
  • team_overview - team_overview
  • client_overview - client_overview
  • solution_run - solution_run
  • dashboard_insight - dashboard_insight
string
Allowed values: session_metrics metric session_moment sessions_recent team_overview client_overview solution_run dashboard_insight
subject_id
string format: uuid
nullable
params
object
key
additional properties

Responses

Section titled “Responses”

200

Section titled “200”

Existing thread resumed for this subject_ref (created: false).

Media typeapplication/json

POST /api/support/threads/ response — the thread plus the resume-or-create verdict (created: false = an existing subject thread was resumed).

object
id
required
string format: uuid
title
required
string
<= 120 characters
kind
  • product - Platform help
  • performance - Performance
string
Allowed values: product performance
subject_kind
string
<= 32 characters
subject_id
string format: uuid
nullable
subject_params
required

The identity-bearing params, view-only ones stripped.

A thread’s subject is not always its subject_id: a dashboard is keyed by its activity and a page thread by its route, and neither has an id. Without this the client cannot tell two id-less threads apart — every page thread was {subject_kind: "page", subject_id: null} on the wire, so the drawer could not re-open the right one when the coach came back to a tab (#945).

Stripped server-side (threads.identity_params) so the rule for what counts as identity lives in ONE place: a client comparing raw params would fork on units and never match.

object
key
additional properties
created_at
required
string format: date-time
updated_at
required
string format: date-time
attachments
required
Array<object>

Context chip on a thread — label + kind. The snapshot content stays server-side (it is prompt material, not display material); user file attachments additionally expose a short-lived download URL + media type so the FE can render an image thumb.

object
id
required
string format: uuid
kind
required
string
<= 32 characters
label
required
string
<= 120 characters
subject_id
string format: uuid
nullable
captured_at
string format: date-time
url
required
string
nullable
media_type
required
string
nullable
created
required
boolean
Example
{
  "kind": "product"
}

201

Section titled “201”

New thread created (created: true).

Media typeapplication/json

POST /api/support/threads/ response — the thread plus the resume-or-create verdict (created: false = an existing subject thread was resumed).

object
id
required
string format: uuid
title
required
string
<= 120 characters
kind
  • product - Platform help
  • performance - Performance
string
Allowed values: product performance
subject_kind
string
<= 32 characters
subject_id
string format: uuid
nullable
subject_params
required

The identity-bearing params, view-only ones stripped.

A thread’s subject is not always its subject_id: a dashboard is keyed by its activity and a page thread by its route, and neither has an id. Without this the client cannot tell two id-less threads apart — every page thread was {subject_kind: "page", subject_id: null} on the wire, so the drawer could not re-open the right one when the coach came back to a tab (#945).

Stripped server-side (threads.identity_params) so the rule for what counts as identity lives in ONE place: a client comparing raw params would fork on units and never match.

object
key
additional properties
created_at
required
string format: date-time
updated_at
required
string format: date-time
attachments
required
Array<object>

Context chip on a thread — label + kind. The snapshot content stays server-side (it is prompt material, not display material); user file attachments additionally expose a short-lived download URL + media type so the FE can render an image thumb.

object
id
required
string format: uuid
kind
required
string
<= 32 characters
label
required
string
<= 120 characters
subject_id
string format: uuid
nullable
captured_at
string format: date-time
url
required
string
nullable
media_type
required
string
nullable
created
required
boolean
Example
{
  "kind": "product"
}

400

Section titled “400”
Media typeapplication/json
object
detail
required

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).

string
Examplegenerated
{
  "detail": "example"
}

401

Section titled “401”
Media typeapplication/json
object
detail
required

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).

string
Examplegenerated
{
  "detail": "example"
}

404

Section titled “404”
Media typeapplication/json
object
detail
required

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).

string
Examplegenerated
{
  "detail": "example"
}

429

Section titled “429”
Media typeapplication/json
object
detail
required

429 — rate limit exceeded. Honour the Retry-After response header (seconds to wait) before retrying; it is sent on every 429.

string
Examplegenerated
{
  "detail": "example"
}