Sign in
agents

Create and launch a new agent run.

Changed on

Returns as soon as the run is created; the devbox provisions in the background. Watch the agent status or event stream for progress.

post/agents

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/agents
  • Auth: none declared. Required headers: x-organization-id

Headers

x-organization-idstring required

Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.

Request body

namestring
agentTypestring required
promptstring required
systemPromptstring
personaIdstring
modelstring
modelEndpointIdstring
blueprintIdstring
blueprintNamestring
promptMode'implement' | 'plan' | 'review'
listenersEnabledboolean
labelIdsstring[]
groupIdstring
authMethod'org-key' | 'claude-max' | 'codex-subscription'
providerSecretIdstring
repoSlugstring
repoBranchstring
orgShare'none' | 'view' | 'edit'

Response

Response

idstring required
streamIdstring required
agentTypestring required
status'starting' | 'running' | 'needs_input' | 'completed' | 'interrupted' | 'stopping' | 'stopped' | 'error' | 'terminated' required
turnState'working' | 'idle' nullable required
turnStateVersioninteger required
devboxIdstring nullable required
tunnelKeystring nullable
namestring required
promptstring required
systemPromptstring nullable
personaIdstring nullable
modelstring nullable
blueprintIdstring nullable
blueprintNamestring nullable
promptMode'implement' | 'plan' | 'review' nullable
createdAtnumber required
lastActiveAtnumber nullable
archivedboolean required
ownerIdstring required
userIdstring nullable
prUrlstring nullable
hasBackgroundWorkboolean
listenersEnabledboolean
suspendAtTurnEndboolean
organizationIdstring required
modelProviderSecretIdstring nullable
credentialSyncPendingboolean nullable
originatorstring nullable
pinnedboolean required
mark'blocked' | 'in_review' | 'completed' nullable
viewerAccess'owner' | 'edit' | 'view'
launchWarningsstring[]

Changes