Public Boundary
These docs cover the current public Prompt Orchestra surface, not every route implemented in saas-ai-api.
Supported public surface
| Family | Status | Routes |
|---|---|---|
| Stateless agent runtime | stable | 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 |
| Setup verification | stable | POST /api/setup/verify |
| Stateless agent authoring and workflow | public beta | 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 |
| Stateless agent comparison and version iteration | public beta | GET /api/agent-runs/compare, GET /api/agents/:id/versions/:versionId/diff, POST /api/agents/:id/versions/:versionId/rollback |
| Skills | public beta | GET /api/skills, POST /api/skills, GET /api/skills/:id, PATCH /api/skills/:id, POST /api/skills/:id/versions, POST /api/skills/:id/publish, POST /api/skills/:id/preview, GET /api/skills/:id/versions/:versionId/diff, POST /api/skills/:id/run |
| Tools | public beta | GET /api/tools, POST /api/tools, GET /api/tools/:id, PATCH /api/tools/:id, POST /api/tools/:id/versions, GET /api/tools/:id/versions/:versionId/diff |
| Evaluations | public beta | GET /api/skills/:id/evaluation-cases, POST /api/skills/:id/evaluation-cases, POST /api/skills/:id/evaluations/run, GET /api/skills/:id/evaluations/:evaluationRunId |
Excluded route families
| Family | Status | Why it is excluded from public docs |
|---|---|---|
| Sessions | non-public | Explicitly excluded from the Phase 4 public allowlist. |
| Realtime and voice | non-public | Realtime remains partner beta until supported-org proof passes and continuity is fully trusted. |
| Low-level agent mutation helpers | non-public | Public authoring goes through version create plus saveWorkflow, validateWorkflow, publish, compare, diff, and rollback. Version patch helpers and step/transition mutation routes remain outside the public surface. |
| Prompts | non-public | Implemented in the API, but not part of the frozen public contract surface. |
/api/runs* orchestration run routes | non-public | Implemented, but outside the public allowlist. Public persisted run detail is GET /api/agent-runs/:id, not GET /api/runs/:id. |
| Costs and reporting helpers | non-public | Implemented, but outside the current public route inventory. |
| Key-management and admin routes | non-public | Used by setup and admin flows, but not part of the public route docs surface. |
| Legacy runtime routes | legacy | Kept for compatibility or migration, not for new public integrations. |
Workflow is public only as agent-scoped dependent configuration. There is no top-level public workflow noun and no standalone public workflow resource family.
Documentation rule
If a route exists in the API implementation but is not listed in the supported public surface above, these docs treat it as non-public.
That is intentional. Route availability is broader than the current public promise.