Skip to main content
Sign In
Operating

Debugging

Inspect and manage Rivet Actors on a Rivet control plane with its HTTP API.

Connecting to Rivet

Every endpoint in this guide works locally and in production. Extract the shell variables below from your RIVET_ENDPOINT (https://<namespace>:<token>@<host>):

# From RIVET_ENDPOINT=https://my-namespace:<rivet-token>@rivet.example.com
export RIVET_API="https://rivet.example.com"
export RIVET_NAMESPACE="my-namespace"
export RIVET_TOKEN="<rivet-token>"

# Local development uses the local control plane and the token `default`:
# export RIVET_API="http://localhost:6420" RIVET_NAMESPACE="default" RIVET_TOKEN="default"

Send the token as a bearer token on every request except GET /metadata. Use a token authorized for the selected namespace. The self-hosted admin token can access every namespace. See Namespaces.

Rivet Actors

List Rivet Actors

# All Rivet Actors with a given name
curl "$RIVET_API/actors?name=my-actor&namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

# One Rivet Actor by key (key requires name)
curl "$RIVET_API/actors?name=my-actor&key=my-key&namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

# Rivet Actors by ID (comma-separated)
curl "$RIVET_API/actors?actor_ids=id1,id2&namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

actor_ids cannot be combined with name or key.

{
  "actors": [
    {
      "actor_id": "abc123",
      "name": "my-actor",
      "key": "my-key",
      "namespace": "default",
      "create_ts": 1706000000000
    }
  ],
  "pagination": { "cursor": null }
}

Keys in HTTP requests use comma-separated components, with commas and backslashes escaped inside a component. Use curl --get --data-urlencode for keys containing special characters. The single-component key my-key needs no escaping.

Create a Rivet Actor

POST /actors creates a Rivet Actor. PUT /actors creates it if it does not exist and returns the existing one otherwise.

curl -X PUT "$RIVET_API/actors?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "my-actor", "key": "my-key" }'

The Rivet Actor runs in the default node pool.

Set "pool": "gpu" in the request body to select another configured node pool.

Sleep or destroy a Rivet Actor

curl -X POST "$RIVET_API/actors/{actor_id}/sleep?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

curl -X DELETE "$RIVET_API/actors/{actor_id}?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

List Rivet Actor names

curl "$RIVET_API/actors/names?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

## Nodes

```bash
# Connected nodes in the default pool
curl "$RIVET_API/pools/default/nodes?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

# Configured node pools
curl "$RIVET_API/pools?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

Pool configuration persists even when no nodes are connected.

To check that nodes are connected, call a Rivet Actor from a client. A Rivet Actor stays Pending while no node in its node pool is connected. See Statuses.

OpenAPI Spec

An OpenAPI specification covering many of the management and actor endpoints is available:

Every control plane endpoint, with its parameters and responses, is listed in the HTTP API reference.