desk-ops

Embed
Preview of the card
<a href="https://forumulate.com/p/gaiadesk/docs/ref-desk-ops"><img src="https://forumulate.com/api/public/orgs/gaiadesk/spaces/docs/pages/296a123f-0d4f-4dec-8a90-f657e63dae10/social-card.svg?v=3e7ae33eec8b" alt="desk-ops" width="600" height="315"></a>
GEThttps://api.gaiadesk.net/v1/desks/{id}/statsScope desks:read

CPU, memory, disks and running jobs, as the desk measures them.

Parameters

idstringpathrequired
The desk's nine-digit id.
GaiaDesk-E2Estringheader
End-to-end encrypted: the sealed request (ApiE2eRequest, as base64url of its JSON) in place of a plaintext body or parameters. The answer is then sealed too (ApiE2eAnswer, ApiE2eStreamEvent, ApiE2eFrame). A POST may instead send the body {"e2e": …} (ApiE2eBody). See the "End-to-end encryption" section of docs/api/README.md.
wake_sintegerquery
If the desk is asleep, ring it and wait up to this long (default 60, at most 120).

Code samples

cURL
curl -X GET "https://api.gaiadesk.net/v1/desks/{id}/stats" \
  -H "Authorization: Bearer $GAIADESK_API_KEY" \
  -H "GaiaDesk-E2E: <value>"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 The figures.
Example
{
  "cpu_percent": 0,
  "cpus": 0,
  "desk": "string",
  "disks": [],
  "hostname": "string",
  "jobs_running": 0,
  "load": [
    0
  ],
  "mem_free_mb": 0,
  "mem_total_mb": 0,
  "os": "string",
  "os_version": "",
  "uptime_secs": 0
}
StatsReport
cpu_percentnumberrequired
Busy share of the whole machine, 0–100, over a short sample.
cpusintegerrequired
Logical CPUs.
deskstringrequired
disksDiskStat[]
Every mounted volume worth listing, with its free space.
= []
Show child parameters
free_mbintegerrequired
mountstringrequired
Where it is mounted (/, C:\\).
total_mbintegerrequired
hostnamestringrequired
jobs_runningintegerrequired
Background jobs (gaiadesk-cli run --detach) running now.
loadarray
1, 5 and 15 minute load averages. None where the OS has none (Windows).
mem_free_mbintegerrequired
What programs can still have without swapping ("available").
mem_total_mbintegerrequired
osstringrequired
macos, windows, linux (std::env::consts::OS).
os_versionstring
The OS's own name and version (macOS 15.1, Windows 11 (26100)).
uptime_secsintegerrequired
{
  "cpu_percent": 0,
  "cpus": 0,
  "desk": "string",
  "disks": [],
  "hostname": "string",
  "jobs_running": 0,
  "load": [
    0
  ],
  "mem_free_mb": 0,
  "mem_total_mb": 0,
  "os": "string",
  "os_version": "",
  "uptime_secs": 0
}
ApiE2eAnswer
e2eobjectrequired
Show child parameters
vintegerrequired
eventsApiE2eFrame[]required
Show child parameters
seqintegerrequired
noncestringrequired
ciphertextstringrequired
{
  "e2e": {
    "v": 0,
    "events": [
      {
        "seq": 0,
        "nonce": "string",
        "ciphertext": "string"
      }
    ]
  }
}
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
400 The request is malformed (usage).
Example
{
  "error": {
    "desk": "string",
    "kind": "string",
    "message": "string",
    "reason": "string",
    "request_id": "string",
    "status": 0
  },
  "e2e": {
    "v": 0,
    "events": [
      {
        "seq": 0,
        "nonce": "string",
        "ciphertext": "string"
      }
    ]
  }
}
Schema
errorError & objectrequired
The CLI's error object plus this request's id.
Show child parameters
deskstring
The desk it concerned, when there was one.
kindstringrequired
The six kinds a program branches on. Stable: a new kind would be a breaking change, so match with a wildcard arm anyway.
messagestringrequired
reasonstring
The finer cause: offline, unknown_desk, not_online, network, not_signed_in, timeout, local, …
request_idstringrequired
statusinteger
Only in a held body (GaiaDesk-Held) — the HTTP status this failure would have had, had its 200 not been sent already.
e2eobject
An end-to-end encrypted operation's events; the last opens to the desk's real error (its message here is a placeholder).
Show child parameters
vintegerrequired
eventsApiE2eFrame[]required
Show child parameters
seqintegerrequired
noncestringrequired
ciphertextstringrequired
401 No credential, or one that does not verify (refused, unauthenticated).

