Prompt Orchestra Documentation

These docs describe the current public Prompt Orchestra surface, not every handler implemented in saas-ai-api.

Public surface at a glance

• stable: stateless agent runtime - GET /api/agents/:id, POST /api/agents/:id/run, GET /api/agent-runs/:id, POST /api/agent-runs/:id/load-inputs, POST /api/agent-runs/:id/rerun-from-step
• stable: POST /api/setup/verify
• public beta: stateless agent authoring and iteration - GET /api/agents, POST /api/agents, PATCH /api/agents/:id, POST /api/agents/:id/versions, POST /api/agents/:id/publish, PUT /api/agent-versions/:id/workflow, POST /api/agent-versions/:id/workflow/validate, GET /api/agent-runs/compare, GET /api/agents/:id/versions/:versionId/diff, POST /api/agents/:id/versions/:versionId/rollback
• public beta: skills, tools, and evaluations
• public beta: stateless skill preview/diff and tool diff helpers
• non-public: /api/runs*, costs, sessions, realtime/voice, low-level agent mutation helpers outside the allowlist, key-management/admin routes, and legacy routes

See Public Boundary before relying on any route family that is not called out explicitly above.

Who this is for

• Developers integrating the HTTP API or TypeScript SDK (@prompt-mv/orchestration)
• Product and ops teams who need honest run, validation, and diagnostic docs for the released surface
• Teams who want the supported public contract, not a route dump of every internal handler

Start here

1. AI Platform Setup - in product this now lives under AI Platform -> Authentication; use it to copy the current organizationId, verify auth, and confirm the released route path.
2. Quickstart HTTP - call the released HTTP routes with organizationId and a Bearer token.
3. Quickstart TypeScript SDK - construct PromptOrchestraClient with baseUrl and accessToken or apiKey, then run the stateless authoring flow.
4. Public Boundary - see what is stable, public beta, non-public, and legacy.
5. Inspect Your First Run - inspect the stable public agent-run detail surface.
6. Authentication - Bearer tokens, org scoping, and where API keys apply.

Accuracy

We validate docs against the public allowlist, contract package, API auth/resolver layer, and the shipped SDK implementation.

If implementation breadth is wider than the public boundary, these docs follow the boundary and label the extra routes as non-public.