desks

Embed

<a href="https://forumulate.com/p/gaiadesk/docs/ref-desks"><img src="https://forumulate.com/api/public/orgs/gaiadesk/spaces/docs/pages/a90ba911-f4c8-449d-83fa-80a719d90c9c/social-card.svg?v=3e7ae33eec8b" alt="desks" width="600" height="315"></a>

GEThttps://api.gaiadesk.net/v1/desksScope desks:read

List the desks on the account and its team.

Every desk the caller's account or team has registered: online or not, its name, OS and version, when it was last seen, and for an offline desk since when and why (the reach log). Online desks first.

Code samples

cURL

curl -X GET "https://api.gaiadesk.net/v1/desks" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 The desks.

Example

{
  "devices": [
    {
      "anytime": true,
      "app_version": "string",
      "desk_id": "string",
      "last_failure": {
        "at": 0,
        "kind": "string",
        "message": "string"
      },
      "last_ok": {
        "at": 0,
        "connect_ms": 0,
        "route": "string",
        "rtt_ms": 0
      },
      "last_seen": 0,
      "name": "string",
      "online": true,
      "os": "string",
      "owner": "string",
      "probe": {
        "connect_ms": 0,
        "dialled": true,
        "error": "string",
        "hostname": "string",
        "kind": "string",
        "ok": true,
        "os": "string",
        "route": "string",
        "rtt_ms": 0
      },
      "reachable": true,
      "signal_idle_secs": 0,
      "sources": [
        "string"
      ],
      "offline_since": 0,
      "offline_reason": "string",
      "offline_reason_text": "string",
      "offline_detail": "string",
      "features": [
        "string"
      ],
      "e2e_pub": "string",
      "e2e_required": true
    }
  ],
  "identity": {
    "account": "string",
    "source": "string"
  },
  "notes": [
    "string"
  ],
  "sources": [
    "string"
  ]
}

Schema

devicesApiDesk[]required

Show child parameters

anytimeboolean

Its owner's app says it starts with the computer and works at the lock screen (None: not said).

app_versionstring

