desks

Embed
Preview of the card
<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>
POSThttps://api.gaiadesk.net/v1/desks/{id}/wakeScope desks:write

Ring the desk's doorbell and ask its LAN siblings to Wake-on-LAN it.

Rings every doorbell socket the desk holds and asks up to three awake desks of the same account on its network to send it a Wake-on-LAN packet. With wait_s, waits up to that long for the desk to come online and says whether it woke. A desk that is already online is not rung. A desk with nothing to ring answers 409 unreachable (no_wake_path).

Parameters

idstringpathrequired
The desk's nine-digit id.
Idempotency-Keystringheader
Up to 255 printable ASCII characters. A retry with the same key and the same request within 24 hours gets the first answer again (Idempotent-Replayed: true); the same key with a different request is refused (usage, idempotency_key_reused).

Request body

application/json
wait_sinteger
Wait up to this many seconds for the desk to come online (default 0, at most 90, inside Cloudflare's 100-second request limit).
{
  "wait_s": 0
}

Code samples

cURL
curl -X POST "https://api.gaiadesk.net/v1/desks/{id}/wake" \
  -H "Authorization: Bearer $GAIADESK_API_KEY" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/json" \
  -d '{"wait_s":0}'
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 Rung (and, with wait_s, whether it came online in time).
Example
{
  "desk_id": "string",
  "online": true,
  "woke": true,
  "already_online": true,
  "rang": {
    "doorbell": 0,
    "lan_helpers": 0
  },
  "waited_ms": 0
}
Schema
desk_idstringrequired
onlinebooleanrequired
wokebooleanrequired
It came online after this ring, within wait_s.
already_onlinebooleanrequired
rangobjectrequired
Show child parameters
doorbellintegerrequired
lan_helpersintegerrequired
waited_msintegerrequired
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
Idempotent-Replayedstring
true when this answer is a stored one, replayed for a repeated Idempotency-Key.
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 · POST /desks/{id}/wake

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

Same as 400 · POST /desks/{id}/wake

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

Same as 400 · POST /desks/{id}/wake

409 The desk cannot be reached or woken now (unreachable).

Same as 400 · POST /desks/{id}/wake

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

Same as 400 · POST /desks/{id}/wake

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.
Updated