Destroy Actor

Destroy an actor. The actor's onDestroy hook runs, then its state is deleted permanently.

For an actor listed in its namespace’s skipped field, the destroy also removes it from that list. It succeeds again for such an actor once it is destroyed or gone, so repeat it until skipped_count drops.

DELETE https://rivet.example.com/actors/{actor_id}

Examples

curl -X DELETE "https://rivet.example.com/actors/$ACTOR_ID?namespace=$RIVET_NAMESPACE" \
  -H "Authorization: Bearer $RIVET_TOKEN"

const endpoint = "https://api.rivet.dev";
const namespace = process.env.RIVET_NAMESPACE ?? "default";
const token = process.env.RIVET_TOKEN ?? "";
const actorId = "00000000-0000-0000-0000-000000000000";

const response = await fetch(
	`${endpoint}/actors/${actorId}?namespace=${namespace}`,
	{
		method: "DELETE",
		headers: { Authorization: `Bearer ${token}` },
	},
);

if (!response.ok) {
	throw new Error(`Failed to destroy actor: ${await response.text()}`);
}

export {};

Authentication

Send your namespace token as a bearer token in the Authorization header. Every control plane request also requires the namespace query parameter. See Authentication.

Path Parameters

Query Parameters

Responses

200

The destroy was accepted.

{}

400

envoy.invalid_namespace_name: the namespace value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.

{
  "group": "envoy",
  "code": "invalid_namespace_name",
  "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens."
}

401

auth.invalid_token: the request carries no token, or the token is not valid. auth.token_expired: the token has expired.

{
  "group": "auth",
  "code": "invalid_token",
  "message": "Authentication token is invalid."
}

403

auth.insufficient_permissions: the token’s grants do not cover this request. For a namespace token this is also returned when the actor does not exist.

{
  "group": "auth",
  "code": "insufficient_permissions",
  "message": "Insufficient permissions to access this resource."
}

404

actor.not_found: the actor does not exist or belongs to another namespace. namespace.not_found: the namespace does not exist.

{
  "group": "actor",
  "code": "not_found",
  "message": "The actor does not exist or was destroyed."
}

500

core.internal_error: an unexpected failure, including an actor_id that is not a valid Rivet ID.

{
  "group": "core",
  "code": "internal_error",
  "message": "An internal error occurred"
}

503

auth.verification_unavailable: token verification keys are temporarily unavailable. Retry the request.

{
  "group": "auth",
  "code": "verification_unavailable",
  "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request."
}

Related

• Destroying Actors