--- title: "Create Actor" 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. An `actor.create_pending` response (HTTP 409) means creation may have taken effect but the result could not be confirmed. Inspect the actor identified by `metadata.actor_id` rather than automatically resubmitting the create. A not-found read can race an in-flight create; retrying a keyless create can create a second actor. ```http POST https://rivet.example.com/actors ``` ## Examples ```bash cURL curl -X POST "https://rivet.example.com/actors?namespace=$RIVET_NAMESPACE" \ -H "Authorization: Bearer $RIVET_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "counter", "key": "my-counter", "runner_name_selector": "default", "crash_policy": "sleep" }' ``` ## 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. | ## Request Body Content type: `application/json`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | `string` | Yes | Name of the actor as registered in your RivetKit registry. | | `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. | | `input` | `string \| null` | No | Base64url-encoded CBOR input passed to the actor's `onCreate` hook. | | `pool` | `string \| null` | No | Name of the node pool to run the actor in. Defaults to `default`. | ## Responses ### 200 The created actor. | Field | Type | Description | | --- | --- | --- | | `actor` | `object` | | | `actor.actor_id` | `string` | Unique ID of the actor. | | `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). | | `actor.namespace` | `string` | Name of the namespace the actor belongs to. | | `actor.pool` | `string` | Name of the 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`. | | `actor.forked_from` | `any \| null \| string` | ID of the actor this actor's database was forked from, or `null`. | | `created` | `boolean` | `true` if this request created the actor, `false` if it already existed. | ```json { "actor": { "actor_id": "d97pbq1nyqxw1w5qdwz0iirbqiblh2", "name": "my-actor", "key": "my-key", "namespace": "my-namespace", "pool": "default", "create_ts": 1700000000000, "start_ts": null, "pending_allocation_ts": null, "connectable_ts": null, "sleep_ts": null, "reschedule_ts": null, "destroy_ts": null, "forked_from": 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`: `pool` 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. `actor.invalid_input`: `input` is not valid base64. | 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 on some errors, for example the retry hint of a refusal or the new actor of a pending fork. | ```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 on some errors, for example the retry hint of a refusal or the new actor of a pending fork. | ```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 on some errors, for example the retry hint of a refusal or the new actor of a pending fork. | ```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 on some errors, for example the retry hint of a refusal or the new actor of a pending fork. | ```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 on some errors, for example the retry hint of a refusal or the new actor of a pending fork. | ```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 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 on some errors, for example the retry hint of a refusal or the new actor of a pending fork. | ```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 on some errors, for example the retry hint of a refusal or the new actor of a pending fork. | ```json { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } ```