Prompt DrivenSTUDIO

API contract

Agent API

Use the CLI first. These endpoint contracts exist for callers that need direct HTTP integration with the documented agent surface.

Endpoint map

MethodPathUse
GET/api/agent/versionAPI and client version compatibility.
GET/api/agent/auth/statusAuthentication status for the current token or profile.
POST/api/agent/auth/device/startStart device login for interactive CLI auth.
POST/api/agent/auth/device/completeComplete device login after browser approval.
POST/api/agent/auth/tokensCreate a scoped token. rawToken is shown once.
GET/api/agent/auth/tokensList token metadata available to the caller.
DELETE/api/agent/auth/tokens/[tokenId]Revoke a token by id.
POST/api/agent/projectsCreate a project for automation.
GET/api/agent/projects/[projectId]Read project metadata.
GET/api/agent/projects/[projectId]/scriptRead a project script file.
PUT/api/agent/projects/[projectId]/scriptWrite a project script file.
GET/api/agent/projects/[projectId]/artifactsList public project artifacts for automation.
GET/api/agent/reference-librariesList Reference Libraries visible to the current token or project.
GET/api/agent/reference-libraries/[libraryId]/itemsList visible items for a Reference Library.
POST/api/agent/projects/[projectId]/reference-librariesCreate a user-scoped Reference Library owned by the current token principal.
GET/api/agent/projects/[projectId]/reference-libraries/[libraryId]/grantsList library-level user grants for a Reference Library.
POST/api/agent/projects/[projectId]/reference-libraries/[libraryId]/grantsGrant library-level can-use or admin access to another user.
DELETE/api/agent/projects/[projectId]/reference-libraries/[libraryId]/grants/[grantId]Revoke a library-level user grant.
GET/api/agent/projects/[projectId]/reference-library-policyRead project Reference Library capture policy.
PATCH/api/agent/projects/[projectId]/reference-library-policySet project Reference Library capture policy.
GET/api/agent/projects/[projectId]/reference-library-bindingsList project Reference Library bindings and rights state.
POST/api/agent/projects/[projectId]/reference-library-bindingsAttach a pinned Reference Library item version to a project artifact.
POST/api/agent/projects/[projectId]/reference-library-bindings/[bindingId]/updateDry-run or accept a newer Reference Library binding version.
DELETE/api/agent/projects/[projectId]/reference-library-bindings/[bindingId]Detach a project Reference Library binding while preserving local alternatives.
POST/api/agent/projects/[projectId]/references/captureCapture a saved project reference into the private draft Reference Library.
POST/api/agent/projects/[projectId]/references/publish-capturedPublish an already captured private-draft project reference.
POST/api/agent/projects/[projectId]/reset-pipelineReset pipeline state for scoped retries.
POST/api/agent/pipeline/planPlan a pipeline run.
POST/api/agent/pipeline/runRun pipeline stages or a permitted retry.
GET/api/agent/pipeline/statusRead 15-stage agent pipeline status.
GET/api/agent/jobs/[jobId]Read durable job state.
POST/api/agent/jobs/[jobId]Cancel a job.
GET/api/agent/jobs/[jobId]/eventsStream job events as newline-delimited JSON.
POST/api/agent/distribution/packageGenerate or refresh a distribution package.
GET/api/agent/distribution/packageRead distribution package status.
POST/api/agent/distribution/thumbnails/uploadUpload and optionally replace a selected YouTube thumbnail.
POST/api/agent/distribution/publishPublish through a selected server-side connection.
GET/api/agent/distribution/connectionsList server-side distribution connections.
POST/api/agent/distribution/connectionSelect a distribution connection for publish.
POST/api/agent/release-videoCreate and optionally wait for an end-to-end release video run.
POST/api/agent/release-video/preflightValidate release-video readiness without mutating projects or starting paid work.

Request and response envelopes

  • Successful responses expose ok and data or a command-specific result field.
  • Errors expose ok: false plus error.code, error.message, and optional error.details.
  • Long-running operations return durable ids and may include an events URL for newline-delimited JSON progress.
  • Synchronous runner steps may complete through JSON responses and should be followed by a status refresh.

Agent pipeline status

The status response includes stageOrder and stages using the 15-stage agent view:

  1. 01setup
  2. 02script
  3. 03references
  4. 04tts-script
  5. 05tts-render
  6. 06audio-sync
  7. 07specs
  8. 08veo
  9. 09compositions
  10. 10music
  11. 11render
  12. 12stitch
  13. 13audit
  14. 14distribution-package
  15. 15distribution-publish
  • The human UI combines render and stitch under Render.
  • The human UI combines distribution-package and distribution-publish under Distribution.
  • The agent status API keeps those stages separate so automation can distinguish packaging, upload, render, and stitch failures.

The current order is setup, script, references, tts-script, tts-render, audio-sync, specs, veo, compositions, music, render, stitch, audit, distribution-package, distribution-publish. Async job steps stream or poll progress; synchronous runner steps return JSON and then need a status refresh.

Style Guide boundary

  • Style Guide routes are not listed as Phase 1 agent API endpoints.
  • Selected Style Guide is a project source artifact consumed by references, specs, video generation, compositions, music, audit, and conditional TTS script behavior.
  • Style Guide changes can stale downstream stages through project freshness.
  • Distribution is not a direct Style Guide consumer.

openapi.json status

openapi.json is planned for a later phase and is not linked in Phase 1.