Debugging Actors

Inspect a running Rivet Actor through its gateway endpoints.

Every endpoint here is reached through the gateway using an actor ID. To find actor IDs or check on your nodes, see Debugging in the platform docs. That page also defines the $RIVET_API, $RIVET_NAMESPACE, and $RIVET_TOKEN shell variables used throughout the examples below.

All actor-level endpoints are accessed through the gateway. The gateway routes requests to the correct actor instance using the actor ID in the URL path:

{RIVET_API}/gateway/{actor_id}/{path}

The gateway can also find an actor by name and key from query parameters. See Actor Routing.

Authentication

Standard actor endpoints (health, actions, requests) use the same authentication as the rest of the gateway.

Standard Endpoints

Standard Actor Endpoints

These are the built-in actor endpoints available through the gateway:

# Health check
curl $RIVET_API/gateway/{actor_id}/health

# Metadata
curl $RIVET_API/gateway/{actor_id}/metadata

# Call an action
curl -X POST $RIVET_API/gateway/{actor_id}/action/myAction \
  -H 'Content-Type: application/json' \
  -d '{"args": [1, 2, 3]}'

# Send queue message (queue name in path)
curl -X POST $RIVET_API/gateway/{actor_id}/queue/jobs \
  -H 'Content-Type: application/json' \
  -d '{"body":{"id":"job-1"}}'

# Send queue message and wait for completion (optional timeout in ms)
curl -X POST $RIVET_API/gateway/{actor_id}/queue/jobs \
  -H 'Content-Type: application/json' \
  -d '{"body":{"id":"job-1"},"wait":true,"timeout":5000}'

# Forward an HTTP request to the actor's onRequest handler
curl $RIVET_API/gateway/{actor_id}/request/my/custom/path

Queue send responses always include a status field:

{ "status": "completed" }

The response field is only present when the queue handler returns a value:

{ "status": "completed", "response": { "result": "ok" } }

If wait: true and the timeout is reached, status is "timedOut".