Manage Actors

Create Actor

Create a new actor. Fails if an 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.

POST https://api.rivet.dev/actors

Examples

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

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 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

Name	Type	Required	Description
`namespace`	`string`	Yes	Name of the namespace to operate in.

Request Body

Content type: application/json.

Field	Type	Required	Description
`crash_policy`	`"restart" \| "sleep" \| "destroy"`	Yes	What happens when the actor crashes. RivetKit defaults to `sleep`.
`datacenter`	`string \| null`	No	Datacenter to create the actor in. Defaults to the datacenter serving the request.
`input`	`string \| null`	No	Base64url-encoded CBOR input passed to the actor’s `createState` and `onCreate` hooks.
`key`	`string \| null`	No	Key identifying this actor within its name. Multi-part keys are joined with `/`, see Actor Keys. Omit for a keyless actor.
`name`	`string`	Yes	Name of the actor as registered in your RivetKit registry.
`runner_name_selector`	`string`	Yes	Pool that runs the actor. RivetKit registers the `default` pool unless configured otherwise.

Responses

200

Field	Type	Description
`actor`	`object`
`actor.actor_id`	`string`	Unique ID of the actor.
`actor.connectable_ts`	`integer \| null`	Denotes when the actor was last connectable. Null if actor is not running.
`actor.crash_policy`	`"restart" \| "sleep" \| "destroy"`	What happens when the actor crashes.
`actor.create_ts`	`integer`	Denotes when the actor was first created.
`actor.datacenter`	`string`	Datacenter the actor is scheduled in.
`actor.destroy_ts`	`integer \| null`	Denotes when the actor was destroyed.
`actor.error`	`object \| null`	Error details if the actor failed to start.
`actor.key`	`string \| null`	Actor key. Multi-part keys are joined with `/`, see Actor Keys.
`actor.name`	`string`	Actor name as registered in your RivetKit registry.
`actor.namespace_id`	`string`	ID of the namespace the actor belongs to.
`actor.pending_allocation_ts`	`integer \| null`	Denotes when the actor started waiting for an allocation.
`actor.reschedule_ts`	`integer \| null`	Denotes when the actor will try to allocate again. If this is set, the actor will not attempt to allocate until the given timestamp.
`actor.runner_name_selector`	`string`	Pool the actor runs on.
`actor.sleep_ts`	`integer \| null`	Denotes when the actor entered a sleeping state.
`actor.start_ts`	`integer \| null`	Denotes when the actor was first made connectable. Null if never.

{
  "actor": {
    "actor_id": "00000000-0000-0000-0000-000000000000",
    "connectable_ts": null,
    "crash_policy": "restart",
    "create_ts": 1700000000000,
    "datacenter": "us-east",
    "destroy_ts": null,
    "error": null,
    "key": null,
    "name": "my-actor",
    "namespace_id": "00000000-0000-0000-0000-000000000000",
    "pending_allocation_ts": null,
    "reschedule_ts": null,
    "runner_name_selector": "default",
    "sleep_ts": null,
    "start_ts": null
  }
}