List the conversational coaching agents

GET

/api/agents/

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

• Local development
• Production

The conversational coaching agents available to the caller’s team, plus whether the team may use them.

available is false when the surface is disabled for this deployment (reason: "disabled"), the caller has no active team (reason: "no_team"), or the team’s plan does not include agents (reason: "plan"). The roster is listed either way, so an ineligible team can see what it would unlock.

Entries carry the persona key only — the localised name, description and example questions live in the frontend agents locale bundle.

Authorizations

• ApiKeyBearer
• localJwtAuth
• FirebaseBearer
• FirebaseSessionCookie

Responses

200

Media typeapplication/json

Body of GET /api/agents/.

available is false when the surface is disabled for this deployment or the team’s plan doesn’t include it; reason says which, so the page can render the right empty state (disabled / no_team / plan). The roster itself is always listed, so an ineligible team still sees what it would unlock.

object

available

required

boolean

reason

required

string

nullable

agents

required

Array<object>

One roster entry. Key only — the localised name / description / example questions live in the frontend agents i18n namespace (I18N.md).

object

key

required

string

intake

required

Whether this conversation takes video, and for which movements.

available false → the composer offers no clip AND /api/agents/intake/* 404s AND start_analysis is absent from the model’s tool schema. Three gates, one flag: hiding the button is not a gate, it is a decoration.

object

available

required

boolean

exercises

required

Array<object>

One movement the conversation may be handed a clip for (#1689).

object

activity

required

string

exercise

required

string

camera_view

required

• side - Side
• front - Front
• back - Back

string

Allowed values: side front back

Examples

{
  "available": true,
  "reason": null,
  "agents": [
    {
      "key": "rehab"
    },
    {
      "key": "performance"
    }
  ],
  "intake": {
    "available": true,
    "exercises": [
      {
        "activity": "running",
        "exercise": "Treadmill",
        "camera_view": "side"
      }
    ]
  }
}

Not included in the team's plan

{
  "available": false,
  "reason": "plan",
  "agents": [
    {
      "key": "rehab"
    },
    {
      "key": "performance"
    }
  ],
  "intake": {
    "available": false,
    "exercises": []
  }
}

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

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