List Namespaces

List namespaces, optionally filtered by name or ID. Results are paginated.

Use namespace_id for multiple IDs. namespace_ids is deprecated. For a namespace upgraded from an earlier release, skipped lists the actors the move into its volume group could not move, by ID, name and key, and skipped_count counts them; both are empty for every other namespace and are removed with the backfill in 3.1. skipped lists at most 1,000 actors, so skipped_count can be higher.

GET https://rivet.example.com/namespaces

Examples

curl "https://rivet.example.com/namespaces" \
  -H "Authorization: Bearer $RIVET_TOKEN"

const endpoint = "https://api.rivet.dev";
const token = process.env.RIVET_TOKEN ?? "";

const response = await fetch(`${endpoint}/namespaces`, {
	headers: { Authorization: `Bearer ${token}` },
});
const { namespaces, pagination } = await response.json();
console.log(namespaces, pagination.cursor);

export {};

Authentication

Send your namespace token as a bearer token in the Authorization header. Every control plane request also requires the namespace query parameter. See Authentication.

Query Parameters

Responses

200

Matching namespaces and a cursor for the next page.

{
  "namespaces": [
    {
      "name": "my-namespace",
      "create_ts": 1700000000000,
      "status": "creating",
      "forked_from": null,
      "archived_ts": null,
      "skipped": [],
      "skipped_count": 0
    }
  ],
  "pagination": {
    "cursor": null
  }
}

400

namespace.invalid: limit is outside 1 to 100. envoy.invalid_namespace_name: name or cursor is not a valid namespace name. A query string with any other parameter, or a limit that is not a non-negative integer, is rejected with a plain-text 400.

{
  "group": "namespace",
  "code": "invalid",
  "message": "Namespace list limit must be between 1 and 100."
}

401

auth.invalid_token: the request carries no token, or the token is not valid. auth.token_expired: the token has expired.

{
  "group": "auth",
  "code": "invalid_token",
  "message": "Authentication token is invalid."
}

403

auth.insufficient_permissions: the token’s grants do not cover this request. Namespace management is only available to the admin token.

{
  "group": "auth",
  "code": "insufficient_permissions",
  "message": "Insufficient permissions to access this resource."
}

500

core.internal_error: an unexpected failure. Details are only logged on the server.

{
  "group": "core",
  "code": "internal_error",
  "message": "An internal error occurred"
}

503

auth.verification_unavailable: token verification keys are temporarily unavailable. Retry the request.

{
  "group": "auth",
  "code": "verification_unavailable",
  "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request."
}