Manage Actors

Get or Create Actor

Return the actor with the given name and key, creating it if it does not exist. This is the HTTP equivalent of client.actor.getOrCreate(key).

The response includes created, which is true when this call created the actor. Gateway endpoints can perform the same lookup inline with the rvt-* selector parameters, so you only need this endpoint when you want the actor_id up front.

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

Examples

curl -X PUT "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);

// getOrCreate() returns a handle immediately. The PUT /actors call happens
// lazily when the handle is first used, or when you call resolve().
const counter = client.counter.getOrCreate(["my-counter"]);

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 if it does not exist. Defaults to the datacenter serving the request.
`input`	`string \| null`	No	Base64url-encoded CBOR input passed to the actor’s `createState` and `onCreate` hooks when the actor is created.
`key`	`string`	Yes	Key identifying this actor within its name. Multi-part keys are joined with `/`, see Actor Keys.
`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.
`created`	`boolean`	`true` if this request created the actor, `false` if it already existed.

{
  "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
  },
  "created": false
}