Same as 400 · GET /desks/{id}/stats

403 The credential lacks the scope, or may not use this API (refused).

Same as 400 · GET /desks/{id}/stats

404 No such desk or resource visible to the caller (unreachable, unknown_desk).

Same as 400 · GET /desks/{id}/stats

409 The desk is offline (unreachable, with the reach log's reason: silent, closed, …) or could not be woken within wake_s; or it runs a GaiaDesk from before desk operations (protocol, desk_too_old: update GaiaDesk on this desk).

Same as 400 · GET /desks/{id}/stats

429 Over this key's rate limit (rate_limited), or the desk already runs 16 API operations (desk_busy).

Same as 400 · GET /desks/{id}/stats

Headers
Retry-Afterinteger
Seconds to wait before trying again.
502 The desk went away during the operation (connection_lost), or answered something this server cannot read (protocol).

Same as 400 · GET /desks/{id}/stats

503 Desk operations are turned off on this server (unreachable, desk_ops_disabled).

Same as 400 · GET /desks/{id}/stats

default The error envelope.

Same as 400 · GET /desks/{id}/stats

GEThttps://api.gaiadesk.net/v1/desks/{id}/filesScope files

Download a file (the same 256 MB cap).

The file's bytes. A folder answers 400 is_folder; a file larger than 256 MB, 400 too_large. A failure after the first byte breaks the transfer (the connection is reset, never a clean short file) and is the outcome the call's audit event records.

Parameters

idstringpathrequired
The desk's nine-digit id.
pathstringquery
The file on the desk (relative paths start in the desk user's home, or a confined token's directory). Required, except end-to-end encrypted (GaiaDesk-E2E), where it is inside the sealed request and left out here.
GaiaDesk-E2Estringheader
End-to-end encrypted: the sealed request (ApiE2eRequest, as base64url of its JSON) in place of a plaintext body or parameters. The answer is then sealed too (ApiE2eAnswer, ApiE2eStreamEvent, ApiE2eFrame). A POST may instead send the body {"e2e": …} (ApiE2eBody). See the "End-to-end encryption" section of docs/api/README.md.
wake_sintegerquery
If the desk is asleep, ring it and wait up to this long (default 60, at most 120).

Code samples

cURL
curl -X GET "https://api.gaiadesk.net/v1/desks/{id}/files" \
  -H "Authorization: Bearer $GAIADESK_API_KEY" \
  -H "GaiaDesk-E2E: <value>"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 The file's bytes.
application/octet-stream
"string"
application/x-ndjson
{
  "seq": 0,
  "nonce": "string",
  "ciphertext": "string"
}
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
400 The request is malformed (usage).

Same as 400 · GET /desks/{id}/stats

401 No credential, or one that does not verify (refused, unauthenticated).

Same as 400 · GET /desks/{id}/stats

403 The credential lacks the scope, or may not use this API (refused).

Same as 400 · GET /desks/{id}/stats

404 No such desk or resource visible to the caller (unreachable, unknown_desk).

Same as 400 · GET /desks/{id}/stats

409 The desk is offline (unreachable, with the reach log's reason: silent, closed, …) or could not be woken within wake_s; or it runs a GaiaDesk from before desk operations (protocol, desk_too_old: update GaiaDesk on this desk).

Same as 400 · GET /desks/{id}/stats

429 Over this key's rate limit (rate_limited), or the desk already runs 16 API operations (desk_busy).

Same as 400 · GET /desks/{id}/stats

Headers
Retry-Afterinteger
Seconds to wait before trying again.
502 The desk went away during the operation (connection_lost), or answered something this server cannot read (protocol).

Same as 400 · GET /desks/{id}/stats

503 Desk operations are turned off on this server (unreachable, desk_ops_disabled).

Same as 400 · GET /desks/{id}/stats

default The error envelope.

Same as 400 · GET /desks/{id}/stats

PUThttps://api.gaiadesk.net/v1/desks/{id}/filesScope files

Upload a file (streamed; at most 256 MB through the API, larger goes direct).

The body is the file's bytes. path names the file it becomes; a path that names an existing folder receives it under that folder's last name component. Larger than 256 MB answers 413 too_large.

Parameters

idstringpathrequired
The desk's nine-digit id.
pathstringquery
The file on the desk (relative paths start in the desk user's home, or a confined token's directory). Required, except end-to-end encrypted (GaiaDesk-E2E), where it is inside the sealed request and left out here.
GaiaDesk-E2Estringheader
End-to-end encrypted: the sealed request (ApiE2eRequest, as base64url of its JSON) in place of a plaintext body or parameters. The answer is then sealed too (ApiE2eAnswer, ApiE2eStreamEvent, ApiE2eFrame). A POST may instead send the body {"e2e": …} (ApiE2eBody). See the "End-to-end encryption" section of docs/api/README.md.
wake_sintegerquery
If the desk is asleep, ring it and wait up to this long (default 60, at most 120).

Request body

application/octet-stream
"string"

Code samples

cURL
curl -X PUT "https://api.gaiadesk.net/v1/desks/{id}/files" \
  -H "Authorization: Bearer $GAIADESK_API_KEY" \
  -H "GaiaDesk-E2E: <value>" \
  -H "Content-Type: application/octet-stream" \
  -d '"string"'
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 Written.
Example
{
  "bytes": 0,
  "desk": "string",
  "destination": "string",
  "direction": "string",
  "dirs": 0,
  "failed": [
    {
      "message": "string",
      "path": "string"
    }
  ],
  "files": 0,
  "resumed_bytes": 0,
  "seconds": 0
}
CopyResult
bytesintegerrequired
Bytes this run moved.
deskstringrequired
destinationstringrequired
Where it landed (a desk path for an upload, a local one for a download).
directionstringrequired
dirsintegerrequired
failedCopyFailure[]required
Show child parameters
messagestringrequired
pathstringrequired
filesintegerrequired
resumed_bytesintegerrequired
Bytes already there from an earlier, interrupted run.
secondsnumberrequired
{
  "bytes": 0,
  "desk": "string",
  "destination": "string",
  "direction": "string",
  "dirs": 0,
  "failed": [
    {
      "message": "string",
      "path": "string"
    }
  ],
  "files": 0,
  "resumed_bytes": 0,
  "seconds": 0
}
ApiE2eAnswer
e2eobjectrequired
Show child parameters
vintegerrequired
eventsApiE2eFrame[]required
Show child parameters
seqintegerrequired
noncestringrequired
ciphertextstringrequired
{
  "e2e": {
    "v": 0,
    "events": [
      {
        "seq": 0,
        "nonce": "string",
        "ciphertext": "string"
      }
    ]
  }
}
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
400 The request is malformed (usage).

Same as 400 · GET /desks/{id}/stats

401 No credential, or one that does not verify (refused, unauthenticated).

Same as 400 · GET /desks/{id}/stats

403 The credential lacks the scope, or may not use this API (refused).

Same as 400 · GET /desks/{id}/stats

404 No such desk or resource visible to the caller (unreachable, unknown_desk).

Same as 400 · GET /desks/{id}/stats

409 The desk is offline (unreachable, with the reach log's reason: silent, closed, …) or could not be woken within wake_s; or it runs a GaiaDesk from before desk operations (protocol, desk_too_old: update GaiaDesk on this desk).

Same as 400 · GET /desks/{id}/stats

413 The file is larger than the API moves (256 MB; usage, too_large).

Same as 400 · GET /desks/{id}/stats

429 Over this key's rate limit (rate_limited), or the desk already runs 16 API operations (desk_busy).

Same as 400 · GET /desks/{id}/stats

Headers
Retry-Afterinteger
Seconds to wait before trying again.
502 The desk went away during the operation (connection_lost), or answered something this server cannot read (protocol).

Same as 400 · GET /desks/{id}/stats

503 Desk operations are turned off on this server (unreachable, desk_ops_disabled).

Same as 400 · GET /desks/{id}/stats

default The error envelope.

Same as 400 · GET /desks/{id}/stats

Updated