Skip to content

docs(api): sync from rivet-dev/rivet #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NathanFlurry wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(api): sync from rivet-dev/rivet #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
216 changes: 38 additions & 178 deletions vendor/api/docs/content/actors/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: "Create Actor"
description: "Create a new actor. Fails if a live actor with the same name and key already exists."
description: "Create a new actor. Fails if an actor with the same name and key already exists."
---

{/* Generated by scripts/docs/gen-api-reference.mjs from engine/artifacts/openapi.json and docs/api/endpoints.json. Do not edit by hand. */}

Prefer [Get or Create Actor](/docs/api/actors/get-or-create) for idempotent access by key. Use this endpoint when you need a fresh actor every time, for example with a random key. The request returns once the actor's record exists, and fails after 30 seconds. A namespace token needs a grant on `actor` with `create`.
Prefer [Get or Create Actor](/docs/api/actors/get-or-create) for idempotent access by key. Use this endpoint when you need a fresh actor every time, for example with a random key.

```http
POST https://rivet.example.com/actors
Expand All @@ -22,7 +22,8 @@ curl -X POST "https://rivet.example.com/actors?namespace=$RIVET_NAMESPACE" \
-d '{
"name": "counter",
"key": "my-counter",
"runner_name_selector": "default"
"runner_name_selector": "default",
"crash_policy": "sleep"
}'
```

Expand All @@ -32,209 +33,68 @@ curl -X POST "https://rivet.example.com/actors?namespace=$RIVET_NAMESPACE" \

## Authentication

Send the admin token, or a namespace token from [Create Token](/docs/api/tokens/create) whose grants cover the request, as a bearer token in the `Authorization` header. The `x-rivet-token` header is also accepted. Routes with a `namespace` query parameter use the `default` namespace when it is omitted. See [Authentication](/docs/api/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](/docs/api/authentication).

## Query Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `namespace` | `string` | No | Name of the namespace to operate in. Defaults to `default`. |
| `namespace` | `string` | Yes | Name of the namespace to operate in. |

## Request Body

Content type: `application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Name of the actor as registered in your RivetKit registry. 1 to 64 bytes. |
| `key` | `string \| null` | No | Key identifying this actor within its name. Multi-part keys are joined with `/`, see [Actor Keys](/docs/api/actor-keys). Omit for an actor without a key. |
| `input` | `string \| null` | No | Input passed to the actor, encoded as standard base64 (not base64url). |
| `runner_name_selector` | `string \| null` | No | Node pool that runs the actor. Defaults to `default`. |
| `crash_policy` | `"restart" \| "sleep" \| "destroy"` | Yes | What happens when the actor crashes. RivetKit defaults to `sleep`. |
| `datacenter` | `string \| null` | No | Datacenter to create the actor in. Defaults to the datacenter serving the request. |
| `input` | `string \| null` | No | Base64url-encoded CBOR input passed to the actor's `createState` and `onCreate` hooks. |
| `key` | `string \| null` | No | Key identifying this actor within its name. Multi-part keys are joined with `/`, see [Actor Keys](/docs/api/actor-keys). Omit for a keyless actor. |
| `name` | `string` | Yes | Name of the actor as registered in your RivetKit registry. |
| `runner_name_selector` | `string` | Yes | Pool that runs the actor. RivetKit registers the `default` pool unless configured otherwise. |

## Responses

### 200

The created actor. `created` is always `true`.

| Field | Type | Description |
| --- | --- | --- |
| `actor` | `object` | |
| `actor.actor_id` | `string` | Unique ID of the actor. |
| `actor.connectable_ts` | `integer \| null` | Denotes when the actor was last connectable. Null if actor is not running. |
| `actor.crash_policy` | `"restart" \| "sleep" \| "destroy"` | What happens when the actor crashes. |
| `actor.create_ts` | `integer` | Denotes when the actor was first created. |
| `actor.datacenter` | `string` | Datacenter the actor is scheduled in. |
| `actor.destroy_ts` | `integer \| null` | Denotes when the actor was destroyed. |
| `actor.error` | `object \| null` | Error details if the actor failed to start. |
| `actor.key` | `string \| null` | Actor key. Multi-part keys are joined with `/`, see [Actor Keys](/docs/api/actor-keys). |
| `actor.name` | `string` | Actor name as registered in your RivetKit registry. |
| `actor.key` | `string` | Actor key. Multi-part keys are joined with `/`, see [Actor Keys](/docs/api/actor-keys). An empty string for an actor without a key. |
| `actor.namespace` | `string` | Name of the namespace the actor belongs to. |
| `actor.runner_name_selector` | `string` | Node pool the actor runs in. |
| `actor.create_ts` | `integer` | When the actor was created, in Unix milliseconds. |
| `actor.start_ts` | `integer \| null` | When the actor first started. Not recorded by this version, so always `null`. |
| `actor.pending_allocation_ts` | `integer \| null` | When the actor started waiting for a node. Not recorded by this version, so always `null`. |
| `actor.connectable_ts` | `integer \| null` | When the actor last became connectable. Not recorded by this version, so always `null`. |
| `actor.sleep_ts` | `integer \| null` | When the actor went to sleep. Not recorded by this version, so always `null`. |
| `actor.reschedule_ts` | `integer \| null` | When the actor will next try to allocate. Not recorded by this version, so always `null`. |
| `actor.destroy_ts` | `integer \| null` | When the actor was destroyed, in Unix milliseconds. Only set in listings that include destroyed actors; otherwise `null`. |
| `created` | `boolean` | Always `true`. |
| `actor.namespace_id` | `string` | ID of the namespace the actor belongs to. |
| `actor.pending_allocation_ts` | `integer \| null` | Denotes when the actor started waiting for an allocation. |
| `actor.reschedule_ts` | `integer \| null` | Denotes when the actor will try to allocate again. If this is set, the actor will not attempt to allocate until the given timestamp. |
| `actor.runner_name_selector` | `string` | Pool the actor runs on. |
| `actor.sleep_ts` | `integer \| null` | Denotes when the actor entered a sleeping state. |
| `actor.start_ts` | `integer \| null` | Denotes when the actor was first made connectable. Null if never. |

```json
{
"actor": {
"actor_id": "d97pbq1nyqxw1w5qdwz0iirbqiblh2",
"name": "my-actor",
"key": "my-key",
"namespace": "my-namespace",
"runner_name_selector": "default",
"actor_id": "00000000-0000-0000-0000-000000000000",
"connectable_ts": null,
"crash_policy": "restart",
"create_ts": 1700000000000,
"start_ts": null,
"datacenter": "us-east",
"destroy_ts": null,
"error": null,
"key": null,
"name": "my-actor",
"namespace_id": "00000000-0000-0000-0000-000000000000",
"pending_allocation_ts": null,
"connectable_ts": null,
"sleep_ts": null,
"reschedule_ts": null,
"destroy_ts": null
},
"created": false
}
```

### 400

`actor.invalid_name`: `name` is empty or longer than 64 bytes. `actor.invalid_key`: `key` is longer than 1024 bytes. `actor.invalid_key_encoding`: `key` is not in canonical slash-separated form. `actor.key_owned_elsewhere`: another datacenter owns the key. `envoy.invalid_pool_name`: `runner_name_selector` is not a valid pool name. `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.

