API audiences and compatibility
Which VoiceStudio interfaces are public, which are browser-only, and which are never customer surface.
Every control-plane operation belongs to one audience. Sharing one OpenAPI source does not make an operation public.
| Audience | Routes | Who calls it | Published here? |
|---|---|---|---|
| Public developer API | /v1/* | A scoped developer credential | Yes, in the Cloud projection |
| Website edge API | Reviewed anonymous /v1/marketing/* | The site's own forms | No |
| Dashboard/BFF API | /dashboard/v1/* | The dashboard, with a same-origin session | No |
| Operator API | Reviewed /internal/v1/* | Platform operators | No |
| Internal service API | Other /internal/v1/* | Private services | No |
Website edge, operator and internal routes are never customer API surface. They
are absent from /cloud-openapi.json, including schemas only they use. Browsers
never receive a developer credential, and public clients never use the
dashboard session cookie.
Compatibility
No cross-product compatibility subset is released. The local 0.5.0 and Cloud
preview 1.0.0 contracts both have POST /v1/audio/transcriptions, but fields,
auth, Artifact and Job behavior, timeouts and errors are not declared
interchangeable. That needs the behavioral tests in
#71 to pass for a named pair of
versions. Until then, a shared route name is overlap, not compatibility.
Releasing Cloud
Publishing an active Cloud server in the OpenAPI document or in executable examples is a release step. It needs, in order:
- Verified production DNS and TLS.
- Smoke tests for auth, public routing and customer-safe failures.
- The #71 compatibility and rollback checks for the exact versions.
- A regenerated projection that no longer says
unavailable.
Rollback removes the active server. Durable Jobs, Artifacts and idempotency records are left as they are.