Runtype APIAgents

Create agent

Create a new agent with optional capabilities and configuration. Supports runtype, external, and claude_managed agent types. External-agent auth credentials are accepted on write but returned as <redacted>; a configuration copied from a management response must replace that placeholder with the real credential before create.

Authentication

AuthorizationBearer
API key or Clerk session token

Request

This endpoint expects an object.
namestringRequired>=1 character
agentTypeenumOptionalDefaults to runtype
Allowed values:
capabilitieslist of objectsOptional
claudeManagedConfigobjectOptional
configobjectOptional
descriptionstringOptional
externalConfigobjectOptional
iconstringOptional<=50 characters
maxTurnsintegerOptional1-100
primaryFlowIdanyOptionalDeprecated

primaryFlowId is retired: primary-flow agents were removed (ADR 0024). Attach the flow to the agent as a runtime tool ({ toolType: ‘flow’, flowId }) or dispatch the flow directly via POST /v1/dispatch.

Response

Agent created
agentTypestring
capabilitieslist of objects
claudeManagedConfigmap from strings to any or null
configmap from strings to any or null
configHashstring or null
createdAtstring
descriptionstring or null
draftVersionIdstring or null
externalConfigmap from strings to any or null

External-agent configuration. Configured auth.credentials values are write-only and returned as <redacted>, never plaintext.

healthStatusstring or null
iconstring or null
idstring
lastHealthCheckAtstring or null
lastModifiedSourcestring or null
namestring
organizationIdstring or null
publishedVersionIdstring or null
statusstring
updatedAtstring
userIdstring
_warningslist of stringsOptional
dashboardUrlstringOptional
sandboxCapabilityIssueslist of objectsOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error