Create Namespace

Create a namespace with a unique name, or fork an existing namespace into a new one whose keyed actors and listings are the parent's as of the fork.

A new namespace is written with status creating, or forking for a fork, and the call answers once it is live, or after 30 seconds with the namespace as it stands; poll GET /namespaces?name= until it is live. A fork includes every write the parent acknowledged before the call. Pass wait=settled to wait a few more seconds after the fork is live, so later parent writes usually stay out of the fork; it does not guarantee it. Namespace names are never reused: an archived or failed name stays listed with its status. Forking is refused for a namespace upgraded from an earlier release until its existing actors have been moved into its volume group (namespace.not_forkable). An actor the move could not move after its retries is left in place and listed in the namespace’s skipped field, by ID, name and key, with their number in skipped_count (see GET /namespaces?name=). It stays reachable by its ID and its key, so you can read and export its data, and forking stays refused (namespace.backfill_skipped, which gives the number of such actors) until each one is destroyed, through DELETE /actors/{actor_id} or by the actor itself. Destroying a listed actor is idempotent: repeat it if skipped_count did not drop, even once the actor is gone. Access to such actors is removed with the backfill in 3.1, so export and destroy them before upgrading. Forking is also refused for a namespace that is still being created (namespace.creating, 503 with Retry-After; retry after the hinted delay), forking, archiving or archived (namespace.pending, namespace.archived), one whose fork failed (namespace.failed), one at the lineage depth cap (namespace.lineage_too_deep), or one a migration from Rivet v2 is still moving actors into (namespace.migrating_from_v2, 409), until the migration ends. A new namespace appears in GET /namespaces once its listing entry is written, usually within the call; a lookup by name never waits for it.

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, with its status and, for a fork, forked_from.

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

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