List your Nodes

View .md OpenAPI spec Open in Claude Open in ChatGPT

GET

/v1/organizations/{id}/nodes

const url = 'https://app.caprid.com/v1/organizations/4/nodes';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://app.caprid.com/v1/organizations/4/nodes \
  --header 'Authorization: Bearer <token>'

Every Node the Organization has enrolled, running or not.

Authorizations

Parameters

Path Parameters

required

integer

The Organization’s id, from GET /v1/organizations.

Example

Responses

200

The Nodes.

application/json

Array<object>

object

url

required

The URL the Node’s peers dial, as it was enrolled.

string

canonical

required

The URL in the normalized form Switchboard uses to tell Nodes apart.

string

source

required

string

Allowed values: poll static

account

required

The Organization’s oldest Namespace, kept from before Organizations. The Node belongs to the whole Organization and carries all of its Namespaces. null when the Organization has no Namespaces.

string | null

region

required

string

gateway

required

boolean

client_url

The Client URL, which is where Clients, such as a player page, reach this relay when that isn’t url. On a private network, url is often a name no Client can resolve, so whatever hands relay addresses to Clients reads this instead. It is fixed when the Node is enrolled, and omitted when the Node has none. Relays never see it, because peer discovery hands out only url.

string

enrolled

required

Whether the Node came from a Relay enrollment token, so its relay has a Node key.

boolean

first_seen_at

required

integer

last_seen_at

required

When its relay last polled, or when it enrolled if it hasn’t polled since.

integer

live

required

Whether its relay has polled in the last 90 seconds.

boolean

Example

[
  {
    "source": "poll"
  }
]

401

No valid credential. Missing, expired and revoked credentials all get the same response, and so does an API key whose trial has lapsed. An Agent token from before a claim gets a 401 too, once the claim has made the trial a person’s, with a message saying to get a new token.

application/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

Headers

WWW-Authenticate

string

Example

Bearer realm="switchboard"

403

Sent with an API key limited to some Namespaces, to a Namespace outside its limit, or to a route that acts on the Organization as a whole. A limited key can never create API keys.

application/json

object

error

required

string

Example

{
  "error": "this API key is limited to the Namespaces acme-staging, and acme isn't one of them"
}

404

No such thing, or not yours. Another customer’s Organization or Namespace is a 404 too, so nobody can tell which ones exist.

application/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}