| Field | Type | Description |
| --- | --- | --- |
| `group` | `string` | Error group, for example `actor`. |
| `code` | `string` | Error code within the group, for example `not_found`. |
| `message` | `string` | Human-readable error message. |
| `metadata` | `any` | Extra details. Only present on some errors raised while authenticating or authorizing the request. |

```json
{
"group": "actor",
"code": "invalid_name",
"message": "Actor name must be 1 to 64 bytes."
}
```

### 401

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

| Field | Type | Description |
| --- | --- | --- |
| `group` | `string` | Error group, for example `actor`. |
| `code` | `string` | Error code within the group, for example `not_found`. |
| `message` | `string` | Human-readable error message. |
| `metadata` | `any` | Extra details. Only present on some errors raised while authenticating or authorizing the request. |

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

### 403

`auth.insufficient_permissions`: the token's grants do not cover this request.

| Field | Type | Description |
| --- | --- | --- |
| `group` | `string` | Error group, for example `actor`. |
| `code` | `string` | Error code within the group, for example `not_found`. |
| `message` | `string` | Human-readable error message. |
| `metadata` | `any` | Extra details. Only present on some errors raised while authenticating or authorizing the request. |

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

### 404

`namespace.not_found`: the namespace does not exist.

| Field | Type | Description |
| --- | --- | --- |
| `group` | `string` | Error group, for example `actor`. |
| `code` | `string` | Error code within the group, for example `not_found`. |
| `message` | `string` | Human-readable error message. |
| `metadata` | `any` | Extra details. Only present on some errors raised while authenticating or authorizing the request. |

```json
{
"group": "namespace",
"code": "not_found",
"message": "The namespace does not exist."
}
```

### 409

`actor.duplicate_key`: a live actor with this name and key already exists.

| Field | Type | Description |
| --- | --- | --- |
| `group` | `string` | Error group, for example `actor`. |
| `code` | `string` | Error code within the group, for example `not_found`. |
| `message` | `string` | Human-readable error message. |
| `metadata` | `any` | Extra details. Only present on some errors raised while authenticating or authorizing the request. |

```json
{
"group": "actor",
"code": "duplicate_key",
"message": "Actor key already in use."
}
```

### 415

The request is missing the `Content-Type: application/json` header. Returned as plain text.

Content type: `text/plain`.

### 422

The JSON body does not match the request schema, for example a missing required field, a wrong type or an unknown field where unknown fields are rejected. Returned as plain text.

Content type: `text/plain`.

### 500

`core.internal_error`: an unexpected failure, including `input` that is not valid base64 and a create that did not finish within 30 seconds.

| Field | Type | Description |
| --- | --- | --- |
| `group` | `string` | Error group, for example `actor`. |
| `code` | `string` | Error code within the group, for example `not_found`. |
| `message` | `string` | Human-readable error message. |
| `metadata` | `any` | Extra details. Only present on some errors raised while authenticating or authorizing the request. |

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

### 503

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

| Field | Type | Description |
| --- | --- | --- |
| `group` | `string` | Error group, for example `actor`. |
| `code` | `string` | Error code within the group, for example `not_found`. |
| `message` | `string` | Human-readable error message. |
| `metadata` | `any` | Extra details. Only present on some errors raised while authenticating or authorizing the request. |

```json
{
"group": "auth",
"code": "verification_unavailable",
"message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request."
"runner_name_selector": "default",
"sleep_ts": null,
"start_ts": null
}
}
```
Loading
Loading