The GaiaDesk version it last registered with (the server's list only).

desk_idstringrequired

last_failureReachFailure

The last one that failed, and why.

Show child parameters

atintegerrequired

kindstringrequired

A stable key: a [crate::dial_stage::kind] or an error kind.

messagestringrequired

One line, as the CLI said it.

last_okReachSuccess

The last connect from this machine that worked (cli_reach).

Show child parameters

atintegerrequired

Seconds since the epoch.

connect_msinteger

How long the connect took, ms.

routestringrequired

LAN, Mesh, the GaiaDesk server.

rtt_msinteger

A data-plane round trip measured on it (devices --probe), ms.

last_seeninteger

Seconds since the epoch.

namestring

onlinebooleanrequired

osstring

ownerstringrequired

Whose desk: "you", a teammate's email, or unknown.

probeProbeResult

Show child parameters

connect_msinteger

dialledbooleanrequired

Whether it was dialled at all (no credential for it: not).

errorstring

hostnamestring

kindstring

Why not: a [crate::dial_stage::kind], an error kind, agent_not_answering or no_credential.

okbooleanrequired

Connected AND its agent answered a round trip.

osstring

routestring

rtt_msinteger

reachableboolean

Reachable NOW: only with --probe (else null).

signal_idle_secsinteger

Seconds since the server last heard the desk's socket (online desks, a server that says). Long silence on an "online" desk: a dead socket.

sourcesstring[]required

Where this desk was found: "account", "team", "lan" (seen on this network just now), "pinned" (paired over the LAN before, not seen on this network now), "mesh", "recent".

offline_sinceinteger

Unix seconds it went offline (offline desks the reach log has a word on).

offline_reasonstring

closed, silent, error, updating, server-restart, id-changed, unknown.

offline_reason_textstring

offline_detailstring

id-changed: the id it answers to now (now 555000111).

featuresstring[]

What it takes now, while online: desk_op (desk operations), desk_op_e2e (end-to-end encrypted ones).

e2e_pubstring

Its end-to-end X25519 public key (base64url, 32 bytes) while online and able to open sealed operations; null otherwise.

e2e_requiredboolean

Its owner requires end-to-end encryption for API commands (a plaintext one answers 409 e2e_required).

identityobjectrequired

Who this machine is signed in as, and where that came from — the account whose desks the server listed.

Show child parameters

accountstring

The account's email (null: not signed in, or the server could not say).

sourcestringrequired

app, login, token or none; from the hosted API (GET /v1/desks), api_key or session.

notesstring[]required

sourcesstring[]required

Which sources answered: server, lan, mesh, recent.

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.

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

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

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

Same as 401 · GET /desks

429 Over this key's rate limit (refused, rate_limited).

Same as 401 · GET /desks

Headers

Retry-Afterinteger

Seconds to wait before trying again.

RateLimit-Limitinteger

Requests allowed per window for this key.

RateLimit-Remaininginteger

Requests left in the current window.

RateLimit-Resetinteger

Seconds until the window resets.

GEThttps://api.gaiadesk.net/v1/desks/{id}Scope desks:read

One desk, with its reachability and wake hints.

Parameters

idstringpathrequired

The desk's nine-digit id.

Code samples

cURL

curl -X GET "https://api.gaiadesk.net/v1/desks/{id}" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 The desk.

Example

{
  "anytime": true,
  "app_version": "string",
  "desk_id": "string",
  "last_failure": {
    "at": 0,
    "kind": "string",
    "message": "string"
  },
  "last_ok": {
    "at": 0,
    "connect_ms": 0,
    "route": "string",
    "rtt_ms": 0
  },
  "last_seen": 0,
  "name": "string",
  "online": true,
  "os": "string",
  "owner": "string",
  "probe": {
    "connect_ms": 0,
    "dialled": true,
    "error": "string",
    "hostname": "string",
    "kind": "string",
    "ok": true,
    "os": "string",
    "route": "string",
    "rtt_ms": 0
  },
  "reachable": true,
  "signal_idle_secs": 0,
  "sources": [
    "string"
  ],
  "offline_since": 0,
  "offline_reason": "string",
  "offline_reason_text": "string",
  "offline_detail": "string",
  "features": [
    "string"
  ],
  "e2e_pub": "string",
  "e2e_required": true,
  "wake": {
    "doorbell_sockets": 0,
    "lan_wake": true
  }
}

Schema

anytimeboolean

Its owner's app says it starts with the computer and works at the lock screen (None: not said).

app_versionstring

The GaiaDesk version it last registered with (the server's list only).

desk_idstringrequired

last_failureReachFailure

The last one that failed, and why.

Show child parameters

atintegerrequired

kindstringrequired

A stable key: a [crate::dial_stage::kind] or an error kind.

messagestringrequired

One line, as the CLI said it.

last_okReachSuccess

The last connect from this machine that worked (cli_reach).

Show child parameters

atintegerrequired

Seconds since the epoch.

connect_msinteger

How long the connect took, ms.

routestringrequired

LAN, Mesh, the GaiaDesk server.

rtt_msinteger

A data-plane round trip measured on it (devices --probe), ms.

last_seeninteger

Seconds since the epoch.

namestring

onlinebooleanrequired

osstring

ownerstringrequired

Whose desk: "you", a teammate's email, or unknown.

probeProbeResult

Show child parameters

connect_msinteger

dialledbooleanrequired

Whether it was dialled at all (no credential for it: not).

errorstring

hostnamestring

kindstring

Why not: a [crate::dial_stage::kind], an error kind, agent_not_answering or no_credential.

okbooleanrequired

Connected AND its agent answered a round trip.

osstring

routestring

rtt_msinteger

reachableboolean

Reachable NOW: only with --probe (else null).

signal_idle_secsinteger

Seconds since the server last heard the desk's socket (online desks, a server that says). Long silence on an "online" desk: a dead socket.

sourcesstring[]required

Where this desk was found: "account", "team", "lan" (seen on this network just now), "pinned" (paired over the LAN before, not seen on this network now), "mesh", "recent".

offline_sinceinteger

Unix seconds it went offline (offline desks the reach log has a word on).

offline_reasonstring

closed, silent, error, updating, server-restart, id-changed, unknown.

offline_reason_textstring

offline_detailstring

id-changed: the id it answers to now (now 555000111).

featuresstring[]

What it takes now, while online: desk_op (desk operations), desk_op_e2e (end-to-end encrypted ones).

e2e_pubstring

Its end-to-end X25519 public key (base64url, 32 bytes) while online and able to open sealed operations; null otherwise.

e2e_requiredboolean

Its owner requires end-to-end encryption for API commands (a plaintext one answers 409 e2e_required).

wakeobjectrequired

How this desk could be woken now.

Show child parameters

doorbell_socketsintegerrequired

Doorbell sockets the desk holds on the wake listener (a sleeping Mac's).

lan_wakebooleanrequired

The desk said how it can be woken on its LAN (Wake-on-LAN by an awake sibling).

Headers

X-Request-Idstring

This request's id (req_…), also in every error body. Quote it to support.

400 The request is malformed (usage).

Same as 401 · GET /desks

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

Same as 401 · GET /desks

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

Same as 401 · GET /desks

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

Same as 401 · GET /desks

429 Over this key's rate limit (refused, rate_limited).

Same as 401 · GET /desks

Headers

Retry-Afterinteger

Seconds to wait before trying again.

RateLimit-Limitinteger

Requests allowed per window for this key.

RateLimit-Remaininginteger

Requests left in the current window.

RateLimit-Resetinteger

Seconds until the window resets.

GEThttps://api.gaiadesk.net/v1/desks/{id}/reachScope desks:read

The desk's online and offline history (the reach log, 30 days).

Parameters

idstringpathrequired

The desk's nine-digit id.

sinceintegerquery

Unix seconds. Default seven days ago; the log keeps thirty.

limitintegerquery

At most this many transitions, newest first (default 200, at most 1000).

Code samples

cURL

curl -X GET "https://api.gaiadesk.net/v1/desks/{id}/reach" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 The transitions, newest first.

Example

{
  "desk_id": "string",
  "since": 0,
  "events": [
    {
      "at": 0,
      "online": true,
      "reason": "string",
      "reason_text": "string",
      "detail": "string",
      "version": "string"
    }
  ]
}

Schema

desk_idstringrequired

sinceintegerrequired

eventsApiReachEvent[]required

Show child parameters

atintegerrequired

onlinebooleanrequired

reasonstringrequired

reason_textstringrequired

detailstring

versionstring

Headers

X-Request-Idstring

This request's id (req_…), also in every error body. Quote it to support.

400 The request is malformed (usage).

Same as 401 · GET /desks

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

Same as 401 · GET /desks

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

Same as 401 · GET /desks

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

Same as 401 · GET /desks

429 Over this key's rate limit (refused, rate_limited).

Same as 401 · GET /desks

Headers

Retry-Afterinteger

Seconds to wait before trying again.

RateLimit-Limitinteger

Requests allowed per window for this key.

RateLimit-Remaininginteger

Requests left in the current window.

RateLimit-Resetinteger

Seconds until the window resets.

Next part

Updated Nov 3, 2026

Was this page helpful?