Skip to main content
PUT
Assign an Agent workspace

Authorizations

Authorization
string
header
required

Bearer JWT token or API Key (sk-*).

Path Parameters

agentId
string
required

Body

application/json
mode
enum<string>
required

MANAGED creates a new API-owned agent workspace. EXISTING links an accessible Explorer folder.

Available options:
MANAGED,
EXISTING
Example:

"MANAGED"

version
number
required

Current agent version used for optimistic locking.

Required range: x >= 0
Example:

12

storageEntryId
string<uuid>

Existing Explorer folder id. Required only when mode is EXISTING.

Example:

"33333333-3333-4333-8333-333333333333"

Response

200 - application/json
agentId
string
required

Stable agent id.

Example:

"99999999-9999-4999-8999-999999999999"

name
string
required

Agent display name.

Example:

"Release Reporter"

status
enum<string>
required

Agent lifecycle status.

Available options:
ACTIVE,
PAUSED,
DISABLED
Example:

"ACTIVE"

serviceAccountUserId
string
required

Service account user id used as execution principal.

Example:

"11111111-1111-4111-8111-111111111111"

config
object
required

Persisted agent runtime defaults and identity inputs.

Example:
policy
object
required

Persisted execution constraints and role gates.

Example:
createdBy
string
required

User id that created the agent.

Example:

"44444444-4444-4444-8444-444444444444"

createdAt
string<date-time>
required

Creation timestamp.

Example:

"2026-06-13T10:00:00.000Z"

lastUpdateAt
string<date-time>
required

Last update timestamp.

Example:

"2026-06-13T10:15:00.000Z"

lastUpdateBy
string
required

User id that last updated the agent.

Example:

"44444444-4444-4444-8444-444444444444"

version
number
required

Optimistic locking version.

Example:

3

desc
string

Operator-facing description.

Example:

"Summarizes release status and creates operator updates."

ownerId
string

Owning user or group id.

Example:

"22222222-2222-4222-8222-222222222222"

ownerType
string

Owner type, typically USER or GROUP.

Example:

"USER"

rootStorageEntryId
string

Agent workspace root storage entry id.

Example:

"33333333-3333-4333-8333-333333333333"

metadata
object

Resource metadata.

Example:
avatar
string

Signed avatar URL, when an avatar is configured.

Example:

"https://storage.example/avatar.png"

summary
object

Per-agent operational summary when requested by list or overview endpoints.

Example:
Last modified on September 5, 2026