Computers

Get computer usage

GET /v1/computer-usage · getComputerUsage

Read usage for the authenticated account with cloud access. Uses the same account permissions as computer reads. Account owner and payer headers are ignored; job credentials are refused. Accepted requests and observed results are separate events. Missing provider seconds remain unknown. Allocation allowances are operator limits, not customer charges; retail pricing is not enabled.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — Account computer usage result.

Type: AppComputerUsage

Errors

Example

curl 'https://api.openagents.com/v1/computer-usage' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

List computers

GET /v1/computers · listComputers

Account-owned cloud computers. Accepts live app sessions/sign-in keys or account-bound API keys with accounts scope. Cloud operations remain restricted to accounts with cloud access. Acceptance is not readiness or completion; poll the computer. Internal owner headers and service tokens are not public credentials.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The requested computer result.

Type: AppComputerList

Errors

Example

curl 'https://api.openagents.com/v1/computers' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::list

Create computer

POST /v1/computers · createComputer

Account-owned cloud computers. Accepts live app sessions/sign-in keys or account-bound API keys with accounts scope. Cloud operations remain restricted to accounts with cloud access. Acceptance is not readiness or completion; poll the computer. Internal owner headers and service tokens are not public credentials.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/json

Type: AppCreateComputer

Response

200 — The requested computer result.

Type: AppComputer

202 — Accepted intent; poll the same resource until its observed state confirms completion. A response or polling timeout does not cancel work.

Type: AppComputer

Errors

Example

curl -X POST 'https://api.openagents.com/v1/computers' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "size": "small"
}'

In the Rust SDK

• Computers::create

Get computer capabilities

GET /v1/computers/capabilities · getComputerCapabilities

Account-owned cloud computers. Accepts live app sessions/sign-in keys or account-bound API keys with accounts scope. Cloud operations remain restricted to accounts with cloud access. Acceptance is not readiness or completion; poll the computer. Internal owner headers and service tokens are not public credentials.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Response

200 — The requested computer result.

Type: AppComputerCapabilities

Errors

Example

curl 'https://api.openagents.com/v1/computers/capabilities' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::capabilities

Remove computer named capabilities

DELETE /v1/computers/capabilities · removeComputerNamedCapabilities

Remove a computer named capabilities from your list. Its files and synced chats stay. Cloud access is not required.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Response

204 — The computer name was removed from your list.

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/computers/capabilities' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Get computer

GET /v1/computers/{id} · getComputer

Account-owned cloud computers. Accepts live app sessions/sign-in keys or account-bound API keys with accounts scope. Cloud operations remain restricted to accounts with cloud access. Acceptance is not readiness or completion; poll the computer. Internal owner headers and service tokens are not public credentials.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The requested computer result.

Type: AppComputer

Errors

Example

curl 'https://api.openagents.com/v1/computers/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::get

Delete computer

DELETE /v1/computers/{id} · deleteComputer

Cloud IDs request deletion (202); names of your own computers are removed from your list (204). Read a cloud computer to check when deletion is finished.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The requested computer result.

Type: AppComputer

202 — Accepted intent; poll the same resource until its observed state confirms completion. A response or polling timeout does not cancel work.

Type: AppComputer

204 — The computer name was removed from your list. Its files and synced chats stay.

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/computers/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::delete

Create computer command

POST /v1/computers/{id}/commands · createComputerCommand

Account-authenticated Boat commands. Creation queues execution with output capture already configured. Attach reads saved output and never starts or cancels work. Poll from the returned byte offsets; each request checks current authority. No URL tokens. Unknown execution is never replayed. Output expires seven days after creation; each stream retains its first 256 KiB and reports discarded bytes with gaps. Cancellation is intent until an observed exit. Origin, if supplied, must match this deployment.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/json

Type: AppCreateCommand

Response

200 — The command or saved output.

Type: AppCommand

202 — Accepted intent; poll the same resource until its observed state confirms completion. A response or polling timeout does not cancel work.

Type: AppCommand

Errors

Example

curl -X POST 'https://api.openagents.com/v1/computers/{id}/commands' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "command": "sha256sum input.bin",
  "timeout_seconds": 30
}'

In the Rust SDK

• Computers::execute

Get computer command

GET /v1/computers/{id}/commands/{command} · getComputerCommand

Account-authenticated Boat commands. Creation queues execution with output capture already configured. Attach reads saved output and never starts or cancels work. Poll from the returned byte offsets; each request checks current authority. No URL tokens. Unknown execution is never replayed. Output expires seven days after creation; each stream retains its first 256 KiB and reports discarded bytes with gaps. Cancellation is intent until an observed exit. Origin, if supplied, must match this deployment.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The command or saved output.

Type: AppCommand

Errors

Example

curl 'https://api.openagents.com/v1/computers/{id}/commands/{command}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::get_command

Cancel computer command

POST /v1/computers/{id}/commands/{command}/cancel · cancelComputerCommand

Account-authenticated Boat commands. Creation queues execution with output capture already configured. Attach reads saved output and never starts or cancels work. Poll from the returned byte offsets; each request checks current authority. No URL tokens. Unknown execution is never replayed. Output expires seven days after creation; each stream retains its first 256 KiB and reports discarded bytes with gaps. Cancellation is intent until an observed exit. Origin, if supplied, must match this deployment.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The command or saved output.

Type: AppCommand

202 — Accepted intent; poll the same resource until its observed state confirms completion. A response or polling timeout does not cancel work.

