Agent API

Auto-generated from the OpenAPI spec. Run node docs-site/scripts/fetch-openapi.js to regenerate.

POST /api/v1/agent/act

Agent Act

Request body

Field	Required	Type	Description
messages	Yes	array
draft	No	object
language	No	string

Manager only. The AI Assistant in Action Mode. Runs on the studio's own AI configuration (see Studio → AI Assistant configuration); without one it answers in basic mode.

Responses

• 200 — Successful Response

  {
    "reply": "I couldn't find a documentation page for that. Try different words, or pick a topic below:",
    "action": null,
    "draft": null,
    "usage": null,
    "mode": "basic",
    "docs_results": [],
    "suggested_topics": [
      {
        "id": "studio",
        "label": "Studio",
        "doc_path": null,
        "anchor": null,
        "children": [
          {
            "id": "studio.scheduling",
            "label": "Scheduling",
            "doc_path": null,
            "anchor": null,
            "children": [
              {
                "id": "studio.scheduling.classes",
                "label": "Classes",
                "doc_path": null,
                "anchor": null,
                "children": [
                  {
                    "id": "studio.scheduling.classes.creating-a-class-type",
                    "label": "Creating a class type",
                    "doc_path": "studio-manager/classes.md",
                    "anchor": "creating-a-class-type",
                    "children": null
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "id": "gdpr",
        "label": "GDPR & privacy",
        "doc_path": "gdpr/studio-manager-guide.md",
        "anchor": null,
        "children": null
      },
      {
        "id": "migration",
        "label": "Migration",
        "doc_path": null,
        "anchor": null,
        "children": [ "…two page nodes, migration.overview and migration.column-mapping" ]
      }
    ]
  }

  Field	Type	Description
  reply	string	The assistant's answer. In basic mode, a fixed localized message.
  action	object | null	The action performed, when one was.
  draft	object | null	Fields collected so far for an in-progress action; send it back on the next turn.
  usage	object | null	Token usage of the LLM call (AI mode only).
  mode	"ai" | "basic"	ai — an LLM answered. basic — no AI is configured: reply is fixed and docs_results holds the documentation search hits.
  docs_results	array | null	Basic mode only (possibly empty): up to 3 {title, excerpt, doc_path} keyword-search hits, where doc_path is the docs page path relative to the docs root. null in AI mode.
  suggested_topics	SuggestedTopicNode[] | null	Basic mode only, and only for the two dead ends where docs_results gives nothing to go on — a greeting, or a zero-result search (null whenever docs_results already has a hit, and always null in AI mode). The curated drill-down topics menu — see SuggestedTopicNode shape below.

  Basic mode makes no LLM call, no embedding call and no network call.

• 409 AI_NOT_CONFIGURED — The request carries a draft (the continuation of an in-progress action) but no AI is configured, so the action can't be completed. Add a provider key in Settings → AI Assistant.

• 429 AI_RATE_LIMITED — The studio's AI provider is rate-limiting requests. details.docs_url links to How to set up the AI Assistant → If you expect heavy use.

• 422 — Validation Error

The custom error codes and response fields above aren't captured by fetch-openapi.js's regeneration — added by hand from app/routers/agent.py. Keep them if this page is regenerated.

---

GET /api/v1/agent/suggested-topics

Get Suggested Topics

The full curated basic-mode drill-down topics tree (see _build_suggested_topics_tree), localized to language. Lets the frontend render the empty-state menu before any message is sent, instead of only after a greeting or a zero-result search inside POST /act. Same default-language convention as the rest of this router: an unrecognized language silently falls back to "en" rather than 422ing.

Parameters

Name	In	Required	Type	Description
language	query	No	string	One of en, it, fr, de, es, pt, nl. Defaults to en; an unrecognized value also falls back to en rather than 422ing — same convention as POST /act's language field.

Responses

• 200 — Successful Response

  {
    "topics": [
      { "id": "studio", "label": "Studio", "doc_path": null, "anchor": null, "children": ["…"] },
      {
        "id": "gdpr",
        "label": "GDPR & privacy",
        "doc_path": "gdpr/studio-manager-guide.md",
        "anchor": null,
        "children": null
      },
      { "id": "migration", "label": "Migration", "doc_path": null, "anchor": null, "children": ["…"] }
    ]
  }

  Field	Type	Description
  topics	SuggestedTopicNode[]	See SuggestedTopicNode shape below.

• 422 — Validation Error

Not captured by fetch-openapi.js's regeneration (no language description, no response shape) — added by hand from app/routers/agent.py. Keep it if this page is regenerated.

---

SuggestedTopicNode shape

Both POST /act's suggested_topics field and GET /suggested-topics's topics field return the same recursive tree. It mirrors the real docs sidebar, kept to the 3 macro-categories useful to an in-app manager assistant — studio (relabeled from "For Studio Managers"), gdpr, and migration. "Getting Started" (onboarding, already done), "For Clients" (client-facing), "API Reference" (developer docs) and "Legal" (ToS text) are intentionally excluded.

Field	Type	Description
id	string	Stable, unique, dot-joined path of slugs, e.g. studio.scheduling.classes.creating-a-class-type.
label	string	Localized display label. A section leaf's label is the English markdown heading text, untranslated — docsUrlForPath on the frontend always opens the English-default-locale doc regardless of the chat's language, so a translated label here wouldn't match where the link lands.
doc_path	string | null	Docs-site page path relative to the docs root, e.g. studio-manager/classes.md. Set only on a leaf.
anchor	string | null	Heading slug within doc_path, e.g. creating-a-class-type. Set only on a section leaf (a page with 2+ top-level ("##") sections, excluding the boilerplate "Related pages" section most pages end with).
children	SuggestedTopicNode[] | null	The next level of chips. Set only on a non-leaf.

Exactly one of doc_path or children is ever populated on a given node — never both, never neither. The tree has up to 4 levels: category → [subcategory] → page → [section]. A level is skipped wherever it would add a chip layer with only one item in it:

• A page with 0 or 1 sections is a leaf itself (no anchor, no section-chip layer forced for a single section).
• gdpr has exactly one page and no subcategories, so its category node collapses straight to that page's doc/sections instead of showing a pointless 1-item "page" layer.
• migration has two pages and no subcategories — 2 items is still worth a layer, so its category node keeps children (one per page) rather than collapsing.

studio groups its 31 pages into 8 subcategories: scheduling, clients, payments, staff, marketing, reports, ai-assistant, settings.

Hand-written — fetch-openapi.js has no concept of a recursive response-body schema. Keep this section if this page is regenerated.

---