Rename a conversation
const url = 'http://localhost:8000/api/agents/threads/example/';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"title":"Return to play — Marco"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url http://localhost:8000/api/agents/threads/example/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "title": "Return to play — Marco" }'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”Request Body
Section titled “Request Body”Body of PATCH /api/agents/threads/<id>/.
Blank is allowed and means “unname it” — that hands the title back to the auto-titler rather than pinning an empty string.
object
Examples
{ "title": "Return to play — Marco"}Body of PATCH /api/agents/threads/<id>/.
Blank is allowed and means “unname it” — that hands the title back to the auto-titler rather than pinning an empty string.
object
Examplegenerated
title=exampleBody of PATCH /api/agents/threads/<id>/.
Blank is allowed and means “unname it” — that hands the title back to the auto-titler rather than pinning an empty string.
object
Responses
Section titled “Responses”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
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
Example
{ "subject_kind": "team"}object
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).
Examplegenerated
{ "detail": "example"}object
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).
Examplegenerated
{ "detail": "example"}The caller’s tier does not include the coaching agents.
object
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 0subscription_suspended- Stripe dunning in flight (past_due / unpaid)seat_limit_reached- Adding another team member would exceed plan.max_seatsclient_limit_reached- Adding another Client would exceed plan.max_client_profilesfeature_not_in_plan- The tier does not include this whole feature surface
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).
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.
The active plan’s role string. See current_plan.
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).
Examples
Free team opens an agent conversation
{ "detail": "feature_not_in_plan", "reset_at": null, "current_plan": "free", "current_role": "free", "feature": "agents"}object
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).
Examplegenerated
{ "detail": "example"}object
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).
Examplegenerated
{ "detail": "example"}