List your Organizations

View .md OpenAPI spec Open in Claude Open in ChatGPT

GET

/v1/organizations

const url = 'https://app.caprid.com/v1/organizations';
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 \
  --header 'Authorization: Bearer <token>'

Every Organization your session is a Member of, with your role in each, oldest membership first. An API key lists only its own Organization, with no role.

Authorizations

Responses

200

The Organizations.

application/json

Array<object>

A customer of Switchboard. It owns its Namespaces, and the API keys, Nodes and enrollments that serve them. Its Members manage all of it.

object

required

Identifies the Organization in routes. It never changes.

integer

name

required

For display. Any Member can change it.

string

role

Your role in it. Absent for an API key, which has none.

string

Allowed values: owner member

created_at

required

integer

trial_expires_at

When a Trial Organization lapses, so its Agent knows how long it has to get a person to claim it. Absent for every other Organization.

integer

Example

[
  {
    "id": 4,
    "name": "Acme",
    "role": "owner",
    "trial_expires_at": 1760604800
  }
]

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 on every route with the token of an Agent that has nothing to act in. An Agent whose person hasn’t signed up gets this until they sign up at /app/, and its next request after that acts as their new Account. An Agent nobody has claimed gets this once its trial lapses, because a registration gets one trial. It can register again to start a new one, or a person can claim it so it acts as their Account.

application/json

object

error

required

string

Examples

The person who claimed the Agent hasn't signed up

{
  "error": "the person who claimed this Agent has no Switchboard Account: once they sign up at /app/, the Agent acts as their Account"
}

The Agent's trial has lapsed

{
  "error": "this Agent's trial is over: register again to start a new one, or have a person with a Switchboard Account claim this Agent"
}