{ "openapi": "3.1.0", "info": { "title": "rivet-api-public", "description": "HTTP API of the Rivet control plane.", "contact": { "name": "Rivet Gaming, LLC", "email": "developer@rivet.dev" }, "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" }, "version": "2.3.31" }, "servers": [ { "url": "https://api.rivet.dev" } ], "paths": { "/metadata": { "get": { "tags": [ "metadata" ], "summary": "Returns the runtime and version of the control plane. Requests with the admin token also receive the actor names served by the default namespace.", "operationId": "metadata_get", "responses": { "200": { "description": "Runtime and version metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataGetResponse" } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } } }, "security": [ {}, { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/auth/tokens": { "post": { "tags": [ "auth::tokens" ], "summary": "Issues a namespace-scoped JWT. Requires the admin token, even when the deployment allows unauthenticated requests.", "operationId": "auth_tokens_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenCreateRequest" } } } }, "responses": { "200": { "description": "The issued token. The response carries `Cache-Control: no-store`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenCreateResponse" } } } }, "400": { "description": "`validation.invalid_input`: the subject exceeds 256 UTF-8 bytes, the duration is outside the allowed range, or the grant set is invalid (empty, more than 32 grants, a grant without operations or with more than 5, or a `token` or `jwt` resource). `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "validation", "code": "invalid_input", "message": "subject exceeds 256 UTF-8 bytes" } } } } }, "401": { "description": "`auth.invalid_token`: the request does not carry the admin token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.issuance_disabled`: JWT issuance is not enabled for this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "issuance_disabled", "message": "JWT issuance is not enabled for this deployment." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "415": { "description": "The request is missing the `Content-Type: application/json` header. Returned as plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "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": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including a deployment without authentication configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.issuance_unavailable`: the signing service is temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "issuance_unavailable", "message": "The server could not issue an authentication token because the signing service is temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/auth/tokens/inspect": { "get": { "tags": [ "auth::tokens" ], "summary": "Returns the namespace, subject, grants and lifetime of the JWT that authenticates the request.", "operationId": "auth_tokens_inspect", "responses": { "200": { "description": "The token's claims. The response carries `Cache-Control: no-store`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenInspectResponse" } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, the token is not valid, or it is the admin token rather than a JWT. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/datacenters": { "get": { "tags": [ "datacenters" ], "summary": "Lists the datacenters of the deployment. This version serves a single datacenter named `default`.", "operationId": "datacenters_list", "responses": { "200": { "description": "The datacenters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatacentersListResponse" } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/pools": { "get": { "tags": [ "pools" ], "summary": "Lists a page of the namespace's configured node pools, ordered by name. A pool is listed once it is configured, whether or not any node is connected.", "operationId": "pools_list", "parameters": [ { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return, from 1 to 100. Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Name of the last pool on the previous page. Pass the `pagination.cursor` value from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of node pools.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolsListResponse" } } } }, "400": { "description": "`actor.invalid_limit`: `limit` is not an integer from 1 to 100. `envoy.invalid_pool_name`: `cursor` 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "invalid_limit", "message": "The actor listing limit must be an integer from 1 to 100." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/pools/{pool}": { "get": { "tags": [ "pools" ], "summary": "Returns a node pool's configuration.", "operationId": "pools_get", "parameters": [ { "name": "pool", "in": "path", "required": true, "description": "Name of the node pool. A DNS label of 1 to 63 lowercase letters, digits and hyphens.", "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "responses": { "200": { "description": "The node pool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolResponse" } } } }, "400": { "description": "`envoy.invalid_pool_name`: the pool name is not valid. `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_pool_name", "message": "Pool name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`pool.not_found`: the node pool does not exist. `namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "pool", "code": "not_found", "message": "The node pool does not exist." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] }, "put": { "tags": [ "pools" ], "summary": "Creates or replaces a node pool's configuration. Omitted fields take their defaults. Nodes pick up the new configuration on their next connection.", "operationId": "pools_upsert", "parameters": [ { "name": "pool", "in": "path", "required": true, "description": "Name of the node pool. A DNS label of 1 to 63 lowercase letters, digits and hyphens.", "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolUpsertRequest" } } } }, "responses": { "200": { "description": "The stored node pool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolResponse" } } } }, "400": { "description": "`pool.invalid`: the body has an unknown field or a value out of range. `pool.serverless_unsupported`: the body sets `serverless` or `kind: \"serverless\"`. `envoy.invalid_pool_name`: the pool name is not valid. `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens. A body that is not valid JSON is rejected with a plain-text 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "pool", "code": "invalid", "message": "Node pool configuration is invalid." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "415": { "description": "The request is missing the `Content-Type: application/json` header. Returned as plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] }, "delete": { "tags": [ "pools" ], "summary": "Deletes a node pool. Fails while any node of the pool is connected.", "operationId": "pools_delete", "parameters": [ { "name": "pool", "in": "path", "required": true, "description": "Name of the node pool. A DNS label of 1 to 63 lowercase letters, digits and hyphens.", "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "responses": { "200": { "description": "The node pool was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolsDeleteResponse" } } } }, "400": { "description": "`envoy.invalid_pool_name`: the pool name is not valid. `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_pool_name", "message": "Pool name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`pool.not_found`: the node pool does not exist. `namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "pool", "code": "not_found", "message": "The node pool does not exist." } } } } }, "409": { "description": "`pool.nodes_connected`: the node pool still has connected nodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "pool", "code": "nodes_connected", "message": "The node pool still has connected nodes." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/pools/{pool}/nodes": { "get": { "tags": [ "pools" ], "summary": "Lists a page of the pool's live nodes in node key order. A node is listed while its heartbeat is recent enough for it to receive actors.", "operationId": "pools_list_nodes", "parameters": [ { "name": "pool", "in": "path", "required": true, "description": "Name of the node pool. A DNS label of 1 to 63 lowercase letters, digits and hyphens.", "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return, from 1 to 100. Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous response's `pagination.cursor`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of live nodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolsListNodesResponse" } } } }, "400": { "description": "`actor.invalid_limit`: `limit` is not an integer from 1 to 100. `actor.invalid_cursor`: `cursor` is malformed. `envoy.invalid_pool_name`: the pool name is not valid. `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "invalid_limit", "message": "The actor listing limit must be an integer from 1 to 100." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/namespaces": { "get": { "tags": [ "namespaces" ], "summary": "Lists namespaces in name order, or looks up one namespace by name. Requires the admin token.", "operationId": "namespaces_list", "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Only return the namespace with this name. The response then holds zero or one namespace, `pagination.cursor` is `null`, and `limit` and `cursor` are ignored.", "schema": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "cursor", "in": "query", "required": false, "description": "Name of the last namespace on the previous page. Pass the `pagination.cursor` value from the previous response.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of namespaces to return, from 1 to 100. Defaults to 100.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "A page of namespaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceListResponse" } } } }, "400": { "description": "`namespace.invalid`: `limit` is outside 1 to 100. `envoy.invalid_namespace_name`: `name` or `cursor` is not a valid namespace name. A query string with any other parameter, or a `limit` that is not a non-negative integer, is rejected with a plain-text 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "invalid", "message": "Namespace list limit must be between 1 and 100." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request. Namespace management is only available to the admin token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] }, "post": { "tags": [ "namespaces" ], "summary": "Creates a namespace. Requires the admin token.", "operationId": "namespaces_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespacesCreateRequest" } } } }, "responses": { "200": { "description": "The created namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespacesCreateResponse" } } } }, "400": { "description": "`envoy.invalid_namespace_name`: `name` is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_namespace_name", "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request. Namespace management is only available to the admin token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "409": { "description": "`namespace.name_not_unique`: a namespace with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "name_not_unique", "message": "A namespace with this name already exists." } } } } }, "415": { "description": "The request is missing the `Content-Type: application/json` header. Returned as plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "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": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/actors": { "get": { "tags": [ "actors::list" ], "summary": "Lists actors by IDs, by name and key, or by name. Only a listing by name is paginated.", "operationId": "actors_list", "parameters": [ { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } }, { "name": "name", "in": "query", "required": false, "description": "Actor name. Required unless `actor_ids` or `actor_id` is set. Without `key`, lists every actor with this name, newest first.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Actor key in slash-separated form. Requires `name`. Returns at most one actor.", "schema": { "type": "string" } }, { "name": "actor_ids", "in": "query", "required": false, "description": "Comma-separated actor IDs to look up. Takes precedence over `actor_id`, `name` and `key`. IDs of missing actors or of actors in another namespace are skipped.", "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "description": "Same as `actor_ids`, used when `actor_ids` is absent.", "schema": { "type": "string" } }, { "name": "include_destroyed", "in": "query", "required": false, "description": "Include destroyed actors. Must be exactly `true` or `false`.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of actors to return for a listing by name, from 1 to 100. Defaults to 100. A page can hold fewer actors even when more remain.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous response's `pagination.cursor`. Only used for a listing by name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The matching actors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsListResponse" } } } }, "400": { "description": "`actor.invalid_listing`: neither `name` nor actor IDs were given. `actor.invalid_include_destroyed`, `actor.invalid_limit`, `actor.invalid_cursor`: the parameter is malformed. `actor.invalid_key_encoding`: `key` is not in canonical slash-separated form. `envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "invalid_listing", "message": "Listing actors requires a name or actor IDs." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including an actor ID that is not a valid Rivet ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] }, "post": { "tags": [ "actors::create" ], "summary": "Creates an actor and waits until its record exists. Fails if a live actor with the same name and key exists.", "operationId": "actors_create", "parameters": [ { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsCreateRequest" } } } }, "responses": { "200": { "description": "The created actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsCreateResponse" } } } }, "400": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "invalid_name", "message": "Actor name must be 1 to 64 bytes." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "409": { "description": "`actor.duplicate_key`: a live actor with this name and key already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "duplicate_key", "message": "Actor key already in use." } } } } }, "415": { "description": "The request is missing the `Content-Type: application/json` header. Returned as plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "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": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including `input` that is not valid base64 and a create that did not finish within 30 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] }, "put": { "tags": [ "actors::get_or_create" ], "summary": "Returns the live actor with the given name and key, or creates it. Waking a sleeping actor is part of the lookup. Without a key, a new actor is always created.", "operationId": "actors_get_or_create", "parameters": [ { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsGetOrCreateRequest" } } } }, "responses": { "200": { "description": "The existing or created actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsGetOrCreateResponse" } } } }, "400": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "invalid_name", "message": "Actor name must be 1 to 64 bytes." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "415": { "description": "The request is missing the `Content-Type: application/json` header. Returned as plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "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": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including `input` that is not valid base64 and a create that did not finish within 30 seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/actors/names": { "get": { "tags": [ "actors::list_names" ], "summary": "Lists the actor names that the namespace's connected nodes accept.", "operationId": "actors_list_names", "parameters": [ { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "responses": { "200": { "description": "The actor names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsListNamesResponse" } } } }, "400": { "description": "`envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_namespace_name", "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`auth.insufficient_permissions`: the token's grants do not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "namespace", "code": "not_found", "message": "The namespace does not exist." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure. Details are only logged on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/actors/{actor_id}": { "get": { "tags": [ "actors::get" ], "summary": "Returns one live actor.", "operationId": "actors_get", "parameters": [ { "name": "actor_id", "in": "path", "required": true, "description": "ID of the actor.", "schema": { "$ref": "#/components/schemas/RivetId" } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "responses": { "200": { "description": "The actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsGetResponse" } } } }, "400": { "description": "`envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_namespace_name", "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`actor.not_found`: the actor does not exist, was destroyed, or belongs to another namespace. `namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "not_found", "message": "The actor does not exist or was destroyed." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including an `actor_id` that is not a valid Rivet ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] }, "delete": { "tags": [ "actors::delete" ], "summary": "Destroys an actor.", "operationId": "actors_delete", "parameters": [ { "name": "actor_id", "in": "path", "required": true, "description": "ID of the actor.", "schema": { "$ref": "#/components/schemas/RivetId" } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "responses": { "200": { "description": "The destroy was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsDeleteResponse" } } } }, "400": { "description": "`envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_namespace_name", "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`actor.not_found`: the actor does not exist or belongs to another namespace. `namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "not_found", "message": "The actor does not exist or was destroyed." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including an `actor_id` that is not a valid Rivet ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/actors/{actor_id}/sleep": { "post": { "tags": [ "actors::sleep" ], "summary": "Puts an actor to sleep. The request body is ignored.", "operationId": "actors_sleep", "parameters": [ { "name": "actor_id", "in": "path", "required": true, "description": "ID of the actor.", "schema": { "$ref": "#/components/schemas/RivetId" } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "responses": { "200": { "description": "The sleep was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsSleepResponse" } } } }, "400": { "description": "`envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_namespace_name", "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`actor.not_found`: the actor does not exist or belongs to another namespace. `namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "not_found", "message": "The actor does not exist or was destroyed." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including an `actor_id` that is not a valid Rivet ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } }, "/actors/{actor_id}/reschedule": { "post": { "tags": [ "actors::reschedule" ], "summary": "Moves an actor to a new allocation. A running or stopping actor is stopped and allocated again, and a sleeping actor is allocated now. An actor that is still starting, or is destroyed, is left as is. The request body is ignored.", "operationId": "actors_reschedule", "parameters": [ { "name": "actor_id", "in": "path", "required": true, "description": "ID of the actor.", "schema": { "$ref": "#/components/schemas/RivetId" } }, { "name": "namespace", "in": "query", "required": false, "description": "Name of the namespace to operate in. Defaults to `default`.", "schema": { "type": "string", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63 } } ], "responses": { "200": { "description": "The reschedule was accepted, or there was nothing to move.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorsRescheduleResponse" } } } }, "400": { "description": "`envoy.invalid_namespace_name`: the `namespace` value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "envoy", "code": "invalid_namespace_name", "message": "Namespace name must be a DNS label of 1 to 63 lowercase letters, digits and hyphens." } } } } }, "401": { "description": "`auth.invalid_token`: the request carries no token, or the token is not valid. `auth.token_expired`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "invalid_token", "message": "Authentication token is invalid." } } } } }, "403": { "description": "`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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "insufficient_permissions", "message": "Insufficient permissions to access this resource." } } } } }, "404": { "description": "`actor.not_found`: the actor does not exist, has no record yet, or belongs to another namespace. `namespace.not_found`: the namespace does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "actor", "code": "not_found", "message": "The actor does not exist or was destroyed." } } } } }, "500": { "description": "`core.internal_error`: an unexpected failure, including an `actor_id` that is not a valid Rivet ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "core", "code": "internal_error", "message": "An internal error occurred" } } } } }, "503": { "description": "`auth.verification_unavailable`: token verification keys are temporarily unavailable. Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse", "example": { "group": "auth", "code": "verification_unavailable", "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request." } } } } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] } } }, "components": { "schemas": { "Actor": { "type": "object", "required": [ "actor_id", "name", "key", "namespace", "pool", "create_ts", "start_ts", "pending_allocation_ts", "connectable_ts", "sleep_ts", "reschedule_ts", "destroy_ts" ], "properties": { "actor_id": { "$ref": "#/components/schemas/RivetId" }, "name": { "type": "string", "description": "Actor name." }, "key": { "type": "string", "description": "Actor key in slash-separated form. An empty string for an actor without a key." }, "namespace": { "type": "string", "description": "Name of the namespace the actor belongs to." }, "pool": { "type": "string", "description": "Name of the node pool the actor runs in." }, "create_ts": { "type": "integer", "format": "int64", "description": "When the actor was created, in Unix milliseconds." }, "start_ts": { "type": [ "integer", "null" ], "format": "int64", "description": "When the actor first started. Not recorded by this version, so always `null`." }, "pending_allocation_ts": { "type": [ "integer", "null" ], "format": "int64", "description": "When the actor started waiting for a node. Not recorded by this version, so always `null`." }, "connectable_ts": { "type": [ "integer", "null" ], "format": "int64", "description": "When the actor last became connectable. Not recorded by this version, so always `null`." }, "sleep_ts": { "type": [ "integer", "null" ], "format": "int64", "description": "When the actor went to sleep. Not recorded by this version, so always `null`." }, "reschedule_ts": { "type": [ "integer", "null" ], "format": "int64", "description": "When the actor will next try to allocate. Not recorded by this version, so always `null`." }, "destroy_ts": { "type": [ "integer", "null" ], "format": "int64", "description": "When the actor was destroyed, in Unix milliseconds. Only set in listings that include destroyed actors; otherwise `null`." } }, "additionalProperties": false }, "ActorName": { "type": "object", "required": [ "metadata" ], "properties": { "metadata": { "type": "object", "additionalProperties": {}, "description": "Metadata for the actor name. Currently always empty." } }, "additionalProperties": false }, "ActorsCreateRequest": { "type": "object", "description": "Unknown fields are ignored.", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Actor name, 1 to 64 bytes." }, "key": { "type": [ "string", "null" ], "maxLength": 1024, "description": "Actor key in canonical slash-separated form, at most 1024 bytes. Omit for an actor without a key." }, "input": { "type": [ "string", "null" ], "description": "Actor input as standard base64 (with padding)." }, "pool": { "type": [ "string", "null" ], "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "description": "Name of the node pool to run the actor in. Defaults to `default`." } } }, "ActorsCreateResponse": { "type": "object", "required": [ "actor", "created" ], "properties": { "actor": { "$ref": "#/components/schemas/Actor" }, "created": { "type": "boolean", "description": "Always `true`." } }, "additionalProperties": false }, "ActorsDeleteResponse": { "type": "object", "additionalProperties": false }, "ActorsGetOrCreateRequest": { "type": "object", "description": "Unknown fields are ignored.", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Actor name, 1 to 64 bytes." }, "key": { "type": [ "string", "null" ], "maxLength": 1024, "description": "Actor key in canonical slash-separated form, at most 1024 bytes. Without a key, a new actor is always created." }, "input": { "type": [ "string", "null" ], "description": "Actor input as standard base64 (with padding)." }, "pool": { "type": [ "string", "null" ], "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "description": "Name of the node pool to run the actor in. Defaults to `default`." } } }, "ActorsGetOrCreateResponse": { "type": "object", "required": [ "actor", "created" ], "properties": { "actor": { "$ref": "#/components/schemas/Actor" }, "created": { "type": "boolean", "description": "`true` if this request created the actor, `false` if it already existed." } }, "additionalProperties": false }, "ActorsGetResponse": { "type": "object", "required": [ "actor" ], "properties": { "actor": { "$ref": "#/components/schemas/Actor" } }, "additionalProperties": false }, "ActorsListNamesResponse": { "type": "object", "required": [ "names" ], "properties": { "names": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ActorName" }, "propertyNames": { "type": "string" }, "description": "Map from actor name to its metadata." } }, "additionalProperties": false }, "ActorsListResponse": { "type": "object", "required": [ "actors", "pagination" ], "properties": { "actors": { "type": "array", "items": { "$ref": "#/components/schemas/Actor" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "ActorsRescheduleResponse": { "type": "object", "additionalProperties": false }, "ActorsSleepResponse": { "type": "object", "additionalProperties": false }, "AuthOperationKind": { "type": "string", "enum": [ "read", "update", "list", "create", "delete" ] }, "AuthResourceKind": { "type": "string", "enum": [ "namespace", "actor", "node", "pool", "datacenter", "actor_gateway", "actor_kv" ], "description": "Resource type a grant applies to." }, "AuthTargetScope": { "description": "`\"any\"` for every resource of the type, or `{ \"id\": \"...\" }` for one resource.", "oneOf": [ { "type": "string", "enum": [ "any" ] }, { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/RivetId" } }, "additionalProperties": false } ] }, "AuthTokenCreateRequest": { "type": "object", "required": [ "namespace", "grants" ], "properties": { "namespace": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "description": "Name of the namespace the token is scoped to. It must exist." }, "duration": { "type": [ "integer", "null" ], "format": "int64", "minimum": 1, "description": "Token lifetime in seconds, from 1 to the deployment's maximum. Defaults to the deployment's configured duration." }, "subject": { "type": [ "string", "null" ], "description": "Opaque identifier of the end user, at most 256 UTF-8 bytes. Only used for correlation." }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/AuthTokenGrant" }, "minItems": 1, "maxItems": 32, "description": "Access the token carries within its namespace." } }, "additionalProperties": false }, "AuthTokenCreateResponse": { "type": "object", "required": [ "token", "issued_ts", "expires_ts" ], "properties": { "token": { "type": "string", "description": "The signed JWT.", "example": "eyJ..." }, "issued_ts": { "type": "integer", "format": "int64", "description": "When the token was issued, in Unix milliseconds." }, "expires_ts": { "type": "integer", "format": "int64", "description": "When the token expires, in Unix milliseconds." } }, "additionalProperties": false }, "AuthTokenGrant": { "type": "object", "required": [ "resource", "target", "operations" ], "properties": { "resource": { "$ref": "#/components/schemas/AuthResourceKind" }, "target": { "$ref": "#/components/schemas/AuthTargetScope" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/AuthOperationKind" }, "minItems": 1, "maxItems": 5, "description": "Operations the grant allows on the target." } }, "additionalProperties": false }, "AuthTokenInspectResponse": { "type": "object", "required": [ "namespace", "subject", "grants", "issued_ts", "expires_ts" ], "properties": { "namespace": { "type": "string", "description": "Name of the namespace the token is scoped to." }, "subject": { "type": [ "string", "null" ], "description": "Subject attached to the token, or `null`." }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/AuthTokenGrant" }, "description": "Access the token carries." }, "issued_ts": { "type": "integer", "format": "int64", "description": "When the token was issued, in Unix milliseconds." }, "expires_ts": { "type": "integer", "format": "int64", "description": "When the token expires, in Unix milliseconds." } }, "additionalProperties": false }, "Datacenter": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Datacenter name.", "example": "default" } }, "additionalProperties": false }, "DatacentersListResponse": { "type": "object", "required": [ "datacenters" ], "properties": { "datacenters": { "type": "array", "items": { "$ref": "#/components/schemas/Datacenter" } } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "description": "A structured error. The response also carries an `x-rivet-error: .` header.", "required": [ "group", "code", "message" ], "properties": { "group": { "type": "string", "description": "Error group, for example `actor`." }, "code": { "type": "string", "description": "Error code within the group, for example `not_found`." }, "message": { "type": "string", "description": "Human-readable error message." }, "metadata": { "description": "Extra details. Only present on some errors raised while authenticating or authorizing the request." } } }, "MetadataGetResponse": { "type": "object", "required": [ "runtime", "version", "envoyProtocolVersion" ], "properties": { "runtime": { "type": "string", "enum": [ "engine" ], "description": "Always `engine`." }, "version": { "type": "string", "description": "Version of the control plane." }, "envoyProtocolVersion": { "type": "integer", "format": "int32", "minimum": 0, "description": "Version of the protocol nodes use to connect to the control plane." }, "actorNames": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ActorName" }, "propertyNames": { "type": "string" }, "description": "Actor names the default namespace's connected nodes accept. Only present for requests made with the admin token." } }, "additionalProperties": false }, "Namespace": { "type": "object", "required": [ "name", "create_ts" ], "properties": { "name": { "type": "string", "description": "Namespace name.", "example": "my-namespace" }, "create_ts": { "type": "integer", "format": "int64", "description": "When the namespace was created, in Unix milliseconds." } }, "additionalProperties": false }, "NamespaceListResponse": { "type": "object", "required": [ "namespaces", "pagination" ], "properties": { "namespaces": { "type": "array", "items": { "$ref": "#/components/schemas/Namespace" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "NamespacesCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$", "maxLength": 63, "description": "Immutable namespace name. A DNS label of 1 to 63 lowercase letters, digits and hyphens." } }, "additionalProperties": false }, "NamespacesCreateResponse": { "type": "object", "required": [ "namespace" ], "properties": { "namespace": { "$ref": "#/components/schemas/Namespace" } }, "additionalProperties": false }, "Node": { "type": "object", "required": [ "key", "pool", "namespace", "datacenter", "version", "create_ts", "last_ping_ts", "connected", "stopping" ], "properties": { "key": { "type": "string", "description": "Node key, unique within the pool.", "example": "node-1" }, "pool": { "type": "string", "description": "Name of the node pool." }, "namespace": { "type": "string", "description": "Name of the namespace." }, "datacenter": { "type": "string", "description": "Datacenter name.", "example": "default" }, "version": { "type": "integer", "format": "int64", "description": "Version the node announced when it connected. New actors are placed only on nodes at the newest version with a connected node in the pool.", "example": 3 }, "create_ts": { "type": "integer", "format": "int64", "description": "When the node connected, in Unix milliseconds." }, "last_ping_ts": { "type": "integer", "format": "int64", "description": "When the node last sent a heartbeat, in Unix milliseconds." }, "connected": { "type": "boolean", "description": "Whether the node is connected." }, "stopping": { "type": "boolean", "description": "Whether the node is shutting down." } }, "additionalProperties": false }, "Pagination": { "type": "object", "required": [ "cursor" ], "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when there are no more results." } }, "additionalProperties": false }, "Pool": { "type": "object", "required": [ "name", "drain_on_version_upgrade", "actor_eviction_delay", "actor_eviction_period", "actor_eviction_rate", "metadata" ], "properties": { "name": { "type": "string", "description": "Name of the node pool.", "example": "default" }, "drain_on_version_upgrade": { "type": "boolean", "description": "Drain nodes running an older version when a newer version connects." }, "actor_eviction_delay": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 86400, "description": "Seconds to wait before evicting actors from a draining node." }, "actor_eviction_period": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 86400, "description": "Seconds over which actors are evicted from a draining node." }, "actor_eviction_rate": { "type": "number", "format": "double", "exclusiveMinimum": 0, "description": "Rate at which actors are evicted from a draining node. Must be finite and greater than 0." }, "metadata": { "description": "Opaque JSON stored with the pool, or `null` when unset.", "example": null } }, "additionalProperties": false }, "PoolResponse": { "type": "object", "required": [ "pool" ], "properties": { "pool": { "$ref": "#/components/schemas/Pool" } } }, "PoolUpsertRequest": { "type": "object", "description": "Every field is optional. Unknown fields are rejected.", "properties": { "drain_on_version_upgrade": { "type": "boolean", "default": false, "description": "Drain nodes running an older version when a newer version connects." }, "actor_eviction_delay": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 86400, "default": 0, "description": "Seconds to wait before evicting actors from a draining node." }, "actor_eviction_period": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 86400, "default": 0, "description": "Seconds over which actors are evicted from a draining node." }, "actor_eviction_rate": { "type": "number", "format": "double", "exclusiveMinimum": 0, "default": 1, "description": "Rate at which actors are evicted from a draining node. Must be finite and greater than 0." }, "metadata": { "description": "Opaque JSON stored with the pool, at most 16 KiB when serialized." } }, "additionalProperties": false }, "PoolsDeleteResponse": { "type": "object", "additionalProperties": false }, "PoolsListNodesResponse": { "type": "object", "required": [ "nodes", "pagination" ], "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/Node" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "PoolsListResponse": { "type": "object", "required": [ "pools", "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" }, "pools": { "type": "array", "items": { "$ref": "#/components/schemas/Pool" } } }, "additionalProperties": false }, "RivetId": { "type": "string", "description": "A Rivet ID: 30 lowercase base36 characters.", "example": "d97pbq1nyqxw1w5qdwz0iirbqiblh2" } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer", "description": "The admin token or a namespace JWT from `POST /auth/tokens`." }, "rivet_token_header": { "type": "apiKey", "in": "header", "name": "x-rivet-token", "description": "The same token sent in the `x-rivet-token` header instead of `Authorization`." } } }, "security": [ { "bearer_auth": [] }, { "rivet_token_header": [] } ] }