Namespaces

List Namespaces

List namespaces in name order, or look up one namespace by name. Results are paginated.

name returns zero or one namespace and ignores limit and cursor. Any other query parameter, including namespace, is rejected.

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

Requires the admin token, sent as a bearer token in the Authorization header. Namespace tokens are rejected. See Authentication.

Query Parameters

Name	Type	Required	Description
`name`	`string`	No	Only return the namespace with this name.
`cursor`	`string`	No	Pagination cursor. Pass the `pagination.cursor` value from the previous response to fetch the next page.
`limit`	`integer`	No	Maximum number of results to return, from 1 to 100. Defaults to 100.

Responses

200

Matching namespaces and a cursor for the next page.

Field	Type	Description
`namespaces`	`object[]`
`namespaces[].name`	`string`	Namespace name.
`namespaces[].create_ts`	`integer`	When the namespace was created, in Unix milliseconds.
`pagination`	`object`
`pagination.cursor`	`string \| null`	Cursor for the next page, or `null` when there are no more results.

{
  "namespaces": [
    {
      "name": "my-namespace",
      "create_ts": 1700000000000
    }
  ],
  "pagination": {
    "cursor": null
  }
}

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.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "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.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "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.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "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.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

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

503

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

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing 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."
}