Skip to content
AiKYNETIX

List the stored conversations

GET
/api/agents/threads/
curl --request GET \
  --url 'http://localhost:8000/api/agents/threads/?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
string

Persona key from GET /api/agents/. Accepted and ignored here — a conversation is not keyed by persona, so this cannot narrow the result.

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”

200

Section titled “200”
Media typeapplication/json
Array<object>

One row of the history list.

Deliberately WITHOUT messages: a coach with fifty conversations would otherwise pull every turn of every one to render a sidebar. preview is the opening question, which is enough to recognise a thread whose title was auto-derived from that same question.

agent is “who you last talked to here” — the persona of the most recent answer. A client may draw a row’s icon from it; it must NOT bucket the list by it. Doing that is what made switching persona look like the history emptying itself.

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
message_count
required
integer
preview
required
string
"" nullable
updated_at
required
string format: date-time
Examples

No conversations yet

[
  {
    "threads": []
  }
]

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