Skip to main content
Sign In
General

Actor Routing

How the gateway resolves the {actor} segment of a URL by ID or by name and key.

Every endpoint in this section starts with /gateway/{actor}/. The {actor} segment identifies which actor receives the request. There are two forms: a direct actor ID, or an actor name combined with rvt-* query parameters that tell Rivet how to resolve it.

By Actor ID

If you already know the actor’s ID, put it in the path. This is the fastest form since no lookup is needed.

curl "https://api.rivet.dev/gateway/$ACTOR_ID/action/increment" \
  -H "x-rivet-token: $RIVET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"args": [1]}'

Append @{token} to send the token inline instead of in a header:

curl "https://api.rivet.dev/gateway/$ACTOR_ID@$RIVET_TOKEN/request/status"

Actor IDs come from the response of Create Actor, Get or Create Actor, or List Actors. The RivetKit client exposes the same value through handle.resolve().

By Name and Key

Put the actor name in the path and describe the lookup with rvt-* query parameters. Rivet resolves the actor, creates it if asked, waits for it to be ready, and forwards the request.

curl "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]}'

This is what the RivetKit client does for client.counter.getOrCreate(["my-counter"]).increment(1).

Parameters

ParameterRequiredDescription
rvt-namespaceYesNamespace the actor lives in.
rvt-methodYesget to fail if the actor does not exist, or getOrCreate to create it on first use.
rvt-keyNoActor key. Separate multi-part keys with commas: rvt-key=org-1,room-2. Omit for a keyless actor.
rvt-poolFor getOrCreatePool to create the actor on. RivetKit registers the default pool unless configured otherwise. rvt-runner is a deprecated alias.
rvt-inputNoBase64url-encoded CBOR passed to createState and onCreate if the actor is created. Only with getOrCreate.
rvt-regionNoPreferred region if the actor is created. Only with getOrCreate.
rvt-crash-policyNorestart, sleep, or destroy. RivetKit defaults to sleep. Only with getOrCreate.
rvt-skip-ready-waitNotrue to forward the request as soon as the actor is resolved instead of waiting for it to be ready.
rvt-tokenNoToken, as an alternative to the x-rivet-token header.

Rules

  • Every rvt-* parameter is reserved. Unknown or duplicated rvt-* parameters return a 400.
  • rvt-* parameters are stripped before the request reaches your actor. Other query parameters pass through unchanged, so /gateway/counter/request/search?q=hi&rvt-namespace=... reaches onRequest as /search?q=hi.
  • rvt-method=get never creates an actor. Passing rvt-input, rvt-region, rvt-crash-policy, or rvt-runner with get returns a 400.
  • The @{token} path syntax is not allowed with actor names. Use rvt-token or the header instead.
  • Commas inside a key part cannot be expressed in rvt-key. Create such actors with Create Actor and route to them by ID. See Actor Keys for how the control plane encodes keys.
Edit this page