Create Actor

Create a new actor. Fails if a live actor with the same name and key already exists.

Prefer Get or Create Actor for idempotent access by key. Use this endpoint when you need a fresh actor every time, for example with a random key. The request returns once the actor’s record exists, and fails after 30 seconds. A namespace token needs a grant on actor with create.

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

Examples

curl -X POST "https://rivet.example.com/actors?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "counter",
    "key": "my-counter",
    "runner_name_selector": "default"
  }'

import { createClient } from "rivetkit/client";
import type { registry } from "./index";

const client = createClient<typeof registry>(process.env.RIVET_ENDPOINT);

// create() sends POST /actors and returns a handle bound to the new actor ID.
// It fails if an actor named "counter" with this key already exists.
const counter = await client.counter.create([`counter-${crypto.randomUUID()}`]);

const actorId = await counter.resolve();
console.log(actorId);

Authentication

Send the admin token, or a namespace token from Create Token whose grants cover the request, as a bearer token in the Authorization header. The x-rivet-token header is also accepted. Routes with a namespace query parameter use the default namespace when it is omitted. See Authentication.

Query Parameters

Request Body

Content type: application/json.

Responses

200

The created actor. created is always true.

{
  "actor": {
    "actor_id": "d97pbq1nyqxw1w5qdwz0iirbqiblh2",
    "name": "my-actor",
    "key": "my-key",
    "namespace": "my-namespace",
    "runner_name_selector": "default",
    "create_ts": 1700000000000,
    "start_ts": null,
    "pending_allocation_ts": null,
    "connectable_ts": null,
    "sleep_ts": null,
    "reschedule_ts": null,
    "destroy_ts": null
  },
  "created": false
}

400

actor.invalid_name: name is empty or longer than 64 bytes. actor.invalid_key: key is longer than 1024 bytes. actor.invalid_key_encoding: key is not in canonical slash-separated form. actor.key_owned_elsewhere: another datacenter owns the key. envoy.invalid_pool_name: runner_name_selector is not a valid pool name. envoy.invalid_namespace_name: the namespace value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.

{
  "group": "actor",
  "code": "invalid_name",
  "message": "Actor name must be 1 to 64 bytes."
}

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.

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

404

namespace.not_found: the namespace does not exist.

{
  "group": "namespace",
  "code": "not_found",
  "message": "The namespace does not exist."
}

409

actor.duplicate_key: a live actor with this name and key already exists.

{
  "group": "actor",
  "code": "duplicate_key",
  "message": "Actor key already in use."
}

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, including input that is not valid base64 and a create that did not finish within 30 seconds.

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