updateAgent

PATCH

/api/v1/agents/{agentId}

Image and resource changes take effect after a rebuild (see needsRebuild).

updateAgent

curl --request PATCH \
  --url '<base-url>/api/v1/agents/<agentId>' \
  --header 'Content-Type: application/json' \
  --cookie 'agenthold_session=<agenthold_session>' \
  --data '
{
  "name": "string",
  "image": "string",
  "cpus": 0,
  "memoryMb": 0,
  "idleMinutes": 1,
  "harness": "string",
  "model": "string",
  "permissionPolicy": "auto-approve"
}
'

const url = '<base-url>/api/v1/agents/<agentId>';
const options = {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    cookie: 'agenthold_session=<agenthold_session>'
  },
  body: JSON.stringify({
    name: 'string',
    image: 'string',
    cpus: 0,
    memoryMb: 0,
    idleMinutes: 1,
    harness: 'string',
    model: 'string',
    permissionPolicy: 'auto-approve'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "<base-url>/api/v1/agents/<agentId>"

payload = {
    "name": "string",
    "image": "string",
    "cpus": 0,
    "memoryMb": 0,
    "idleMinutes": 1,
    "harness": "string",
    "model": "string",
    "permissionPolicy": "auto-approve"
}
headers = {
    "cookie": "agenthold_session=<agenthold_session>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "id": "string",
  "workspaceId": "string",
  "name": "string",
  "owner": {
    "id": "string",
    "email": "string",
    "name": "string",
    "avatarUrl": "string"
  },
  "image": "string",
  "harness": "string",
  "cpus": 0,
  "memoryMb": 0,
  "idleMinutes": 0,
  "state": "creating",
  "stateError": "string",
  "stateChangedAt": "2019-08-24T14:15:22Z",
  "needsRebuild": true,
  "model": "string",
  "permissionPolicy": "auto-approve",
  "credentialsInSandbox": true,
  "login": {
    "source": "account",
    "user": {
      "id": "string",
      "email": "string",
      "name": "string",
      "avatarUrl": "string"
    },
    "mine": true,
    "connected": true,
    "kind": "string",
    "status": "ok",
    "reason": "string"
  },
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "sleepsAt": "2019-08-24T14:15:22Z",
  "role": "viewer",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "error": "string"
}

{
  "error": "string"
}

{
  "error": "string"
}

Authorization

session
optional
API key in cookie

token
optional
HTTP Bearer
Authorization: Bearer <token>

Path parameters

agentId
string
required

Request body JSON required

name
optional
string
maxLength: 100 · minLength: 1
image
optional
string
cpus
optional
number
memoryMb
optional
integer
format: int64
idleMinutes
optional
integer
maximum: 10080 · minimum: 1
harness
optional
string
Harness id (see /harnesses). Default claude-code.
model
optional
string
permissionPolicy
optional
auto-approve
or
ask

Returns

200

Updated.

JSON

id
string
required
workspaceId
string
required
name
string
required
owner
object
required
- id
  string
  required
- email
  string
  required
- name
  string
  required
- avatarUrl
  string
  required
}
image
string
required
harness
string
required
cpus
number
required
memoryMb
integer
required
format: int64
idleMinutes
integer
required
state
string
·
one of 8 values
required
Allowed values: creating, starting, running, stopping, sleeping, rebuilding, destroying, error
stateError
string
required
stateChangedAt
string
required
format: date-time
needsRebuild
boolean
required
Image or resources changed since the sandbox was built.
model
string
required
permissionPolicy
auto-approve
or
ask
required
credentialsInSandbox
boolean
required
A harness login was completed inside the sandbox; the agent can read its own credentials.
login
object
required
Which login the agent's harness uses.
- source
  account
  or
  secret
  or
  sandbox
  or
  unsupported
  required
  account: the account login of user. secret: an API key secret attached to the agent wins. sandbox: whatever is signed in inside the sandbox. unsupported: the harness has no account logins.
- mine
  boolean
  required
  You are that user.
- connected
  boolean
  required
  That user has connected a login for the agent's harness.
- user
  optional
  object
  Whose account logins the agent uses.
  
  id
  string
  required
  email
  string
  required
  name
  string
  required
  avatarUrl
  string
  required
- kind
  optional
  string
  How that login was connected.
- status
  optional
  ok
  or
  error
- reason
  optional
  string
  Why the account login is not used although a user is set.
}
role
viewer
or
operator
or
admin
required
createdAt
string
required
format: date-time
updatedAt
string
required
format: date-time
lastActivityAt
optional
string
Last activity while running (prompts, terminals, files, CPU use in the sandbox).

format: date-time
sleepsAt
optional
string
When the agent goes to sleep if nothing happens. Absent while busy or not running.

format: date-time

400

Error.

JSON

error
string
required

403

Error.

JSON

error
string
required

404

Error.

JSON

error
string
required