Assign an Agent workspace
Assign an Agent workspace. The request enforces Agent roles, ownership, workspace boundaries, and lifecycle state.
curl --request PUT \
--url https://api.revoengine.com/api/v1/agents/{agentId}/workspace \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"mode": "MANAGED",
"version": 12
}
'const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({mode: 'MANAGED', version: 12})
};
fetch('https://api.revoengine.com/api/v1/agents/{agentId}/workspace', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.revoengine.com/api/v1/agents/{agentId}/workspace"
payload = {
"mode": "MANAGED",
"version": 12
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text){
"agentId": "99999999-9999-4999-8999-999999999999",
"name": "Release Reporter",
"status": "ACTIVE",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111",
"config": {
"model": "configured-model",
"maxTicks": 24
},
"policy": {
"maxTicks": 24,
"toolNames": [
"ref_search"
]
},
"createdBy": "44444444-4444-4444-8444-444444444444",
"createdAt": "2026-06-13T10:00:00.000Z",
"lastUpdateAt": "2026-06-13T10:15:00.000Z",
"lastUpdateBy": "44444444-4444-4444-8444-444444444444",
"version": 3,
"desc": "Summarizes release status and creates operator updates.",
"ownerId": "22222222-2222-4222-8222-222222222222",
"ownerType": "USER",
"rootStorageEntryId": "33333333-3333-4333-8333-333333333333",
"metadata": {
"team": "operations"
},
"avatar": "https://storage.example/avatar.png",
"summary": {
"activeRunCount": 1,
"queuedInboxCount": 3
}
}Authorizations
Bearer JWT token or API Key (sk-*).
Path Parameters
Body
MANAGED creates a new API-owned agent workspace. EXISTING links an accessible Explorer folder.
MANAGED, EXISTING "MANAGED"
Current agent version used for optimistic locking.
x >= 012
Existing Explorer folder id. Required only when mode is EXISTING.
"33333333-3333-4333-8333-333333333333"
Response
Stable agent id.
"99999999-9999-4999-8999-999999999999"
Agent display name.
"Release Reporter"
Agent lifecycle status.
ACTIVE, PAUSED, DISABLED "ACTIVE"
Service account user id used as execution principal.
"11111111-1111-4111-8111-111111111111"
Persisted agent runtime defaults and identity inputs.
{
"model": "configured-model",
"maxTicks": 24
}
Persisted execution constraints and role gates.
{
"maxTicks": 24,
"toolNames": ["ref_search"]
}
User id that created the agent.
"44444444-4444-4444-8444-444444444444"
Creation timestamp.
"2026-06-13T10:00:00.000Z"
Last update timestamp.
"2026-06-13T10:15:00.000Z"
User id that last updated the agent.
"44444444-4444-4444-8444-444444444444"
Optimistic locking version.
3
Operator-facing description.
"Summarizes release status and creates operator updates."
Owning user or group id.
"22222222-2222-4222-8222-222222222222"
Owner type, typically USER or GROUP.
"USER"
Agent workspace root storage entry id.
"33333333-3333-4333-8333-333333333333"
Resource metadata.
{ "team": "operations" }
Signed avatar URL, when an avatar is configured.
"https://storage.example/avatar.png"
Per-agent operational summary when requested by list or overview endpoints.
Show child attributes
Show child attributes
{
"activeRunCount": 1,
"queuedInboxCount": 3
}
curl --request PUT \
--url https://api.revoengine.com/api/v1/agents/{agentId}/workspace \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"mode": "MANAGED",
"version": 12
}
'const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({mode: 'MANAGED', version: 12})
};
fetch('https://api.revoengine.com/api/v1/agents/{agentId}/workspace', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.revoengine.com/api/v1/agents/{agentId}/workspace"
payload = {
"mode": "MANAGED",
"version": 12
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text){
"agentId": "99999999-9999-4999-8999-999999999999",
"name": "Release Reporter",
"status": "ACTIVE",
"serviceAccountUserId": "11111111-1111-4111-8111-111111111111",
"config": {
"model": "configured-model",
"maxTicks": 24
},
"policy": {
"maxTicks": 24,
"toolNames": [
"ref_search"
]
},
"createdBy": "44444444-4444-4444-8444-444444444444",
"createdAt": "2026-06-13T10:00:00.000Z",
"lastUpdateAt": "2026-06-13T10:15:00.000Z",
"lastUpdateBy": "44444444-4444-4444-8444-444444444444",
"version": 3,
"desc": "Summarizes release status and creates operator updates.",
"ownerId": "22222222-2222-4222-8222-222222222222",
"ownerType": "USER",
"rootStorageEntryId": "33333333-3333-4333-8333-333333333333",
"metadata": {
"team": "operations"
},
"avatar": "https://storage.example/avatar.png",
"summary": {
"activeRunCount": 1,
"queuedInboxCount": 3
}
}