Create Namespace

Create a namespace with a unique name and a display name.

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

Examples

curl -X POST "https://rivet.example.com/namespaces" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "display_name": "My App"
  }'

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

const response = await fetch(`${endpoint}/namespaces`, {
	method: "POST",
	headers: {
		Authorization: `Bearer ${token}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({ name: "my-app", display_name: "My App" }),
});
const { namespace } = await response.json();
console.log(namespace);

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.

Request Body

Content type: application/json.

Responses

200

The newly created namespace.

{
  "namespace": {
    "name": "my-namespace",
    "create_ts": 1700000000000
  }
}

400

envoy.invalid_namespace_name: name is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.

{
  "group": "envoy",
  "code": "invalid_namespace_name",
  "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens."
}

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

409

namespace.name_not_unique: a namespace with this name already exists.

{
  "group": "namespace",
  "code": "name_not_unique",
  "message": "A namespace with this name already exists."
}

415

The request is missing the Content-Type: application/json header. Returned as plain text.

Content type: text/plain.

422

The JSON body does not match the request schema, for example a missing required field, a wrong type or an unknown field where unknown fields are rejected. Returned as plain text.

Content type: text/plain.

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