AGNTDocs

Workspace

Workspace

Each user's cloud computer, with a browser, desktop and shell, that the assistant uses for sites and apps without an API. When the assistant needs the user, for example to sign in, it opens a handoff, and the user takes over the live browser and hands it back.

POST/workspace/cleanup

Clean up the workspace

Clears temporary files and download caches on the user's workspace without touching the user's own files. With `scope: "sites"`, it also removes local working copies of the user's sites, which are restored when next needed.

Request body

scopeenumcachesites

Responses

200Cleanup result
ok reqboolean
scopestring
403No end user on the call

Request

curl 'https://api.agnt.ai/workspace/cleanup' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "cache"
}'

Response

{
  "ok": true
}
GET/workspace/handoff/active

List open handoffs

Returns every open request for the user to take over their workspace, oldest first, plus the newest on its own.

Responses

200Open handoffs
ok reqboolean
handoffs reqobject[]
idstring
taskIdstring | nullTask waiting on it; null for a session the user opened
actionTypeenumloginpaymentform_fillmfaother
promptstringWhat the assistant asks the user to do
targetUrlstring
screenshotUrlstring
statusenumpendingstartingreadyactive
expiresAtstring
createdAtstring
handoffobject | nullNewest open handoff
403No end user on the call

Request

curl 'https://api.agnt.ai/workspace/handoff/active' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "handoffs": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "taskId": "6660c4a1f2e3b7d8a9c01234",
      "actionType": "login",
      "prompt": "prompt"
    }
  ]
}
POST/workspace/handoff/launch

Open the workspace

Starts a handoff in which the user uses their workspace directly. The workspace starts in the background: poll the open handoffs until this one is ready, then start the live session.

Responses

200Started
ok reqboolean
handoffId reqstring
status reqenumstarting
403No end user on the call

Request

curl 'https://api.agnt.ai/workspace/handoff/launch' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "handoffId": "6660c4a1f2e3b7d8a9c01234",
  "status": "starting"
}
POST/workspace/handoff/{handoffId}/session

Start a live session

Starts the computer if needed and returns a one-time link to a live view of it. The assistant cannot use the computer while the user has it. Each call issues a new link.

Path parameters

handoffId reqstring

Request body

Responses

200Session link
ok reqboolean
sessionUrl reqstringOne-time link to the live session
controlobject
generationinteger
handoffIdstring
operatorenumuseragentunknown
400Handoff is no longer open
403Not this user's handoff
404Handoff not found
409Control of the computer changed; refresh and retry

Request

curl 'https://api.agnt.ai/workspace/handoff/<handoffId>/session' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "ok": true,
  "sessionUrl": "https://harborview.co"
}
POST/workspace/handoff/{handoffId}/complete

Complete a handoff

Tells the assistant the user finished the step. Control returns to the assistant, and the waiting task continues.

Path parameters

handoffId reqstring

Request body

Responses

200Completed
ok reqboolean
taskIdstring | null
400Session is not open
403Not this user's handoff
404Session expired or not found
409Control of the computer changed; refresh and retry

Request

curl 'https://api.agnt.ai/workspace/handoff/<handoffId>/complete' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "ok": true
}
POST/workspace/handoff/{handoffId}/defer

Defer a handoff

Closes the request because the user cannot do the step now. The computer returns to the assistant, which receives the message and suggested time and decides when to ask again.

Path parameters

handoffId reqstring

Request body

message reqstringMessage to the assistant, such as "after 5pm"
deferMinutesintegerOptional: minutes from now to try again

Responses

200Deferred
ok reqboolean
deferredUntilstring | null
400Invalid body or handoff already closed
403Not this user's handoff
404Handoff not found
409Control of the computer changed; refresh and retry

Request

curl 'https://api.agnt.ai/workspace/handoff/<handoffId>/defer' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Prefers morning meetings."
}'

Response

{
  "ok": true
}
POST/workspace/handoff/{handoffId}/decline

