Skip to content
AiKYNETIX

List every conversation, across agents and subjects

GET
/api/agents/conversations/
curl --request GET \
  --url http://localhost:8000/api/agents/conversations/ \
  --header 'Authorization: Bearer <token>'

EVERY conversation the caller has, across every agent and every subject — what the sidebar lists.

GET /agents/threads/ cannot answer this: it requires an agent and a subject_kind (a thread’s identity includes both), so a coach switching athlete watched the history apparently empty itself. Same per-coach scoping as that endpoint, for the same reason — a conversation is personal working notes, so this never surfaces a colleague’s.

Newest first and BOUNDED: this is a way back to recent work, not an archive browser. Rows carry agent + subject_kind + subject_id so the client can group them and resolve the athlete’s name from its own roster; they omit messages, like every list row here.

Authorizations

Section titled “Authorizations”

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

Nothing yet

[
  {
    "conversations": []
  }
]

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