Type: AppCommand

Errors

Example

curl -X POST 'https://api.openagents.com/v1/computers/{id}/commands/{command}/cancel' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::cancel_command

Attach computer command

GET /v1/computers/{id}/commands/{command}/output · attachComputerCommand

Account-authenticated Boat commands. Creation queues execution with output capture already configured. Attach reads saved output and never starts or cancels work. Poll from the returned byte offsets; each request checks current authority. No URL tokens. Unknown execution is never replayed. Output expires seven days after creation; each stream retains its first 256 KiB and reports discarded bytes with gaps. Cancellation is intent until an observed exit. Origin, if supplied, must match this deployment.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The command or saved output.

Type: AppCommandOutput

Errors

Example

curl 'https://api.openagents.com/v1/computers/{id}/commands/{command}/output' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• OutputReader::next_page

Prepare computer credential reference

POST /v1/computers/{id}/credential-references · prepareComputerCredentialReference

Optional host-side credentials. Requires a supported network profile and an authorized source connection. Credential values and cloud paths never appear in this contract. Prepare all references before sending the command with command_key. Pass oa-ref:REFERENCE_UUID as the client API key or Git HTTPS password. The proxy replaces this non-secret marker only for an authorized matching request.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/json

Type: AppPrepareComputerCredentialReference

Response

201 — Done

Type: AppComputerCredentialReference

Errors

Example

curl -X POST 'https://api.openagents.com/v1/computers/{id}/credential-references' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "source": "00000000-0000-0000-0000-000000000001",
  "rule": "messages",
  "command_key": "command-example",
  "idempotency_key": "credential-example",
  "ttl_seconds": 300
}'

In the Rust SDK

• Computers::prepare_credential

Get computer credential reference

GET /v1/computers/{id}/credential-references/{reference} · getComputerCredentialReference

Optional host-side credentials. Requires a supported network profile and an authorized source connection. Credential values and cloud paths never appear in this contract. Prepare all references before sending the command with command_key. Pass oa-ref:REFERENCE_UUID as the client API key or Git HTTPS password. The proxy replaces this non-secret marker only for an authorized matching request.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — Done

Type: AppComputerCredentialReference

Errors

Example

curl 'https://api.openagents.com/v1/computers/{id}/credential-references/{reference}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::get_credential

Revoke computer credential reference

DELETE /v1/computers/{id}/credential-references/{reference} · revokeComputerCredentialReference

Optional host-side credentials. Requires a supported network profile and an authorized source connection. Credential values and cloud paths never appear in this contract. Prepare all references before sending the command with command_key. Pass oa-ref:REFERENCE_UUID as the client API key or Git HTTPS password. The proxy replaces this non-secret marker only for an authorized matching request.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

204 — Credential access has ended.

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/computers/{id}/credential-references/{reference}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::revoke_credential

Read a workspace file

GET /v1/computers/{id}/files · readComputerFile

Requires an awake computer; never wakes or allocates. Returns a bounded complete read after taking a read lease and checking file size and modification metadata. Files open for writing return409; files that cannot take a lease are unsupported. Concurrent changes can return409. File mode is not altered.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — Complete binary file; X-Content-SHA256 and ETag identify the returned bytes.

Content type: application/octet-stream

Type: string (binary)

Errors

Example

curl 'https://api.openagents.com/v1/computers/{id}/files?path=...' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::read_file

Upload a workspace file

PUT /v1/computers/{id}/files · writeComputerFile

Requires awake computer, Content-Length, and SHA256. Validates the full body before writing. Publishes a same-directory temporary file by atomic rename; partial or mismatched uploads leave the previous file intact. Missing parents return404. Maximum4MiB, two transfers per instance,60second upload and60second execution bounds. A lost response can leave the result uncertain: read and compare SHA256 before retrying. Files stay on this computer's disk and are not shared artifacts.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Request body

Content type: application/octet-stream

Type: string (binary)

Response

200 — The complete upload was checked and atomically published with mode0600.

Type: AppComputerFileInfo

Errors

Example

curl -X PUT 'https://api.openagents.com/v1/computers/{id}/files?path=...' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'X-Content-SHA256: ...' \
  -H 'Content-Length: ...' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @file

In the Rust SDK

• Computers::write_file

Stop computer

POST /v1/computers/{id}/stop · stopComputer

Account-owned cloud computers. Accepts live app sessions/sign-in keys or account-bound API keys with accounts scope. Cloud operations remain restricted to accounts with cloud access. Acceptance is not readiness or completion; poll the computer. Internal owner headers and service tokens are not public credentials.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The requested computer result.

Type: AppComputer

202 — Accepted intent; poll the same resource until its observed state confirms completion. A response or polling timeout does not cancel work.

Type: AppComputer

Errors

Example

curl -X POST 'https://api.openagents.com/v1/computers/{id}/stop' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::stop

Wake computer

POST /v1/computers/{id}/wake · wakeComputer

Account-owned cloud computers. Accepts live app sessions/sign-in keys or account-bound API keys with accounts scope. Cloud operations remain restricted to accounts with cloud access. Acceptance is not readiness or completion; poll the computer. Internal owner headers and service tokens are not public credentials.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Response

200 — The requested computer result.

Type: AppComputer

202 — Accepted intent; poll the same resource until its observed state confirms completion. A response or polling timeout does not cancel work.

Type: AppComputer

Errors

Example

curl -X POST 'https://api.openagents.com/v1/computers/{id}/wake' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

• Computers::wake