Decline a handoff

Closes the request because the user refuses. The computer returns to the assistant, which finds another way or reports that it cannot continue. It does not ask again for this task for a while.

Path parameters

handoffId reqstring

Request body

Responses

200Declined
ok reqboolean
taskIdstring | null
400Handoff already closed
403Not this user's handoff
404Handoff not found
409Control of the computer changed; refresh and retry

Request

curl 'https://api.agnt.ai/workspace/handoff/<handoffId>/decline' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "ok": true
}
POST/workspace/handoff/resolve

Resolve handoffs

Ends the user's turn and reports, for each request, whether it was done, refused or left for later. Completed requests let their tasks continue; pending ones stay open. Ids that are not the user's are skipped.

Request body

items reqobject[]
handoffId reqstring
outcome reqenumcompleteddeclinedpending
notestring

Responses

200Closed requests
ok reqboolean
resolved reqobject[]
handoffIdstring
outcomeenumcompleteddeclined
400Invalid body
409Control of the computer changed; refresh and retry

Request

curl 'https://api.agnt.ai/workspace/handoff/resolve' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "handoffId": "6660c4a1f2e3b7d8a9c01234",
      "outcome": "completed"
    }
  ]
}'

Response

{
  "ok": true,
  "resolved": [
    {
      "handoffId": "6660c4a1f2e3b7d8a9c01234",
      "outcome": "completed"
    }
  ]
}
GET/workspace/profile

Retrieve workspace usage

Returns rolling usage figures for the user's workspace. `profile` is `null` until the workspace has run.

Responses

200Profile
okboolean
profileobject | null
lastActiveAtstring | null
updatedAtstring | null
peakMemoryBytesnumberHighest memory use in the last 24 hours
avgMemoryBytesnumber
memoryLimitBytesnumber
currentDiskBytesnumber
diskQuotaBytesnumber
avgCpuLoadAvgnumber
totalActiveMinutesnumber
topMcpSlugsstring[]Most-used connected tool servers

Request

curl 'https://api.agnt.ai/workspace/profile' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "profile": {
    "lastActiveAt": "2026-10-15T14:30:00Z",
    "updatedAt": "2026-10-15T14:30:00Z",
    "peakMemoryBytes": 1,
    "avgMemoryBytes": 1
  }
}
GET/workspace/snapshots

List workspace usage snapshots

Returns point-in-time usage, oldest first, taken at most every 5 minutes while the computer runs and kept for 30 days.

Query parameters

limitinteger

Responses

200Snapshots
okboolean
snapshotsobject[]
timestampstring
memoryUsedBytesnumber | null
memoryTotalBytesnumber | null
diskUsedBytesnumber | null
diskQuotaBytesnumber | null
cpuLoadAvgnumber | nullOne-minute load average
activeMcpSlugsstring[]Connected tool servers running
containerUptimenumber | nullSeconds

Request

curl 'https://api.agnt.ai/workspace/snapshots' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "snapshots": [
    {
      "timestamp": "2026-10-15T14:30:00Z",
      "memoryUsedBytes": 1,
      "memoryTotalBytes": 1,
      "diskUsedBytes": 1
    }
  ]
}
GET/workspace/watch

Watch a task's browser

Returns a still image of the browser tab the assistant is using for one of the user's tasks. It does not take control or start the computer; poll it for a live view. Returns `available: false` when there is nothing to show.

Query parameters

taskId reqstring

Responses

200Frame, or available false
availableboolean
reasonenumSet when available is falsewatch_unavailable
taskIdstring
capturedAtstring
widthinteger
heightinteger
pngBase64stringPNG image, base64
sequenceintegerIncreases with each new frame
400Invalid taskId

Request

curl 'https://api.agnt.ai/workspace/watch?taskId=' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "available": true,
  "reason": "watch_unavailable",
  "taskId": "6660c4a1f2e3b7d8a9c01234",
  "capturedAt": "2026-10-15T14:30:00Z"
}