Skip to content
AiKYNETIX

Delete a conversation

DELETE
/api/agents/threads/{id}/
curl --request DELETE \
  --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.

panel is the agents panel this conversation keeps (#2369): {tabs, active}, where tabs are hrefs of screens the panel hosts and active is plan, new (the + tab) or a tab’s index.

PATCH renames it (a blank title hands naming back to the auto-titler), stores its panel tabs, or both. Tabs are cleaned rather than refused: at most 12, deduped, hosted paths of this site only, a session tab without its ?t= moment; an active that no longer points at a kept tab falls back to plan. Storing tabs does not move the conversation in the history list. 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”

204

Section titled “204”

Conversation deleted.

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

Example generated

{
  "detail": "example"
}

402

Section titled “402”

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

Media typeapplication/json
object
detail
required

One of eight 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; exercise_not_in_plan leads to a contact-us CTA — the movement list is sales-managed, no tier adds to it (#2030). trial_expired / access_ended mean the team is read-only (#2901): everything opens, nothing new is created; they lead to a subscribe CTA and always carry reset_at: null.

  • 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
  • exercise_not_in_plan - The (activity, exercise) is not in the team’s exercise grants
  • trial_expired - The team is read-only: its self-serve trial ended
  • access_ended - The team is read-only: its paid plan or granted access ended
string
Allowed values: quota_exhausted subscription_suspended seat_limit_reached client_limit_reached feature_not_in_plan exercise_not_in_plan trial_expired access_ended
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

Example generated

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

Example generated

{
  "detail": "example"
}