Skip to content
AiKYNETIX

Start a new conversation

POST
/api/agents/threads/
curl --request POST \
  --url 'http://localhost:8000/api/agents/threads/?agent=example&subject_kind=client' \
  --header 'Authorization: Bearer <token>'

The caller’s stored conversations about one athlete or squad.

Threads are per coach, not per team: two coaches on one team hold separate conversations about the same athlete, because a conversation is personal working notes rather than a shared document. Not keyed by language — switching UI language continues the same thread — and not keyed by agent either, for the same reason: switching persona answers the next question in the conversation you are already in. agent is therefore REQUIRED on POST (it stamps the new conversation’s starting persona) and ignored on GET; the value on a row is the persona of its most recent ANSWER, so render it as a mark and never filter by it.

There can be MANY per subject: a return-to-play discussion and a weekly-load discussion about the same athlete are different documents. POST starts an empty one (the coach’s “new conversation”), which is additive — it never discards an existing thread, and it folds a still-empty one rather than stacking duplicates.

title is auto-derived from the opening question when the coach has not set one. List rows omit messages; read one thread to get its turns.

Threads untouched for the retention window are deleted server-side by the prune_agent_threads sweep.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
agent
required
string

Persona key from GET /api/agents/ (e.g. rehab).

lang
string

Reply language (en / ru / es). Defaults to en.

subject_id
string

Client id — required when subject_kind=client, ignored for team (a team subject always resolves to the caller’s active team).

subject_kind
required
string
Allowed values: client team

team or client.

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json

One stored conversation, with its turns — the read-a-thread shape.

agent here is the persona of the most recent ANSWER, not the conversation’s identity: render it as an icon, never use it as a filter key. Per-turn attribution lives on each message.

object
id
required
string format: uuid
agent
required
string
subject_kind
required
string
Allowed values: team client
subject_id
required
string format: uuid
title
required
string
messages
required
Array<object>

One stored turn. citations replays the grounding provenance so a reopened conversation keeps its “Based on: …” footnotes (#759).

agent is the persona that PRODUCED this turn, and it is blank on the coach’s own turns — a question has no persona. A conversation can mix them (switching persona answers the next question in the same thread), so this is what a client reads to attribute an answer; the thread-level agent is only the most recent one.

object
id
required
string format: uuid
role
required
string
content
required
string
citations
required
Array<string>
lang
required
string
agent
required
string
partial
required
boolean
tools
required
visuals
required
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "subject_kind": "team"
}

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"
}

402

Section titled “402”

The caller’s tier does not include the coaching agents.

Media typeapplication/json
object
detail
required

One of five 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.

  • quota_exhausted - Session quota for the period reached 0
  • subscription_suspended - Stripe dunning in flight (past_due / unpaid)
  • seat_limit_reached - Adding another team member would exceed plan.max_seats
  • client_limit_reached - Adding another Client would exceed plan.max_client_profiles
  • feature_not_in_plan - The tier does not include this whole feature surface
string
Allowed values: quota_exhausted subscription_suspended seat_limit_reached client_limit_reached feature_not_in_plan
reset_at
required

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

string format: date-time
nullable
current_plan
required

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.

string
current_role
required

The active plan’s role string. See current_plan.

string
feature

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

string
Examples
Example402—AgentsNotInPlan

Free team opens an agent conversation

{
  "detail": "feature_not_in_plan",
  "reset_at": null,
  "current_plan": "free",
  "current_role": "free",
  "feature": "agents"
}

403

Section titled “403”
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"
}