Call Actors

Send Queue Message

Enqueue a durable message for an actor. Optionally wait for the actor to complete it and return a response.

By default, the request returns after the message is enqueued. Set wait to true to wait for message.complete(...); timeout sets that wait in milliseconds, and a timeout returns status: "timedOut" without canceling the queued work.

POST https://api.rivet.dev/gateway/{actor}/queue/{name}

Examples

curl -X POST "https://api.rivet.dev/gateway/counter/queue/increment?rvt-namespace=$RIVET_NAMESPACE&rvt-method=getOrCreate&rvt-key=my-counter&rvt-pool=default" \
  -H "x-rivet-token: $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "amount": 1
    },
    "wait": true,
    "timeout": 5000
  }'

const endpoint = "https://api.rivet.dev";
const actorId = process.env.ACTOR_ID;
const response = await fetch(`${endpoint}/gateway/${actorId}/queue/increment`, {
	method: "POST",
	headers: {
		Authorization: `Bearer ${process.env.RIVET_TOKEN}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({ body: { amount: 1 }, wait: true, timeout: 5000 }),
});
console.log(await response.json());
export {};

Authentication

Send a token in the x-rivet-token header, inline in the path as {actor_id}@{token}, or in the rvt-token query parameter. Use a public token (pk_) from browsers and a secret token (sk_) from trusted backends. See Authentication.

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.
`name`	`string`	Yes	Name of the queue message as defined in the actor’s `queues` map.

Actor Selector

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

Field	Type	Required	Description
`body`	`any`	Yes	Message payload. Any JSON value.
`wait`	`boolean`	No	Wait for the actor to complete the message and return its response.
`timeout`	`integer`	No	How long to wait for completion, in milliseconds. Only used with wait.

Responses

200

The message was enqueued, with its completion status when waiting.

Field	Type	Description
`status`	`"completed" \| "timedOut"`	Whether the actor completed the message before the timeout.
`response`	`any`	Value the actor passed to complete(). Present when status is completed.

{
  "status": "completed",
  "response": {
    "count": 1
  }
}

Queues