Skip to content
AiKYNETIX

Read one conversation

GET
/api/agents/threads/{id}/
curl --request GET \
  --url http://localhost:8000/api/agents/threads/example/ \
  --header 'Authorization: Bearer <token>'

One stored conversation, resolved admin-scoped: a thread id belonging to another coach returns 404, not 403 — a 403 would confirm the conversation exists.

Each turn carries the agent that produced it — blank on the coach’s own turns, since a question has no persona. A conversation may mix them.

PATCH renames it (a blank title hands naming back to the auto-titler); DELETE removes the conversation and its turns.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Responses

Section titled “Responses”

200

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

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