Bridge REST API Reference

The Familiars backend is a single-process FastAPI bridge, listening on 127.0.0.1:18711 (HTTPS + HTTP/2) by default. 60+ route files, 500+ endpoints. This document is organized by route file; each endpoint lists its HTTP method, path, description, request body, and response body.

Source: src/bridge/routes/ + src/api/v1/endpoints/communication.py.

---

0. Transport & Authentication

Transport

• Default: HTTPS + HTTP/2 (hypercorn + self-signed cert workspace/.bridge.crt)
• Fallback: FAMILIARS_HTTP_INSECURE=1 → plain HTTP + uvicorn
• Port: 18711 by default. If occupied, Electron automatically picks a free port and writes it to workspace/.bridge.port

Authentication

• All endpoints except /health, /api/auth/*, /api/broker_app/*, /api/demo/*, /api/chat/* require the X-Bridge-Token header
• The token is also accepted via the ?token=... query parameter (for SSE / WebSocket / <img src> scenarios)
• BridgeTokenMiddleware validates globally

SSE

• Chat streams, status streams, reminder streams, and asset job streams return text/event-stream
• HTTP/2 multiplexing avoids Chromium's 6-socket-per-host HTTP/1.1 limit

curl Examples

# 获取 token
TOKEN=$(cat workspace/.bridge_token)

# 列出 agent
curl -k -H "X-Bridge-Token: $TOKEN" https://127.0.0.1:18711/api/agents

# SSE 流式对话
curl -k -N -H "X-Bridge-Token: $TOKEN" \
  "https://127.0.0.1:18711/api/chat/stream?prompt=你好&agent_id=1"

# 创建待办
curl -k -X POST -H "X-Bridge-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"买牛奶","deadline":"2026-07-05T18:00"}' \
  https://127.0.0.1:18711/api/todos

---

1. chat.py — Chat

Prefix: /api

Method	Path	Description	Request	Response
GET	/chat/inflight	Get currently in-flight streams	-	{slots: [{agent_id, dialogue_id, fingerprint}]}
POST	/chat/send	Send a message, synchronously get the full reply	{prompt, dialogue_id?, parent_id?, type?, agent_id?}	{type, content, node_id, metadata}
GET	/chat/stream	SSE streaming reply	query: prompt, dialogue_id, parent_id, agent_id, type, model, regen_q, resume_a, call_mode	SSE: progress / result / error events
GET	/chat/recipe_dialogue_id	Look up recipe dialogue mapping	query: recipe_id	{dialogue_id}
POST	/translate	Translate text (preserving code/URLs)	{text, target?}	{translated}
GET	/models	List models available in the @-picker	-	[{id, name, ...}]
GET	/chat/generate/stream	Legacy generation SSE (Generation.generate)	query: prompt, agent_id	SSE stream

---

2. agents.py — Agent Lifecycle

Prefix: /api

Method	Path	Description	Request	Response
GET	/agents	List all agents (including the manager)	-	[{id, name, color, avatar_url, portrait_url, ...}]
GET	/agents/{agent_id}/dialogue_tree	Get an agent's dialogue tree	-	Tree-structure JSON
POST	/agents	Register an existing agent id	query: agent_id	{ok, agent_id}
POST	/agents/temporary	Create a temporary agent	JSON body	{agent_id}
GET	/agents/create/stream	Agent creation wizard SSE	query: name, identity, personality, appearance, voice, need_figure, need_audio, ...	SSE progress events
DELETE	/agents/{agent_id}	Delete an agent	-	{ok}
POST	/agents/{agent_id}/release-memory	Release agent memory	-	{ok}
GET	/agents/{agent_id}/greeting	Download the greeting video	-	Video file
POST	/agents/{agent_id}/greeting/played	Mark greeting as played	-	{ok}
GET	/agents/{agent_id}/pending_cg	Pending CG	-	CG status
GET	/agents/diagnose-dirs	Diagnose orphan/duplicate agent directories	-	{orphan_dirs, duplicates}
GET	/agents/{agent_id}/avatar	Get avatar	-	PNG image
GET	/agents/{agent_id}/portrait	Get portrait	-	Image/video
GET	/agents/{agent_id}/client_portraits/{client_name}	Client-customized portrait	-	Image
GET	/agents/{agent_id}/figure_rgba	Full-body transparent-background portrait	-	PNG
GET	/agents/{agent_id}/bg	Get background image	-	Image
GET	/agents/{agent_id}/bust_loop	Bust loop animation	-	WebM/WebP
GET	/agents/{agent_id}/bust_meta	Bust animation metadata	-	{duration, fps, ...}
GET	/agents/{agent_id}/theme/{element}	Theme element resource	element: bubble/chat_bg/dock_bg/selected	PNG
GET	/agents/{agent_id}/theme/meta	Theme metadata	-	{text_color_hint, bubble_text_color_hint, ...}
GET	/agents/{agent_id}/skills/{skill_id}/cg	Skill CG asset	-	Image
GET	/manager/entry-image/{key}	Manager entry image	key	Image

---

3. tree.py — Dialogue Tree

Prefix: /api

Method	Path	Description	Request	Response
GET	/tree/{agent_id}/{dialogue_id}	Serialize the whole tree	-	{roots, nodes}
GET	/tree/{agent_id}/{dialogue_id}/query	Semantic node search	query: text, k?	[{node, score}]
GET	/tree/{agent_id}/{dialogue_id}/node/{node_id}	Get a single node	-	{id, title, content, node_type, parent, children, metadata, ...}
GET	/tree/{agent_id}/{dialogue_id}/path/{node_id}	Path from root to node	-	[{id, content, node_type, ...}]
DELETE	/tree/{agent_id}/{dialogue_id}/node/{node_id}	Delete subtree	-	{ok, removed, roots, nodes}
POST	/tree/{agent_id}/{dialogue_id}/move	Move subtree	{node_id, new_parent_id?}	{ok}
PATCH	/tree/{agent_id}/{dialogue_id}/node/{node_id}	Edit node text	{content}	{ok}

---

4. todo.py — Todos

Prefix: /api

Method	Path	Description	Request	Response
GET	/todos	List todos	query: open_only?	[{id, title, content, deadline, completed, ...}]
POST	/todos	Create todo	{title, content?, deadline?, emergency_level?, needs_reminder?, remind_at?, frequency?}	{id, ...}
DELETE	/todos/{todo_id}	Delete todo	-	{ok}
PATCH	/todos/{todo_id}	Update todo	{title?, content?, deadline?, emergency_level?}	{ok}
POST	/todos/{todo_id}/complete	Complete todo	-	{ok}
POST	/todos/{todo_id}/uncomplete	Reopen	-	{ok}

---

5. schedule.py — Schedules

Prefix: /api

Method	Path	Description	Request	Response
GET	/schedules	List schedules	query: agent_id?	[{id, title, scheduled_time, ...}]
POST	/schedules	Create schedule	{title, content?, scheduled_time, emergency_level?, frequency?, kind?, needs_reminder?, remind_at?}	{id, ...}
DELETE	/schedules/{schedule_id}	Delete schedule	-	{ok}
POST	/schedules/{schedule_id}/complete	Complete	-	{ok}
POST	/schedules/{schedule_id}/uncomplete	Reopen	-	{ok}

---

6. cron.py — Cron Jobs

Prefix: /api

Method	Path	Description	Request	Response
GET	/cron-jobs	List cron jobs	query: agent_id?, include_system?	[{name, cron, task, agent_id, ...}]
POST	/cron-jobs	Create cron job	{name, cron, task, agent_id, action?, recurring?}	{name, ...}
PATCH	/cron-jobs/{name}	Update	{name?, cron?, task?, action?, recurring?, agent_id?}	{ok}
DELETE	/cron-jobs/{name}	Delete	-	{ok}
GET	/cron-jobs/{name}/runs	Recent run records	query: limit?	[{ts, status, output}]
POST	/cron-jobs/{name}/run-now	Run now	-	{ok}
GET	/cron-jobs/{name}/diagnostics	Diagnostics	-	Diagnostics JSON
GET	/cron/scripts/preview	Script preview	-	Script list

---

7. reminders.py — Reminders

Prefix: /api

Method	Path	Description	Request	Response
GET	/reminders/recent	Recent reminder events	query: since_ts?, limit?	[{kind, subject_id, ts, ...}]
GET	/reminders/stream	SSE reminder stream	query: start_ts?	SSE event stream
POST	/reminders/{kind}/{subject_id}/snooze	Snooze	{minutes?}	{ok}
POST	/reminders/{kind}/{subject_id}/dismiss	Dismiss	-	{ok}

---

8. settings.py — Settings

Prefix: /api

Method	Path	Description	Request	Response
GET	/settings	Get global settings	-	Settings JSON
PUT	/settings	Update global settings	Partial settings JSON	{ok}
GET	/agents/{agent_id}/settings	Agent settings	-	Settings JSON
PUT	/agents/{agent_id}/settings	Update agent settings	Partial settings JSON	{ok}
GET	/dialogues/{agent_id}/{dialogue_id}/settings	Dialogue settings	-	Settings JSON
PUT	/dialogues/{agent_id}/{dialogue_id}/settings	Update dialogue settings	Partial settings JSON	{ok}
GET	/settings/llm	LLM connection info (key masked)	-	{base_url, api_key: "***", default_model, ...}
GET	/settings/update-config	Update config	-	Config JSON
PUT	/settings/llm	Update LLM connection	{base_url?, api_key?, default_model?, transport_mode?, auto_fallback?}	{ok}
GET	/settings/models	List saved models	-	[{name, url, ...}]
POST	/settings/models	Add model	{name, url, api_key?, ...}	{ok}
DELETE	/settings/models/{name}	Delete model	-	{ok}
POST	/settings/models/{name}/ping	Test model connectivity	-	{ok, latency_ms}

---

9. auth.py — Authentication

Prefix: /api

Method	Path	Description	Request	Response
POST	/auth/register	Register local identity	{nickname?}	{token, ...}
POST	/auth/login	Login (device fingerprint)	-	{token, ...}

---

10. user.py — User Profile

Prefix: /api/user

Method	Path	Description	Request	Response
GET	/profile	Get profile	-	{nickname, ...}
PUT	/profile	Update profile	Partial profile JSON	{ok}
GET	/avatar	Get avatar	-	Image file
POST	/avatar	Upload avatar	multipart: file	{ok, url}
POST	/intro	Merge self-introduction into USER.md	{text}	{ok}

---

11. background.py — Background Mode

Prefix: /api/background

Method	Path	Description	Request	Response
GET	/state	Background state	-	{enabled, autorun_installed}
POST	/enable	Enable background + install autorun	-	{ok}
POST	/disable	Disable background + uninstall autorun	-	{ok}
POST	/quit	Gracefully stop the bridge	-	{ok}

---

12. status.py — Runtime Status

Prefix: /api

Method	Path	Description	Request	Response
GET	/status	Status snapshot	-	{states: {...}}
GET	/status/stream	SSE status delta stream	-	SSE
POST	/status/debug	Manually set a status key	{key, label, detail?, level?, clear?}	{ok}

---

13. usage.py — LLM Usage

Prefix: /api

Method	Path	Description	Request	Response
GET	/usage/summary	Aggregated usage	query: model?	{total_tokens, cost, per_model: {...}}

---

14. memory.py / memory_status.py — Memory

Prefix: /api

Method	Path	Description	Request	Response
GET	/memory	Memory/VRAM observability	-	{rss_gb, vram_gb, dialogues_loaded, ...}
GET	/memory/writer-status	Memory writer diagnostics	query: recent?, agent_id?	{status, records: [...]}

---

15. monitor.py — Message Monitoring

Prefix: /api/monitor

Method	Path	Description	Request	Response
GET	/	List listener statuses	-	[{id, status, ...}]
GET	/settings	Monitor settings	-	Settings JSON
PUT	/settings	Update monitor settings	Settings JSON	{ok}
GET	/file-roots	File root resolution snapshot	-	{wechat: [...], qq: [...]}
POST	/file-roots/refresh	Force re-resolution	{source, allow_ui_probe?}	{ok}
GET	/_diag	Diagnostics snapshot	-	{preflight, vram_residents}
POST	/{monitor_id}/start	Start listener	-	{ok}
POST	/{monitor_id}/stop	Stop listener	-	{ok}

---

16. skills.py — Skills

Prefix: /api

Method	Path	Description	Request	Response
GET	/skills	Global skill list	-	[{id, name, ...}]
GET	/skills/{skill_id}/source	Get SKILL.md source	-	{source}
PUT	/skills/{skill_id}/source	Update SKILL.md	{source}	{ok}
POST	/skills/{skill_id}/validate	Validate SKILL.md	-	{ok, errors?}
PATCH	/skills/{skill_id}/meta	Update skill metadata	{name?, description?, ...}	{ok}
DELETE	/skills/{skill_id}	Delete skill	-	{ok}
POST	/skills/runs/{run_id}/cancel	Cancel run	-	{ok}
POST	/agents/{agent_id}/skills/{skill_id}/unschedule	Unschedule	-	{ok}
GET	/skills/runs/active	Active runs	-	[{run_id, skill_id, ...}]
GET	/skills/runs/{run_id}/stream	SSE run progress	-	SSE
GET	/agents/{agent_id}/skills	Agent-available skills	-	[{id, name, ...}]
GET	/recipes/{recipe_id}/skills	Recipe-linked skills	-	[{id, ...}]
GET	/recipe_skills/all	All recipe skills	-	[{...}]
GET	/skills/{skill_id}/doc	Raw SKILL.md	-	Text
GET	/agents/{agent_id}/knowledge-bases	Agent knowledge bases	-	[{id, name, ...}]
POST	/agents/{agent_id}/knowledge-bases	Create knowledge base	{name, ...}	{id}
POST	/agents/{agent_id}/knowledge-bases/upload	Upload KB file	multipart	{ok}
DELETE	/agents/{agent_id}/knowledge-bases/{kb_id}	Delete knowledge base	-	{ok}
GET	/agents/{agent_id}/skills/{skill_id}/cg_meta	CG metadata	-	{...}
POST	/agents/{agent_id}/skills/{skill_id}/run	Run skill (background)	-	{run_id}
POST	/agents/{agent_id}/skills/{skill_id}/run_in_dialogue	Run in dialogue	{dialogue_id, parent_id?, initial_inputs?}	{run_id}
POST	/skills/import/folder	Import from folder	JSON body	{ok}
POST	/skills/import/zip	Import from zip	multipart	{ok}
POST	/skills/import/text	Import from text	{text, skill_id?}	{ok}

---

17. skill_forge.py — Skill Forge

Prefix: /api/skills/forge

Method	Path	Description	Request	Response
POST	/from-dialogue/derive_io	Derive I/O from dialogue	JSON body	{inputs, outputs}
POST	/from-dialogue/propose	Propose skill from dialogue	JSON body (heavy)	{skill_md, ...}
POST	/from-dialogue/repropose	Repropose with locked I/O	JSON body	{skill_md, ...}
POST	/summary	Skill summary	JSON body	{summary}
POST	/from-dialogue/build_and_preview	Build and preview	JSON body	{skill_md}
POST	/preview	Preview SKILL.md	JSON body	{skill_md}
GET	/revise/terminal/{skill_id}	Revision terminal state	-	{status}
GET	/revise/inflight	In-flight revisions	-	{...}
POST	/revise	Apply user-guided revision	{skill_md, user_guidance, skill_id}	{skill_md}
POST	/commit	Commit to registry	{skill_id, skill_md, scope, agent_id?, overwrite?}	{ok}

---

18. skill_proposals.py — Skill Proposal Approval

Prefix: /api/skill_proposals

Method	Path	Description	Request	Response
GET	/	List proposals	-	[{id, ...}]
GET	/count	Pending approval count	-	{count}
GET	/{pid}	Proposal details	-	{...}
POST	/{pid}/approve	Approve	-	{ok}
POST	/{pid}/reject	Reject	{reason?}	{ok}

---

19. skill_workshop.py — Skill Studio

Prefix: /api/skill_workshop

Method	Path	Description	Request	Response
GET	/skills	List registered skills	-	[{id, name, ...}]
POST	/upload	Upload asset	multipart: file	{asset_id, url}
GET	/asset	Get asset	query: asset_id	File stream
POST	/rewrite	Rewrite storyboard	JSON body	{storyboard}
POST	/run	Start run	JSON body	{run_id}
GET	/run/{run_id}/status	Run status	-	{status, progress, ...}
GET	/run/{run_id}/images	Generated images	-	[{idx, url, ...}]
POST	/run/{run_id}/regenerate_image	Regenerate image	JSON body	{ok}
POST	/run/{run_id}/approve_images	Approve images	JSON body	{ok}
GET	/run/{run_id}/clips	Clip list	-	[{idx, ...}]
POST	/run/{run_id}/clips/{idx}/generate	Generate clip	JSON body	{ok}
POST	/run/{run_id}/concat_final	Concatenate final video	JSON body	{video_url}
GET	/draft	Get draft	-	{...}
POST	/draft	Save draft	JSON body	{ok}
GET	/history/{skill_id}	Run history	-	[{run_id, ts, ...}]
GET	/history/{skill_id}/{run_id}	Historical run details	-	{...}

---

20. asr.py — Speech Recognition

Prefix: /api

Method	Path	Description	Request	Response
POST	/asr/transcribe	Upload audio and transcribe	multipart: audio, form: language?	{text, segments}
POST	/asr/prewarm	Prewarm ASR model	-	{ok}
POST	/call/prewarm	Prewarm all call-mode models	query: agent_id?	{ok}
POST	/focus/{mode}	User attention signal	mode: dialog/call/idle, query: agent_id?, dialogue_id?	{ok}
POST	/dialog/prewarm	Prewarm dialogue-mode models	-	{ok}
GET	/gpu_tier	GPU tier + features	-	{tier, features: {...}}
POST	/model_choice	Persist missing-model decision	query: model_id, choice	{ok}

---

21. digital_human.py — Digital Human

Prefix: /api/digital_human

Method	Path	Description	Request	Response
GET	/{agent_id}/status	Asset inventory + backend recommendation	-	{assets, backend, ...}
POST	/{agent_id}/prewarm	Background preload	-	{ok}
POST	/{agent_id}/unload	Release cached session	-	{ok}
POST	/{agent_id}/regenerate_voice	Regenerate voice.wav	-	{ok}

---

22. agent_workshop.py — External Agent Import

Prefix: /api/agent_workshop

Method	Path	Description	Request	Response
GET	/kinds	Importable agent kinds	-	["openclaw", "hermes", ...]
GET	/scan/{kind}	Scan install state	-	{installed, ...}
POST	/import/{kind}/start	Start import session	{need_digital_human?, display_name?, model?}	{session_id}
POST	/import/cancel	Cancel import	{session_id}	{ok}
GET	/import/{kind}/stream	SSE import progress	query: session_id, approved_steps?	SSE
POST	/custom	Custom agent	{display_name, repo_url?, cli_command, description?, need_digital_human?}	{agent_id}

---

23. agent_assets.py — Agent Asset Management

Prefix: /api

Method	Path	Description	Request	Response
POST	/agents/upload_staging	Stage to staging area	multipart: file, form: kind(figure/voice)	{staging_id}
POST	/agents/{agent_id}/asset_job/figure	Start portrait replacement job	multipart: file	{job_id}
GET	/agents/{agent_id}/asset_job	Job status	-	{status, stage, ...}
GET	/agents/{agent_id}/asset_job/stream	SSE job stream	-	SSE
POST	/agents/{agent_id}/asset_job/retry	Retry a single stage	{stage}	{ok}
DELETE	/agents/{agent_id}/asset_job	Discard job	-	{ok}
POST	/agents/{agent_id}/asset_job/upload_stage	Sideload stage delivery	multipart: file, form: stage	{ok}
POST	/agents/{agent_id}/voice/replace	Replace voice	multipart: file, form: transcript?	{ok}
POST	/agents/{agent_id}/theme/{element}/replace	Replace theme element	multipart: file	{ok}
POST	/agents/{agent_id}/greeting/regenerate	Re-render greeting video	-	{ok}

---

24. agent_activity.py — Agent Activity

Prefix: /api

Method	Path	Description	Request	Response
GET	/agents/activity	Agent activity list	-	[{agent_id, activity, ts}]
GET	/agents/activity/stream	SSE activity stream	-	SSE

---

25. agent_recipes.py — Recipe CRUD

Prefix: /api/recipes

This is the largest route file, with 56 endpoints. The core endpoints are listed below.

Method	Path	Description
GET	/catalog	Wireable module catalog
GET	/_meta/protocol	Folder protocol spec
GET	/{recipe_id}/docs	Recipe doc list
GET	/{recipe_id}/docs/{name}	Get doc
PUT	/{recipe_id}/docs/{name}	Update doc
DELETE	/{recipe_id}/docs/{name}	Delete doc
GET	/{recipe_id}/utils	Utils file list
GET	/{recipe_id}/utils/{name}	Get utils file
PUT	/{recipe_id}/utils/{name}	Update utils file
DELETE	/{recipe_id}/utils/{name}	Delete utils file
POST	/{recipe_id}/utils/upload	Upload utils file
GET	/	List all recipes
GET	/{recipe_id}	Get recipe details
POST	/{recipe_id}/duplicate	Duplicate recipe
GET	/{recipe_id}/renderers	Custom renderer list
GET	/{recipe_id}/renderers/{name}	Get renderer source
GET	/{recipe_id}/export_zip	Export zip
POST	/import_zip	Import from zip
POST	/preview_zip	Preview zip contents
POST	/import_folder	Import from folder
POST	/install	Install recipe
POST	/{recipe_id}/create_agent	Create agent from recipe
POST	/	Create recipe
PUT	/{recipe_id}	Update recipe
POST	/_meta/validate_chain_steps	Validate chain steps
DELETE	/{recipe_id}	Delete recipe
POST	/{recipe_id}/unbind_all_and_delete	Unbind all agents then delete
GET	/_state/default	Get default recipe state
DELETE	/_state/default	Clear default
POST	/{recipe_id}/set_default	Set as default
POST	/{recipe_id}/bind/{agent_id}	Bind to agent
POST	/{recipe_id}/unbind/{agent_id}	Unbind from agent
POST	/{recipe_id}/validate	Validate recipe
GET	/chain_source/{slot}	Chain slot implementation enumeration
GET	/_meta/reasoning_templates	Reasoning template list
GET	/{recipe_id}/resolved_tools	Resolved tools
GET	/{recipe_id}/tool_catalog	Tool catalog
GET	/{recipe_id}/skill_status	Skill status
GET	/{recipe_id}/knowledge_file	Knowledge file
GET	/{recipe_id}/digital_human_slots	Digital human slots
GET	/{recipe_id}/asset_file	Asset file
GET	/library	Marketplace library list
POST	/library/install	Install from marketplace library
POST	/library/publish	Publish to marketplace library
GET	/{recipe_id}/capabilities/status/{agent_id}	Capability approval status
POST	/{recipe_id}/capabilities/approve/{agent_id}	Approve capability
DELETE	/{recipe_id}/capabilities/approve/{agent_id}	Revoke approval
POST	/eval/compare	Evaluation comparison
POST	/{recipe_id}/eval	Run evaluation
GET	/{recipe_id}/graph	Get graph definition
PUT	/{recipe_id}/graph	Update graph definition
DELETE	/{recipe_id}/graph	Delete graph
POST	/{recipe_id}/graph/test	Test graph

---

26. recipe_dev.py — Recipe Development Tools

Prefix: /api/recipe_dev

Method	Path	Description	Request	Response
POST	/compile	Compile recipe	JSON body	{ok, errors?}
POST	/dryrun	Dry run	JSON body	{outcome, units}
POST	/e2e_test	End-to-end test	JSON body	{pass, details}
POST	/publish_relay	Publish to relay	JSON body	{ok}
GET	/review_status	Review status	-	{status}

---

27. flow_templates.py — Flow Templates

Prefix: /api/flow-templates

Method	Path	Description	Request	Response
GET	/	List templates	-	[{id, name, ...}]
POST	/	Create template	JSON body	{id}
GET	/{template_id}	Get template	-	{id, template, layout, ...}
PUT	/{template_id}	Update template	JSON body	{ok}
DELETE	/{template_id}	Delete template	-	{ok}
POST	/{template_id}/validate	Validate template	-	{ok, errors?}
POST	/{template_id}/duplicate	Duplicate template	-	{new_id}
GET	/{template_id}/docs	Doc list	-	[{name}]
GET	/{template_id}/docs/{name}	Get doc	-	{content}
PUT	/{template_id}/docs/{name}	Update doc	{content}	{ok}
DELETE	/{template_id}/docs/{name}	Delete doc	-	{ok}
GET	/{template_id}/export	Export	-	JSON
POST	/import	Import	JSON body	{id}
POST	/preview_bundle	Preview bundle	JSON body	{preview}
POST	/import_bundle	Import bundle	multipart	{id}
GET	/{template_id}/export_bundle	Export bundle	-	zip file
GET	/{template_id}/renderers	Custom field renderer list	-	[{name}]
GET	/{template_id}/renderers/{name}	Get renderer	-	{source}
POST	/{template_id}/renderers/{name}	Create/update renderer	{source}	{ok}
DELETE	/{template_id}/renderers/{name}	Delete renderer	-	{ok}

---

28. flows.py — Flow Instances

Prefix: /api/flows

Method	Path	Description	Request	Response
GET	/	List instances	query: status?, template_id?, limit?	[{instance_id, template_id, status, ...}]
GET	/{instance_id}	Get instance	query: trace_tail?	{instance_id, status, trace_tail: [...]}
GET	/{instance_id}/trace	Full trace	query: limit?	[{ts, event, ...}]
POST	/{instance_id}/cancel	Force stop	-	{ok}

---

29. flow_dev.py — Flow Development Tools

Prefix: /api/flow_dev

Method	Path	Description	Request	Response
POST	/publish_relay	Publish to relay	JSON body	{ok}
GET	/review_status	Review status	-	{status}

---

30. comm (communication.py) — Communication Hub

Prefix: /api/communication

Method	Path	Description	Request	Response
GET	/messages	Message list	query: agent_id?, since?, direction?	[{id, agent_id, content, ts, direction}]
POST	/messages	User sends message to agent	JSON body	{id}
POST	/send	Agent pushes to user	JSON body	{ok}
GET	/approvals/pending	Pending approval list	query: agent_id?	[{request_id, tool, args, ...}]
POST	/approvals/request	Create approval request	JSON body	{request_id}
POST	/approvals/respond	Respond to approval	{request_id, approved, reason?, scope?, choices?}	{ok}
GET	/approvals/{request_id}	Approval status	-	{request_id, status, ...}
POST	/interrupt	Interrupt agent	{agent_id, reason?}	{ok}

---

31. broker.py — Broker Core

Prefix: /api/broker

Method	Path	Description
GET	/brokers	List brokers
POST	/brokers/{broker_id}/register	Register broker
POST	/brokers/{broker_id}/deregister	Deregister broker
POST	/brokers/{broker_id}/scopes	Set scopes
GET	/brokers/{broker_id}/card	Get card
POST	/brokers/{broker_id}/actions/{action}	Execute action
POST	/brokers/{broker_id}/deals/{deal_id}/transition	Deal state transition
GET	/brokers/{broker_id}/deals	Deal list
GET	/brokers/{broker_id}/ledger	Ledger
POST	/federation/receive	Federation receive
GET	/federation/status	Federation status
POST	/federation/rooms/{broker_id}/{room_id}/federate	Federate room
POST	/federation/threads/{broker_id}/{thread_id}/federate	Federate thread
POST	/federation/tasks/{broker_id}/{task_id}/federate	Federate task
GET	/federation/rooms/{broker_id}	Federated room list

---

32. broker_workshop.py — Broker Workshop

Prefix: /api/broker_workshop

The largest route file, with 90+ endpoints. Covers: instance management, marketplace index, covers, consent, capability approvals, CRL/trust, rooms/threads/messages/permissions/reputation/triggers/approvals.

Core endpoints:

Method	Path	Description
GET	/instances	List installed instances
GET	/instances/{broker_id}	Instance details
POST	/instances/install_from_url	Install from URL
GET	/marketplace/index	Marketplace index
GET	/marketplace/recipes/index	Recipe marketplace index
GET	/marketplace/flows/index	Flow marketplace index
POST	/marketplace/{kind}/like	Like
POST	/marketplace/{kind}/coin	Coin
GET	/marketplace/coin/balance	Coin balance
POST	/marketplace/coin/claim	Claim coins
POST	/marketplace/{kind}/view	Mark viewed
POST	/marketplace/report	Report
POST	/marketplace/ban	Ban
POST	/marketplace/unban	Unban
POST/GET	/marketplace/moderators/*	Moderator management
POST	/marketplace/cover/upload	Upload cover
POST	/marketplace/cover/generate	AI-generate cover
GET	/instances/{broker_id}/rooms	Room list
POST	/instances/{broker_id}/rooms	Create room
GET/PATCH/DELETE	/instances/{broker_id}/rooms/{room_id}	Room CRUD
GET	/instances/{broker_id}/rooms/{room_id}/threads	Thread list
POST	/instances/{broker_id}/rooms/{room_id}/threads	Create thread
POST/GET	/instances/{broker_id}/messages*	Message CRUD + reactions + search
GET	/instances/{broker_id}/reputation/{cluster_id}	Reputation
POST	/instances/{broker_id}/reputation/rate	Rate
GET/POST/DELETE	/instances/{broker_id}/triggers*	Trigger management
GET/POST/DELETE	/instances/{broker_id}/capabilities/*	Capability management
POST/GET	/instances/{broker_id}/approvals*	Vote approvals
POST/GET	/instances/crl/*	CRL management
POST/GET	/instances/trust/*	Trust management
GET/POST	/instances/{broker_id}/permissions/*	Permission management
GET/POST	/instances/{broker_id}/member_caps*	Member capabilities

---

33. broker_app.py — Broker App Static Assets

Prefix: /api/broker_app

Method	Path	Description
GET	/{broker_id}/ui/{rel:path}	UI static assets (script/link/img)
GET	/{broker_id}/cover	Cover image
GET	/{broker_id}/sdk.js	Broker SDK
GET	/_meta/sdk.js	SDK metadata

---

34. broker_assets.py — Broker Assets

Prefix: /api/broker_workshop

Method	Path	Description
POST	/instances/{broker_id}/assets	Upload asset
GET	/instances/{broker_id}/assets/{asset_id}	Get asset
GET	/instances/{broker_id}/assets	Asset list
DELETE	/instances/{broker_id}/assets/{asset_id}	Delete asset
GET	/instances/{broker_id}/capabilities	Capability list
POST	/instances/{broker_id}/capabilities/grant	Grant capability
POST	/instances/{broker_id}/capabilities/revoke	Revoke capability

---

35. guild.py — Guild System (Ventaris)

Prefix: /api/guild

The Ventaris guild subsystem. Tasks/wallets/medals/inbox/recipe runs. 80+ endpoints.

Core endpoints:

Method	Path	Description
GET/PUT	/instances/{broker_id}/rooms/{room_id}/config	Room config
POST	/instances/{broker_id}/tasks	Create task
GET	/instances/{broker_id}/tasks	Task list
GET	/instances/{broker_id}/tasks/calendar	Task calendar
GET/PUT	/instances/{broker_id}/tasks/{task_id}	Task CRUD
POST	/instances/{broker_id}/tasks/{task_id}/reassign	Reassign
POST	/instances/{broker_id}/tasks/{task_id}/publish	Publish task
POST	/instances/{broker_id}/tasks/{task_id}/accept	Accept task
POST	/instances/{broker_id}/tasks/{task_id}/contract/*	Contract management
POST	/instances/{broker_id}/tasks/{task_id}/start	Start task
POST	/instances/{broker_id}/tasks/{task_id}/complete	Complete task
POST	/instances/{broker_id}/tasks/{task_id}/cancel	Cancel task
POST	/instances/{broker_id}/tasks/{task_id}/deliveries	Submit delivery
POST	/instances/{broker_id}/deliveries/{delivery_id}/verdict	Delivery verdict
POST/GET	/instances/{broker_id}/tasks/{task_id}/subtasks*	Subtasks
POST/GET	/instances/{broker_id}/tasks/{task_id}/merge_requests*	Merge requests
GET	/instances/{broker_id}/wallets	Wallet list
GET	/instances/{broker_id}/balance/{cluster_id}	Balance
POST	/instances/{broker_id}/tokens/move	Transfer tokens
GET	/instances/{broker_id}/ledger	Ledger
POST/GET	/instances/{broker_id}/medals*	Medal management
GET	/instances/{broker_id}/archive	Archive
GET	/instances/{broker_id}/inbox	Inbox
POST	/instances/{broker_id}/inbox/*	Inbox operations
POST	/instances/{broker_id}/recipe/run	Run recipe
POST/GET	/instances/{broker_id}/tasks/{task_id}/modifications*	Modification requests

---

36. xun_da.py — Xun Da (Social Collaboration)

Prefix: /api/xun_da

Social collaboration subsystem. Tags/recipes/rooms/threads/payments/albums/reputation/medals/user profiles. 80+ endpoints.

Core endpoints:

Method	Path	Description
GET	/tags	Tag list
POST	/recipe/rebuild	Rebuild recipe
GET	/recipe/me	My recipes
POST/GET	/rooms/*	Room management (create/discover/join/close/invite)
POST/GET	/threads/*	Thread management (create/join/leave/messages/attachments/payments/settlement/albums)
GET	/reputation/me/pending	Pending reputation
GET	/badges/me	My medals
POST	/cron/tick	Cron tick
GET/PUT	/user_profile/me	My profile
POST	/user_profile/me/avatar	Upload avatar

---

37. cg.py — CG Cutscenes

Prefix: /api

Method	Path	Description
GET	/agents/manager/cg/list	CG status list
POST	/agents/manager/cg/run	Render CG
GET	/agents/manager/cg/reference/{agent_id}	CG reference
DELETE	/agents/{agent_id}/skills/{skill_id}/cg	Delete CG
GET	/skill_state	Currently active skill
POST	/agents/{agent_id}/skills/{skill_id}/cg/preview	CG preview
GET	/agents/manager/cg/steps	CG steps
POST	/agents/manager/cg/step_image	Step image
POST	/agents/manager/cg/step_image/upload	Upload step image
POST	/agents/{agent_id}/skills/{skill_id}/steps/{step_index}/dh_compose	Digital human composition
DELETE	/agents/{agent_id}/skills/{skill_id}/steps/{step_index}/image	Delete step image
GET	/agents/{agent_id}/skills/{skill_id}/steps/{step_index}/image	Get step image

---

38. gift.py — Gifts

Prefix: /api/gift

Method	Path	Description	Request	Response
GET	/video/{decision_id}	Gift video	-	Video file
POST	/swap	Swap candidate / re-search	{agent_id, dialogue_id, node_id, candidate_index?, keyword?}	{ok}
POST	/open	Mark opened	{agent_id, dialogue_id, node_id}	{ok}
POST	/purchase	Confirm purchase	{agent_id, dialogue_id, node_id}	{ok}

---

39. reports.py — Reports

Prefix: /api

Method	Path	Description
GET	/manager/reports	Flattened report list
GET	/manager/reports/by-agent	Grouped by agent
GET	/manager/reports/meta	Manager meta-report
GET	/manager/reports/content	Raw report markdown (query: path)
POST	/manager/reports/roll-up	Trigger manager_meta_review
POST	/manager/report	Legacy stub

---

40. feedback.py — Feedback

Prefix: /api/feedback

Method	Path	Description	Request	Response
POST	/proactive	Proactive message rating	{agent_id, rating(0/1), decision_id?, fired_at?, signal_summary?, action_category?, act_score?}	{ok}
GET	/proactive/stats	Feedback stats	query: agent_id?	{stats}

---

41. draft.py — Drafts

Prefix: /api/draft

Method	Path	Description	Request	Response
POST	/from_text	Auto-classify	{text, agent_id?}	{kind, draft}
POST	/schedule_from_text	Extract schedule	{text, agent_id?}	{draft}
POST	/todo_from_text	Extract todo	{text, agent_id?}	{draft}
POST	/cron_from_text	Extract cron job	{text, agent_id?}	{draft}

---

42. quick_inputs.py — Quick Inputs

Prefix: /api

Method	Path	Description	Request	Response
GET	/quick-inputs	List quick inputs	-	[{qid, text, ...}]
POST	/quick-inputs	Add	{text}	{qid}
POST	/quick-inputs/{qid}/use	Mark used	-	{ok}
DELETE	/quick-inputs/{qid}	Delete	-	{ok}

---

43. quick_ask.py — Quick Q&A

Prefix: /api/quick_ask

Method	Path	Description	Request	Response
POST	/dialogue	Create temporary dialogue	{quoted_text?}	{dialogue_id}
POST	/dialogue/{dialogue_id}/archive	Archive	-	{ok}

---

44. responses.py — OpenAI Responses API Proxy

Path: /v1/responses

Method	Path	Description	Request	Response
POST	/v1/responses	Proxy the Responses API	OpenAI Responses API body	OpenAI Responses API response (streaming supported)

---

45. learn.py — Framework Docs

Prefix: /api/learn

Method	Path	Description
GET	/docs	Doc key list
GET	/docs/{doc_key}	Get doc (plain-text markdown)

---

46. feishu.py — Feishu

Prefix: /api/feishu

Method	Path	Description	Request	Response
POST	/webhook	Feishu event delivery	Feishu event JSON	{ok}

---

47. phone_call.py — Phone Calls

Path: /api/phone_call

Method	Path	Description
GET	/api/phone_call/{agent_id}/status	Virtual cable detection + audio devices

---

48. broadcast.py — Broadcast

Prefix: /api

Method	Path	Description
GET	/broadcast/stream	SSE broadcast stream

---

49. demo.py — Demo

Prefix: /api/demo

Method	Path	Description
GET	/status	Demo status
POST	/token	Get demo token
POST	/feedback	Demo feedback

---

50. desktop_notify.py — Desktop Notifications

Prefix: /api

Method	Path	Description	Request	Response
POST	/desktop-notify/native	Send native desktop notification	{title, body, urgency?}	{ok}

---

51. dev.py — Development Endpoints

Prefix: /api/dev

Method	Path	Description
GET	/framework-docs	Framework doc list
GET	/framework-docs/{name}	Get framework doc
GET	/llm_gates	LLM gate status
POST	/fake_gift	Fake gift
POST	/gift_demo	Gift demo
GET	/pools	Connection pool status
POST	/thread_dump	Thread dump

---

52. setup.py — Setup Wizard

Prefix: /api/setup

Method	Path	Description
GET	/seethrough	See-through render state
POST	/seethrough/backend	Set see-through backend
POST	/seethrough/check-login	Check see-through login
GET	/status	Setup status
GET	/llm_presets	LLM preset list
POST	/chrome	Install Chrome
GET	/chrome/install/stream	Chrome install SSE
GET	/tutorial_media/{step_id}/{filename}	Tutorial media asset
GET	/extensions	Extension list
POST	/extensions/select	Select extension
POST	/complete	Complete setup
GET	/deps/install/stream	Dependency install SSE
GET	/deps/install/stream/{mirror}	Mirrored dependency install SSE
GET	/models/offer	Model offers
POST	/models/download	Download model

---

53. onboarding.py — Onboarding

Prefix: /api/onboarding

Method	Path	Description
POST	/probe_media	Probe media capabilities
GET	/media	Media capability list
POST	/media/{capability}	Enable capability
DELETE	/media/{capability}	Disable capability
GET	/probe_env	Environment probe
GET	/state	Onboarding state
PUT	/state	Set onboarding state
GET	/tutorial_state	Tutorial state
PUT	/tutorial_state	Set tutorial state

---

54. user_profile.py — Broker User Profile

Prefix: /api/broker_user

Method	Path	Description
GET	/profile	Current user profile
PUT	/profile	Update profile
GET	/profile/{cluster_id}	Other user's profile
GET	/profile/search	Search users
POST	/profile/import_from_agent	Import from agent
POST	/profile/import_from_user	Import from desktop user
POST	/profile/ai_infer	AI infer
POST	/assets	Upload asset
GET	/assets/{asset_id}	Get asset

---

55. tool_skills.py — Tool-Level Skills

Prefix: /api

Method	Path	Description
POST	/tool_skills/import/folder	Import from folder
POST	/tool_skills/import/zip	Import from zip
POST	/tool_skills/import/text	Import from text
GET	/tool_skills	List
DELETE	/tool_skills/{skill_id}	Delete
GET	/tool_skills/_meta/clients	Client metadata

---

56. tools_catalog.py / tools_source.py — Tool Catalog

Prefix: /api/tools

Method	Path	Description
GET	/catalog	Tool catalog
GET	/{name}	Tool details
GET	/{name}/source	Tool source

---

57. marketplace_artifacts.py — Marketplace Artifacts

Prefix: /api

Method	Path	Description
GET	/marketplace/artifact_updates	Artifact updates
POST	/marketplace/artifacts/install	Install artifact

---

58. vram.py — VRAM

Prefix: /api/vram

Method	Path	Description
POST	/yield	Yield VRAM

---

59. broker_dev.py — Broker Development Tools

Prefix: /api/broker_dev

Method	Path	Description
GET	/guide	Development guide
GET	/keys	Key list
POST	/keys	Generate key
POST	/pack	Pack
POST	/sign	Sign
POST	/verify	Verify
POST	/publish	Publish
POST	/publish_relay	Publish to relay
GET	/review_status	Review status

---

Introspection tool: src/models/RAG/bridge_api_reflected.py automatically diffs the "hand-written catalog vs the actual FastAPI routes" so the documentation stays honest as routes are added or removed. The CLI covers every REST endpoint except WebSocket-only streams.