Skip to content
Scope

Create or update agent (upsert)

POST
/api/v1/agents
 
curl --request POST \
  --url https://example.com/api/v1/agents \
  --header 'Content-Type: application/json' \
  --data '{ "_id": "example", "name": "example", "description": "example", "modelProvider": "example", "supportedModels": [ "example" ], "defaultModel": "example", "available": true, "capabilities": { "supportsReasoningEffort": true, "supportsMcpServers": true, "supportsSkills": true, "supportsExtensions": true } }'

Request Body

Section titled “Request Body ”
Media type application/json
object
_id
required
string
>= 1 characters
name
required
string
>= 1 characters
description
string
modelProvider
string
supportedModels
Array<string>
defaultModel
string
available
boolean
capabilities
object
supportsReasoningEffort
boolean
supportsMcpServers
boolean
supportsSkills
boolean
supportsExtensions
boolean
Example generated
{
  "_id": "example",
  "name": "example",
  "description": "example",
  "modelProvider": "example",
  "supportedModels": [
    "example"
  ],
  "defaultModel": "example",
  "available": true,
  "capabilities": {
    "supportsReasoningEffort": true,
    "supportsMcpServers": true,
    "supportsSkills": true,
    "supportsExtensions": true
  }
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Success

Media type application/json
object
_id
required
string
name
required
string
description
string
modelProvider
string
supportedModels
required
Array<string>
defaultModel
string
available
boolean
capabilities
object
supportsReasoningEffort
boolean
supportsMcpServers
boolean
supportsSkills
boolean
supportsExtensions
boolean
versions
Array<object>
object
agentVersion
required
string
>= 1 characters
workerVersion
required
string
>= 1 characters
components
required
object
key
additional properties
string
gitCommit
required
string
>= 1 characters
buildTime
required
string
>= 1 characters
imageTag
required
string
>= 1 characters
queueName
string
status
required
string
Allowed values: active retired
createdAt
required
string | null format: date-time
createdAt
required
string | null format: date-time
updatedAt
string | null format: date-time
deletedAt
string | null format: date-time
Example 
{
  "versions": [
    {
      "status": "active"
    }
  ]
}

400

Section titled “400 ”

Validation error

409

Section titled “409 ”

Restored agent versions conflict with an active queue owner