Skip to main content
Sign In
More

Debugging

Inspect and debug running Rivet Actors using the management and actor inspector HTTP APIs.

Management API

The management API runs on the root path and is used to list, create, and look up actors.

Authentication

EnvironmentAuthentication
Local developmentNo authentication required. All endpoints are accessible without tokens.
Self-hosted engineThe Rivet Engine handles authentication. Set RIVET_TOKEN to enable authenticated access to restricted endpoints like KV.
Rivet CloudAuthentication is handled by the Rivet Cloud platform. Use your project token passed via the x-rivet-token header.

Restricted endpoints (like KV reads) require the x-rivet-token header:

curl http://localhost:6420/actors/{actor_id}/kv/keys/{base64_key} \
  -H 'x-rivet-token: YOUR_RIVET_TOKEN'
Command Line

List Actors

# List all actors with a given name
curl http://localhost:6420/actors?name=my-actor

# List actors by key
curl http://localhost:6420/actors?key=my-key

# List actors by IDs (comma-separated)
curl http://localhost:6420/actors?actor_ids=id1,id2
Command Line

Returns:

{
  "actors": [
    {
      "actor_id": "abc123",
      "name": "my-actor",
      "key": "[\"default\"]",
      "namespace_id": "default",
      "create_ts": 1706000000000
    }
  ]
}
JSON

Create or Get Actor

curl -X PUT http://localhost:6420/actors \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-actor",
    "key": "[\"default\"]",
    "runner_name_selector": "default",
    "crash_policy": "restart"
  }'
Command Line

Returns the actor object with its actor_id.

List Actor Names

curl http://localhost:6420/actors/names?namespace=default
Command Line

Returns all registered actor names and their metadata.

Read Actor KV

Requires authentication (see above).

curl http://localhost:6420/actors/{actor_id}/kv/keys/{base64_key} \
  -H 'x-rivet-token: YOUR_RIVET_TOKEN'
Command Line

Returns the value stored at the given key.

See the OpenAPI spec for the full schema of all management endpoints.

Actor API

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:

http://localhost:6420/gateway/{actor_id}/{path}

The gateway only accepts actor IDs, not names. Use GET /actors?name=... from the management API to look up actor IDs first.

Authentication

Standard actor endpoints (health, actions, requests) and inspector endpoints have separate authentication requirements.

Standard Endpoints

EnvironmentAuthentication
Local developmentNo authentication required.
Self-hosted engineThe Rivet Engine handles authentication at the gateway level.
Rivet CloudAuthentication is handled by the Rivet Cloud platform at the gateway level.

Inspector Endpoints

EnvironmentAuthentication
Local developmentNo authentication required if RIVET_INSPECTOR_TOKEN is not set. A warning is logged.
Self-hosted engineSet the RIVET_INSPECTOR_TOKEN environment variable. Pass it as a bearer token in the Authorization header.
Rivet CloudToken is required. Pass it as a bearer token in the Authorization header.
curl http://localhost:6420/gateway/{actor_id}/inspector/summary \
  -H 'Authorization: Bearer YOUR_INSPECTOR_TOKEN'
Command Line

Standard Actor Endpoints

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

# Health check
curl http://localhost:6420/gateway/{actor_id}/health

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

# Forward an HTTP request to the actor's onRequest handler
curl http://localhost:6420/gateway/{actor_id}/request/my/custom/path
Command Line

Inspector Endpoints

The inspector HTTP API exposes JSON endpoints for querying and modifying actor internals at runtime. These are designed for agent-based debugging and tooling.

Get State

curl http://localhost:6420/gateway/{actor_id}/inspector/state
Command Line

Returns the actor’s current persisted state:

{ "state": { "count": 42, "users": [] } }
JSON

Set State

curl -X PATCH http://localhost:6420/gateway/{actor_id}/inspector/state \
  -H 'Content-Type: application/json' \
  -d '{"state": {"count": 0, "users": []}}'
Command Line

Returns:

{ "ok": true }
JSON

Get Connections

curl http://localhost:6420/gateway/{actor_id}/inspector/connections
Command Line

Returns all active connections with their params, state, and metadata:

{
  "connections": [
    {
      "type": "websocket",
      "id": "conn-id",
      "details": {
        "type": "websocket",
        "params": {},
        "stateEnabled": true,
        "state": {},
        "subscriptions": 2,
        "isHibernatable": true
      }
    }
  ]
}
JSON

Get RPCs

curl http://localhost:6420/gateway/{actor_id}/inspector/rpcs
Command Line

Returns a list of available actions:

{ "rpcs": ["increment", "getCount"] }
JSON

Execute Action

curl -X POST http://localhost:6420/gateway/{actor_id}/inspector/action/increment \
  -H 'Content-Type: application/json' \
  -d '{"args": [5]}'
Command Line

Returns:

{ "output": 47 }
JSON

Get Queue Status

curl http://localhost:6420/gateway/{actor_id}/inspector/queue?limit=10
Command Line

Returns queue status with messages:

{
  "size": 3,
  "maxSize": 1000,
  "truncated": false,
  "messages": [
    { "id": 1, "name": "process", "createdAtMs": 1706000000000 }
  ]
}
JSON

Get Traces

Query trace spans in OTLP JSON format:

curl "http://localhost:6420/gateway/{actor_id}/inspector/traces?startMs=0&endMs=9999999999999&limit=100"
Command Line

Returns:

{
  "otlp": {
    "resourceSpans": [
      {
        "scopeSpans": [
          {
            "spans": [
              {
                "traceId": "abc123",
                "spanId": "def456",
                "name": "increment",
                "startTimeUnixNano": "1706000000000000000"
              }
            ]
          }
        ]
      }
    ]
  },
  "clamped": false
}
JSON

Get Workflow History

curl http://localhost:6420/gateway/{actor_id}/inspector/workflow-history
Command Line

Returns:

{
  "history": null,
  "isWorkflowEnabled": false
}
JSON

Summary

Get a full snapshot of the actor in a single request:

curl http://localhost:6420/gateway/{actor_id}/inspector/summary
Command Line

Returns:

{
  "state": { "count": 42 },
  "connections": [],
  "rpcs": ["increment", "getCount"],
  "queueSize": 0,
  "isStateEnabled": true,
  "isDatabaseEnabled": false,
  "isWorkflowEnabled": false,
  "workflowHistory": null
}
JSON

Polling

Inspector endpoints are safe to poll. For live monitoring, poll at 1-5 second intervals. The /inspector/summary endpoint is useful for periodic snapshots since it returns all data in a single request.

OpenAPI Spec

The full OpenAPI specification including all management and actor endpoints is available:

Edit this page