Generate a structured plan

POST

/api/agents/plans/

const url = 'http://localhost:8000/api/agents/plans/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"agent":"rehab","subject":{"kind":"client","id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:8000/api/agents/plans/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "agent": "rehab", "subject": { "kind": "client", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }'

Generate — or regenerate — the structured plan for one (agent, subject).

Returns 201 with the plan: ordered steps, each carrying a title, a rationale citing one of the subject’s measurements, and a prescription (the concrete thing the coach runs), plus the plan’s own title, summary and recheck_metric.

Not a stream: the caller needs a validated step list, so this is a single JSON-mode completion. Generated from the subject’s measurements, NOT from the conversation, so the same subject yields a comparable plan regardless of what was discussed.

Regenerating replaces the machine-written steps and keeps the ones the coach edited (step.edited), so correcting a step is never silently undone. One plan per (conversation, subject, lang) — regardless of persona, so regenerating after switching persona updates the same plan (and re-attributes it to whoever wrote it) rather than piling up versions.

With no model configured, a deterministic plan is built from the subject’s out-of-range measurements (mode: "stub"), so the shape is identical and nothing is invented.

Authorizations

Parameters

Query Parameters

lang

string

Plan language (en / ru / es). Defaults to en.

Request Body^required

Body of POST /api/agents/plans/ — which agent, about which subject, in which conversation.

The STEPS still come from the subject’s measurements rather than the chat, so the same subject yields a comparable plan — but the plan is filed against the conversation, so a new thread starts with an empty panel instead of the last thread’s plan.

object

agent

required

string

>= 1 characters <= 32 characters

subject

required

What the conversation is scoped to: the caller’s whole team, or one athlete on it. id is the Client id and is required only for kind="client" — a team subject is always the caller’s active team, never an id from the body (that would be a tenancy hole).

object

kind

required

team - team
client - client

string

Allowed values: team client

string format: uuid

nullable

thread_id

string format: uuid

nullable

Examples

PlanForOneAthlete

Plan for one athlete

{
  "agent": "rehab",
  "subject": {
    "kind": "client",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Body of POST /api/agents/plans/ — which agent, about which subject, in which conversation.

object

agent

required

string

>= 1 characters <= 32 characters

subject

required

object

kind

required

team - team
client - client

string

Allowed values: team client

string format: uuid

nullable

thread_id

string format: uuid

nullable

Body of POST /api/agents/plans/ — which agent, about which subject, in which conversation.

object

agent

required

string

>= 1 characters <= 32 characters

subject

required

object

kind

required

team - team
client - client

string

Allowed values: team client

string format: uuid

nullable

thread_id

string format: uuid

nullable

Responses

201

application/json

Read shape of a plan — the ordered steps plus the framing the agent produced. is_edited tells the UI a regenerate would preserve coach work.

object

required

string format: uuid

agent

required

string

<= 32 characters

thread

required

string format: uuid

nullable

subject_kind

required

string

Allowed values: team client

subject_id

required

string format: uuid

lang

string

default: en <= 5 characters

title

required

string

<= 200 characters

summary

string

recheck_metric

string

<= 160 characters

mode

string

<= 8 characters

citations

required

Array<string>

is_edited

required

boolean

steps

required

Array<object>

One step. edited is read-only — the service sets it from a text change (ticking done deliberately does not count as authorship).

object

required

string format: uuid

order

required

integer

title

required

string

<= 200 characters

rationale

string

prescription

string

done

boolean

edited

required

boolean

generated_at

string format: date-time

updated_at

required

string format: date-time

Example

{
  "subject_kind": "team",
  "lang": "en"
}

400

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

401

application/json

object

detail

required

string

Example^generated

{
  "detail": "example"
}

402

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

application/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

402—AgentsNotInPlan

Free team opens an agent conversation

{
  "detail": "feature_not_in_plan",
  "reset_at": null,
  "current_plan": "free",
  "current_role": "free",
  "feature": "agents"
}

403

application/json

object

detail

required

string

Example^generated

{
  "detail": "example"
}

404

application/json

object

detail

required

string

Example^generated

{
  "detail": "example"
}

429

application/json

object

detail

required

429 — rate limit exceeded. Honour the Retry-After response header (seconds to wait) before retrying; it is sent on every 429.

string

Example^generated

{
  "detail": "example"
}

Generate a structured plan

Authorizations

Parameters

Query Parameters

Request Bodyrequired

Examples

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

402

Examples

403

Examplegenerated

404

Examplegenerated

429

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated