Computes API

Discover available capacity across the network. Public responses describe what is free — never where to open a socket.

GET/api/registry/computes

Full compute directory. Query filters supported.

Query parameters

Param	Values	Effect
available	1 \| true	Only computes with free capacity / fresh heartbeat
visibility	public \| private \| all	Filter by advertised visibility (default all)

bash

# Anything free right now?
curl -sS 'https://grid-compute.com/api/registry/computes?available=1' | jq '.stats, .computes'

# Public visibility only
curl -sS 'https://grid-compute.com/api/registry/computes?visibility=public' | jq '.computes[].name'

Compute row fields

Field	Meaning
id	Stable row id (nodeId:name)
name	Public compute name (must be activated to list on registry.grid)
nodeId	Opaque operator node identifier
image	Image / workload label (e.g. nginx:alpine) — not a private registry secret
visibility	public or private
class	S \| M \| L
backend	e.g. docker
replicas	Configured replica count
freeSlots	Currently free units of work
status	available \| busy \| offline (heartbeat-derived)
lastSeen	Last announce / heartbeat

example row

{
  "id": "node_macmini:fire",
  "name": "fire",
  "nodeId": "node_macmini",
  "label": "Fire - Spark of Technology",
  "image": "nginx:alpine",
  "visibility": "public",
  "class": "S",
  "backend": "docker",
  "replicas": 4,
  "freeSlots": 4,
  "status": "offline",
  "lastSeen": "2026-07-18T04:18:11.799Z",
  "firstSeen": "2026-07-18T00:12:51.647Z"
}

Announce / heartbeat (write)

POST/api/registry/computes

Host announce. Requires webhook bearer in production. Body includes nodeId + computes[].

bash

curl -sS -X POST https://grid-compute.com/api/registry/computes \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $GRID_WEBHOOK_SECRET" \
  -d '{
    "nodeId": "node_macmini",
    "label": "MacNode",
    "computes": [{
      "name": "fire",
      "image": "nginx:alpine",
      "visibility": "public",
      "class": "S",
      "backend": "docker",
      "replicas": 4,
      "freeSlots": 3
    }]
  }'

Heartbeat freshness defines availability (see availableMs in the GET response). Stale rows flip to offline. The CLI grid ember path performs announces for you when a name is activated.

Builder pattern

Poll available computes, rank by freeSlots / class / region, then negotiate work through your application protocol. Do not treat image labels as pull credentials or assume public Docker Hub access equals permission to run jobs on a peer.