Call Action

Invoke an action defined on an actor and return its result. This is the HTTP equivalent of calling a method on an actor handle in the RivetKit client.

Arguments are passed as a JSON array in args and spread into the action’s parameters. The action’s return value comes back in output. Actions that return undefined respond with { "output": null }.

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

Examples

curl -X POST "https://api.rivet.dev/gateway/counter/action/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 '{
    "args": [
      1
    ]
  }'

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

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

// getOrCreate resolves the actor by name and key, the same as
// rvt-method=getOrCreate&rvt-key=my-counter over HTTP.
const counter = client.counter.getOrCreate(["my-counter"]);

// Calling an action sends POST /gateway/{actor}/action/increment
// with body { "args": [1] } and returns the "output" field.
const count = await counter.increment(1);
console.log(count); // 1

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

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.

Request Body

Content type: application/json (optional).

Responses

200

Action executed successfully

{
  "output": 1
}

400

Invalid action

500

Internal error

Related

• Actions
• Actor Routing