Inspector

Patch State

Replace the actor's current state.

The inspector API is subject to change without notice. Do not build production integrations on it.

This writes state directly and bypasses actor actions. Use it only for inspection and recovery.

PATCH https://rivet.example.com/gateway/{actor}/inspector/state

Examples

curl -X PATCH "https://rivet.example.com/gateway/$ACTOR_ID/inspector/state" \
  -H "Authorization: Bearer $INSPECTOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state": {
      "count": 2
    }
  }'

const endpoint = "https://api.rivet.dev";
const response = await fetch(
	`${endpoint}/gateway/${process.env.ACTOR_ID}/inspector/state`,
	{
		method: "PATCH",
		headers: {
			Authorization: `Bearer ${process.env.INSPECTOR_TOKEN}`,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({ state: { count: 2 } }),
	},
);
console.log(await response.json());
export {};

Authentication

Inspector endpoints do not accept namespace tokens. Send the actor’s inspector token as a bearer token in the Authorization header.

Path Parameters

Name	Type	Required	Description
`actor`	`string`	Yes	Actor ID, actor ID with an inline token (`{actor_id}@{token}`), or actor name combined with the `rvt-*` query parameters.

Headers

Name	Type	Required	Description
`Authorization`	`string`	No	Bearer token for inspector authentication. Required in production, optional in development.

{actor} accepts an actor ID, an actor ID with an inline routing token ({actor_id}@{token}), or an actor name combined with the rvt-* query parameters below. See Actor Routing for the full rules.

Name	Type	Required	Description
`rvt-namespace`	`string`	No	Namespace the actor lives in. Required when `{actor}` is an actor name.
`rvt-method`	`string`	No	How to resolve an actor name to an actor. `getOrCreate` requires `rvt-pool`. One of `"get"`, `"getOrCreate"`.
`rvt-key`	`string`	No	Actor key. Separate multi-part keys with commas.
`rvt-pool`	`string`	No	Pool to create the actor on when `rvt-method=getOrCreate`. RivetKit registers the `default` pool unless configured otherwise.
`rvt-runner`	`string`	No	Deprecated alias for `rvt-pool`.
`rvt-input`	`string`	No	Base64url-encoded CBOR input passed to `createState` and `onCreate` when `rvt-method=getOrCreate` creates the actor.
`rvt-region`	`string`	No	Preferred region when `rvt-method=getOrCreate` creates the actor.
`rvt-crash-policy`	`string`	No	Crash policy when `rvt-method=getOrCreate` creates the actor. RivetKit defaults to `sleep`. One of `"restart"`, `"sleep"`, `"destroy"`.
`rvt-skip-ready-wait`	`boolean`	No	Return as soon as the actor is resolved instead of waiting for it to be ready.
`rvt-token`	`string`	No	Token to authenticate with. Prefer the `x-rivet-token` header or inline path token when possible.

Request Body

Content type: application/json (optional).

Field	Type	Required	Description
`state`	`any`	Yes

Responses

200

The state was saved.

Field	Type	Description
`ok`	`boolean`

{
  "ok": true
}

401

The inspector token is missing or invalid.