Skip to main content

Documentation Index

Fetch the complete documentation index at: https://avocadostudioai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This tab documents the Orchestrator HTTP API — the brain that runs editor sessions, calls the LLMs, and serves draft state to integrated sites. The same API is what the editor app, the avocado-register CLI, the Onboarding agent, and any Bring Your Own Coding Agent workflow all talk to.

​
Status

This is a placeholder spec, not a complete contract. The OpenAPI document under Orchestrator endpoints in the sidebar is auto-generated from the running Fastify routes via @fastify/swagger. Most orchestrator routes do not have request/response schemas attached today, so what you see for each operation is essentially “this URL exists, accepts these HTTP methods, and returns something” — the actual request body shape and response payload are not yet documented in the spec.What this means in practice:
  • The list of endpoints is complete and accurate (it’s reflected from the live route table).
  • The HTTP methods are accurate.
  • The request bodies, query parameters, and response shapes are mostly empty placeholders.
  • The “Try it” panel in each operation page lets you send requests, but won’t validate or autocomplete payloads.
  • Internal-only routes (/telemetry/*, /contentful/*, /gdrive/*, /jira/*, /restore/*, etc.) are filtered out — only the public-facing surface is listed.
If you actually need to call one of these endpoints today, the most reliable references are:
  1. The route source files in apps/orchestrator/src/routes/*.ts — every route is named, documented, and the request/response types are inline.
  2. The editor’s network calls — open browser devtools, perform an action, and inspect what the editor sends to the orchestrator.
  3. The avocado-register CLI source for a complete worked example of POST /sites/register.
We plan to upgrade this spec to a real, complete OpenAPI document by attaching Zod schemas to the most-used routes via fastify-type-provider-zod — which would also add runtime validation as a side benefit. There’s no timeline for that work; if you need it sooner, open an issue describing your use case so we can prioritize.

​
What the orchestrator exposes (high level)

The public surface groups into nine areas, mirroring the OpenAPI tags:
TagWhat it coversUsed by
SitesSite registration and listing — POST /sites/register, GET /sitesThe editor on mount, avocado-register CLI
ChatAI chat / planning — POST /chat, POST /chat/start, GET /chat/stream, POST /chat/cancelEditor’s per-edit chat panel
Sites AgentSite onboarding agent (migrate / integrate / create modes) — POST /sites-agent/start, GET /sites-agent/stream, POST /sites-agent/respond, POST /sites-agent/cancelEditor’s Onboarding agent FAB
DraftDraft content read endpoints — GET /draft/pages, GET /draft/slugs, GET /draft/site-config, POST /draft/bootstrapThe integrated site (called from fetchEditorPage / createSitePage)
PublishPublishing endpoints — POST /publish, GET /publish/status, GET /publish/contentEditor’s publish flow
HistoryUndo / redo / version log — GET /history/log, GET /history/status, POST /history/undo, POST /history/redo, POST /history/restoreEditor’s history panel
AuthOptional access password gate — POST /auth/verify, GET /auth/statusEditor login screen if ACCESS_PASSWORD_HASH is set
MediaImage upload, generation, search — POST /image/upload, POST /image/generate, POST /image/generate/chat, POST /image/interpret, GET /unsplash/search, GET /generated-images/:fileNameEditor’s Asset Manager
HealthService health and readiness — GET /health, GET /docs/jsonContainer health checks, this docs site

​
Auth model

Most orchestrator routes are unauthenticated today. The orchestrator is designed to be reachable from your editor and from your integrated sites — both of which run inside your trust boundary. There are two optional gates:
  1. Access password (editor-facing) — set ACCESS_PASSWORD_HASH on the orchestrator and the editor will prompt for a password before letting users in. Verified via POST /auth/verify. Off by default.
  2. Publish token (integration-facing) — set PUBLISH_TOKEN on the orchestrator and POST /publish requests must include x-publish-token: <token> in headers. Off by default; recommended for production.
There’s no per-user authentication or session-bound API key today. If you expose the orchestrator to the public internet without these gates, anyone who knows the URL can use it. See Docker Deployment for the broader hosting story.

​
Regenerating this spec

The spec file at docs-site/api-reference/orchestrator.openapi.json is generated by a one-shot script that imports the orchestrator’s app, waits for all routes to register, then dumps the @fastify/swagger reflection. 
pnpm --filter @ai-site-editor/orchestrator export-openapi
The script runs with NODE_ENV=test so the orchestrator does not actually start listening on port 4200 — it only registers route plugins, which is enough for @fastify/swagger to introspect them. Output goes to docs-site/api-reference/orchestrator.openapi.json and counts the operations exported. Run this any time after adding, removing, or renaming a route on the orchestrator. The Mintlify docs site will pick up the new spec on its next reload.

​
Reporting issues with the spec

If an operation here is missing, mislabeled, or you need a request/response shape that isn’t documented:
  • For missing schemas (the placeholder situation above): file an issue at github.com/yu7321/avocado describing which route you need and your use case. This helps prioritize the Zod-schema upgrade work.
  • For outright bugs (an endpoint listed here doesn’t exist on the running orchestrator): the spec is stale — either the orchestrator changed without re-running export-openapi, or there’s a bug in the route filter. Open an issue with [api-reference] in the title.
  • For internal routes that shouldn’t be public: the route filter at apps/orchestrator/src/index.ts (INTERNAL_ROUTE_PREFIXES) decides what’s filtered. Add your prefix there and re-run the export.