{ "openapi": "3.1.0", "info": { "title": "Wabe Cloud API", "version": "0.1.0", "description": "Manage projects, route requests to actor instances, and use project-scoped disks. Base URL: https://api.wabe.sh. [Download the OpenAPI schema](/openapi-cloud.json)." }, "security": [ { "bearerAuth": [] } ], "paths": { "/health": { "get": { "operationId": "health", "summary": "Check the server", "tags": [ "System" ], "responses": { "200": { "description": "Gateway is responding.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "ok\n" } } } }, "security": [] } }, "/v1/disks/{disk}/files/{path}": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "description": "Virtual file path relative to root; may contain slash-separated components.", "example": "notes.txt" } } ], "get": { "operationId": "readFile", "summary": "Read a file", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Exact file bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input, query, name or source.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Requested file, parent or script was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "put": { "operationId": "writeFile", "summary": "Replace a file", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Complete replacement published according to configured durability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteResult" } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "expected_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_revision", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body -X PUT 'https://api.wabe.sh/v1/disks/demo/files/notes.txt' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY' \\\n -H 'Content-Type: application/octet-stream' \\\n --data-binary @./notes.txt" } ] }, "post": { "operationId": "appendFile", "summary": "Append streamed bytes to current EOF", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Byte count and updated metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteResult" } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "expected_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_revision", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body -X POST 'https://api.wabe.sh/v1/disks/demo/files/notes.txt' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY' \\\n -H 'Content-Type: application/octet-stream' \\\n --data-binary @./notes.txt" } ] }, "delete": { "operationId": "removeFile", "summary": "Remove file or empty directory", "tags": [ "Filesystem" ], "responses": { "204": { "description": "File or empty directory removed." }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/entries": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "listEntries", "summary": "List direct directory children", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Newline-delimited JSON records; consume or close the body to release the request lease.", "content": { "application/x-ndjson": { "schema": { "type": "string", "x-record-schema": "#/components/schemas/Entry" }, "example": "{\"path\":\"/notes.txt\",\"metadata\":{\"version\":2,\"object_id\":\"1a99088e-bfec-4eec-87e4-19ba5acf29e1\",\"version_id\":\"f75f43ae-8375-48f0-8bcd-862cb75c26ef\",\"branch_id\":\"8ec08f61-c6b4-4f3a-83e9-d46ae3e5bc30\",\"revision\":1,\"first_edit_at_ms\":1794225600000,\"last_edit_at_ms\":1794225600000,\"mode\":33188,\"kind\":{\"File\":{\"content_root\":null,\"size\":0,\"chunk_bytes\":65536}}}}\n" } } }, "400": { "description": "Invalid input, query, name or source.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Requested file, parent or script was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "default": "/" } }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/exec": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "post": { "operationId": "execute", "summary": "Execute shell or JavaScript", "tags": [ "Execution" ], "responses": { "200": { "description": "Newline-delimited JSON records; consume or close the body to release the request lease.", "content": { "application/x-ndjson": { "schema": { "type": "string", "x-record-schema": "#/components/schemas/ExecutionRecord" }, "example": "{\"type\":\"stdout\",\"data\":\"SGVsbG8K\"}\n{\"type\":\"exit\",\"code\":0}\n" } } }, "400": { "description": "Invalid input, query, name or source.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Requested file, parent or script was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "description": "Select body, script or path as source. Source limit is 64 KiB. HTTP 200 starts the response; require a final exit record and inspect its code. Runtime failures are stderr/exit records. Default elapsed deadline is 30 seconds. JS runs as an async function body on Linux.", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "bash", "js" ], "default": "bash" } }, { "name": "script", "in": "query", "required": false, "schema": { "type": "string", "description": "UTF-8 source as query text; the body becomes stdin." } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string", "description": "Stored virtual JS source path; requires kind=js. Body becomes stdin." } }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain": { "schema": { "type": "string" }, "example": "echo Hello" }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/kv/{namespace}": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "app" }, "description": "Namespace on this disk." } ], "post": { "operationId": "keyValue", "summary": "Operate on a KV namespace", "tags": [ "KV" ], "responses": { "200": { "description": "JSON response for get/exists/put/delete/batch, NDJSON entries for scan. Missing get returns found:false with HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KvResponse" } }, "application/x-ndjson": { "schema": { "type": "string", "x-record-schema": "#/components/schemas/KvEntry" }, "example": "{\"key\":\"greeting\",\"value\":{\"type\":\"text\",\"value\":\"Hello\"},\"revision\":\"7\"}\n" } } }, "400": { "description": "Invalid input, query, name or source.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "KV size or request-body limit exceeded.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "KV body requires application/json.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "KV JSON shape or operation is unsupported.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "description": "Keys: 16 KiB; values: 1 MiB; encoded batches and JSON bodies: 8 MiB. Scan stays within the namespace and uses byte order with an exclusive after cursor sharing the prefix. TTL is unsupported. Mutations never trigger flush; optional remote mode waits for background/explicit persistence.", "requestBody": { "required": true, "x-max-body-bytes": 8388608, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KvRequest" }, "example": { "op": "scan", "prefix": "greet", "limit": 10 } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/config": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "put": { "operationId": "setChunkSize", "summary": "Set the chunk size for future file writes", "tags": [ "Configuration" ], "responses": { "204": { "description": "Updated; empty body." }, "400": { "description": "Invalid input, query, name or source.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "chunk_bytes", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 4096, "maximum": 4194304, "example": 65536 } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "get": { "operationId": "getStorageConfig", "summary": "Read file storage settings", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Current file storage settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConfig" }, "example": { "chunk_bytes": 65536, "autosave_interval_ms": 10000, "history_retention_ms": 2592000000 } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "patch": { "operationId": "setStorageConfig", "summary": "Set all file storage settings", "tags": [ "Filesystem" ], "responses": { "204": { "description": "Storage settings updated." }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageConfig" }, "example": { "chunk_bytes": 65536, "autosave_interval_ms": 10000, "history_retention_ms": 2592000000 } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/redis/{namespace}": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "app" }, "description": "Namespace on this disk." } ], "post": { "operationId": "postRedisCommand", "summary": "Run a Redis command", "tags": [ "Redis" ], "responses": { "200": { "description": "Command reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisReply" }, "example": { "result": "OK" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisCommand" }, "example": [ "SET", "greeting", "Hello" ] } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } }, { "name": "Upstash-Response-Format", "in": "header", "description": "Reply format. RESP2 requires the default encoding.", "schema": { "type": "string", "enum": [ "json", "resp2" ], "default": "json" } } ] }, "put": { "operationId": "putRedisCommand", "summary": "Run a Redis command", "tags": [ "Redis" ], "responses": { "200": { "description": "Command reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisReply" }, "example": { "result": "OK" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisCommand" }, "example": [ "SET", "greeting", "Hello" ] } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } }, { "name": "Upstash-Response-Format", "in": "header", "description": "Reply format. RESP2 requires the default encoding.", "schema": { "type": "string", "enum": [ "json", "resp2" ], "default": "json" } } ] } }, "/v1/disks/{disk}/redis/{namespace}/{command}": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "app" }, "description": "Namespace on this disk." }, { "name": "command", "in": "path", "required": true, "schema": { "type": "string", "example": "GET/greeting" }, "description": "Slash-separated, URL-encoded command and arguments." } ], "get": { "operationId": "getRedisPath", "summary": "Run a Redis path command", "tags": [ "Redis" ], "responses": { "200": { "description": "Command reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisReply" }, "example": { "result": "Hello" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } }, { "name": "Upstash-Response-Format", "in": "header", "description": "Reply format. RESP2 requires the default encoding.", "schema": { "type": "string", "enum": [ "json", "resp2" ], "default": "json" } } ], "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body 'https://api.wabe.sh/v1/disks/demo/redis/app/GET/greeting' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY'" } ] }, "post": { "operationId": "postRedisPath", "summary": "Run a Redis path command", "tags": [ "Redis" ], "responses": { "200": { "description": "Command reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisReply" }, "example": { "result": "OK" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": {} }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "description": "A nonempty raw body is appended to the arguments, followed by query options.", "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } }, { "name": "Upstash-Response-Format", "in": "header", "description": "Reply format. RESP2 requires the default encoding.", "schema": { "type": "string", "enum": [ "json", "resp2" ], "default": "json" } }, { "name": "command", "in": "path", "required": true, "schema": { "type": "string", "example": "SET/greeting" }, "description": "Slash-separated, URL-encoded command and arguments." } ], "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body -X POST 'https://api.wabe.sh/v1/disks/demo/redis/app/SET/greeting' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY' \\\n -H 'Content-Type: application/octet-stream' \\\n --data-binary 'Hello'" } ] }, "put": { "operationId": "putRedisPath", "summary": "Run a Redis path command", "tags": [ "Redis" ], "responses": { "200": { "description": "Command reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedisReply" }, "example": { "result": "OK" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": {} }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "description": "A nonempty raw body is appended to the arguments, followed by query options.", "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } }, { "name": "Upstash-Response-Format", "in": "header", "description": "Reply format. RESP2 requires the default encoding.", "schema": { "type": "string", "enum": [ "json", "resp2" ], "default": "json" } }, { "name": "command", "in": "path", "required": true, "schema": { "type": "string", "example": "SET/greeting" }, "description": "Slash-separated, URL-encoded command and arguments." } ], "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body -X PUT 'https://api.wabe.sh/v1/disks/demo/redis/app/SET/greeting' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY' \\\n -H 'Content-Type: application/octet-stream' \\\n --data-binary 'Hello'" } ] } }, "/v1/disks/{disk}/notifications": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "readNotifications", "summary": "Read retained changes or subscribe", "tags": [ "Notifications" ], "parameters": [ { "name": "sequence", "in": "query", "schema": { "type": "string" }, "description": "Exclusive opaque cursor; omitted or 0 starts at retained history.", "required": false }, { "name": "sse", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Replay retained history then stream live events with SSE.", "required": false }, { "name": "include_value", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Deliver previously captured content in value_chunk records.", "required": false }, { "name": "entity", "in": "query", "schema": { "type": "string", "enum": [ "file", "kv" ] }, "description": "Restrict the resource kind.", "required": false }, { "name": "file_prefix", "in": "query", "schema": { "type": "string" }, "description": "Literal normalized file-path prefix; cannot combine with namespace.", "required": false }, { "name": "namespace", "in": "query", "schema": { "type": "string" }, "description": "Exact KV namespace; cannot combine with file_prefix.", "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "description": "Finite GET only; maximum examined events, including filtered events.", "required": false }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "string" }, "description": "Cursor fallback when sequence query is omitted." }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A finite NDJSON page or a live SSE stream, selected by sse.", "headers": { "X-Notification-Sequence": { "description": "Journal head at request start.", "schema": { "type": "string" } } }, "content": { "application/x-ndjson": { "schema": { "type": "string" }, "x-record-schema": "#/components/schemas/NotificationRecord", "example": "{\"type\":\"checkpoint\",\"sequence\":\"62ad930b-c1e6-4d3c-ab84-8bf74a025d2f:42\"}\n" }, "text/event-stream": { "schema": { "type": "string", "description": "When sse=true; Last-Event-ID can supply the resume cursor." }, "x-record-schema": "#/components/schemas/NotificationRecord", "example": "event: checkpoint\nid: 62ad930b-c1e6-4d3c-ab84-8bf74a025d2f:42\ndata: {\"type\":\"checkpoint\",\"sequence\":\"62ad930b-c1e6-4d3c-ab84-8bf74a025d2f:42\"}\n\n" } } }, "400": { "description": "Invalid settings, cursor or filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "sequence_expired: reload state and resume from sequence=0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationError" } }, "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationError" } }, "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Notifications closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "post": { "operationId": "configureNotifications", "summary": "Update notification capture and retention", "tags": [ "Notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationUpdate", "type": "object", "properties": { "enabled": { "type": "boolean" }, "retention": { "type": "object", "properties": { "max_count": { "type": [ "integer", "null" ], "minimum": 1 }, "max_bytes": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [], "additionalProperties": false }, "coalesce_window_ms": { "type": "integer", "minimum": 0, "maximum": 60000 }, "include_value": { "type": "boolean" } }, "additionalProperties": false }, "example": { "enabled": true, "retention": { "max_count": 1000 }, "coalesce_window_ms": 0 } } } }, "responses": { "200": { "description": "Updated settings. A supplied retention object replaces the previous one; at least one positive limit is required while enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSettings" } } } }, "400": { "description": "Invalid settings, cursor or filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationError" } }, "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Notifications closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/stat": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "statFile", "summary": "Read object metadata", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Current file or directory metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" }, "example": { "version": 2, "object_id": "1a99088e-bfec-4eec-87e4-19ba5acf29e1", "version_id": "f75f43ae-8375-48f0-8bcd-862cb75c26ef", "branch_id": "8ec08f61-c6b4-4f3a-83e9-d46ae3e5bc30", "revision": 1, "first_edit_at_ms": 1794225600000, "last_edit_at_ms": 1794225600000, "mode": 33188, "kind": { "File": { "content_root": null, "size": 0, "chunk_bytes": 65536 } } } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "example": "/notes.txt" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/mkdir": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "post": { "operationId": "makeDirectory", "summary": "Create directory", "tags": [ "Filesystem" ], "responses": { "204": { "description": "Directory created or already present." }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "example": "/archive" } }, { "name": "recursive", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/move": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "post": { "operationId": "moveEntry", "summary": "Move to exact destination", "tags": [ "Filesystem" ], "responses": { "204": { "description": "Entry moved." }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false }, "example": { "from": "/notes.txt", "to": "/archive/notes.txt" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/branches": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "listBranches", "summary": "List branches", "description": "List the filesystem branches on a disk. Use a branch name in the branch query parameter to select it for file or execution requests.", "tags": [ "Filesystem" ], "responses": { "200": { "description": "One JSON record per branch, separated by newlines.", "content": { "application/x-ndjson": { "schema": { "type": "string" }, "x-record-schema": "#/components/schemas/BranchInfo", "example": "{\"id\":\"8ec08f61-c6b4-4f3a-83e9-d46ae3e5bc30\",\"name\":\"main\",\"root_directory_id\":\"7c8fd44b-019f-4a0c-94bf-627a04d5d07f\",\"revision\":0,\"base_commit\":null,\"head_commit\":null}\n" } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "post": { "operationId": "createBranch", "summary": "Create independently writable branch", "tags": [ "Filesystem" ], "responses": { "200": { "description": "New branch metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchInfo" } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "from": { "type": "string", "format": "uuid" } }, "required": [ "name", "from" ], "additionalProperties": false }, "example": { "name": "work", "from": "7bdd0f94-3d70-4367-8d5d-1cdbec118598" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "delete": { "operationId": "deleteBranch", "summary": "Delete a nondefault branch", "tags": [ "Filesystem" ], "responses": { "204": { "description": "Branch deleted." }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "example": "work" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/commits": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "listCommits", "summary": "List retained workspace commits", "tags": [ "Filesystem" ], "responses": { "200": { "description": "One JSON record per retained commit.", "content": { "application/x-ndjson": { "schema": { "type": "string" }, "x-record-schema": "#/components/schemas/CommitInfo", "example": "{\"id\":\"7bdd0f94-3d70-4367-8d5d-1cdbec118598\",\"branch_id\":\"8ec08f61-c6b4-4f3a-83e9-d46ae3e5bc30\",\"root_directory_id\":\"7c8fd44b-019f-4a0c-94bf-627a04d5d07f\",\"revision\":1,\"base_commit\":null,\"parent_commit\":null,\"created_at_ms\":1794225600000,\"message\":\"Save notes\",\"git_oid\":null,\"parent_commits\":[]}\n" } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "post": { "operationId": "createCommit", "summary": "Seal selected branch and create a commit", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Commit metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitInfo" }, "example": { "id": "7bdd0f94-3d70-4367-8d5d-1cdbec118598", "branch_id": "8ec08f61-c6b4-4f3a-83e9-d46ae3e5bc30", "root_directory_id": "7c8fd44b-019f-4a0c-94bf-627a04d5d07f", "revision": 1, "base_commit": null, "parent_commit": null, "created_at_ms": 1794225600000, "message": "Save notes", "git_oid": null, "parent_commits": [] } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 8192, "default": "" }, "label": { "type": "string" } }, "required": [], "additionalProperties": false }, "example": { "message": "Save notes" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/commits/{commit}": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "commit", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "operationId": "deleteCommit", "summary": "Delete an unreferenced commit", "tags": [ "Filesystem" ], "responses": { "204": { "description": "Commit deleted." }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/history": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "fileHistory", "summary": "List file versions newest first", "tags": [ "Filesystem" ], "responses": { "200": { "description": "One JSON record per file version, newest first.", "content": { "application/x-ndjson": { "schema": { "type": "string" }, "x-record-schema": "#/components/schemas/VersionInfo", "example": "{\"metadata\":{\"version\":2,\"object_id\":\"1a99088e-bfec-4eec-87e4-19ba5acf29e1\",\"version_id\":\"f75f43ae-8375-48f0-8bcd-862cb75c26ef\",\"branch_id\":\"8ec08f61-c6b4-4f3a-83e9-d46ae3e5bc30\",\"revision\":1,\"first_edit_at_ms\":1794225600000,\"last_edit_at_ms\":1794225600000,\"mode\":33188,\"kind\":{\"File\":{\"content_root\":null,\"size\":0,\"chunk_bytes\":65536}}},\"sealed\":true}\n" } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "example": "/notes.txt" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/versions/{version}": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "readFileVersion", "summary": "Read sealed file version", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Bytes of the sealed file version.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/restore": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "post": { "operationId": "restoreFile", "summary": "Restore shared content as a new file state", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Metadata of the restored file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "version": { "type": "string", "format": "uuid" }, "expected_version": { "$ref": "#/components/schemas/VersionMatch" } }, "required": [ "path", "version" ], "additionalProperties": false }, "example": { "path": "/notes.txt", "version": "f75f43ae-8375-48f0-8bcd-862cb75c26ef" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/labels": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "listLabels", "summary": "List explicit pins", "tags": [ "Filesystem" ], "responses": { "200": { "description": "One JSON record per pin.", "content": { "application/x-ndjson": { "schema": { "type": "string" }, "x-record-schema": "#/components/schemas/LabelInfo", "example": "{\"name\":\"daily\",\"target\":{\"kind\":\"commit\",\"id\":\"7bdd0f94-3d70-4367-8d5d-1cdbec118598\"}}\n" } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "put": { "operationId": "pinState", "summary": "Pin a file, directory view or commit", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Pin metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelInfo" } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string" }, "commit": { "type": "string", "format": "uuid" } }, "required": [ "name", "commit" ], "additionalProperties": false } ] }, "example": { "name": "daily", "commit": "7bdd0f94-3d70-4367-8d5d-1cdbec118598" } } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] }, "delete": { "operationId": "deleteLabel", "summary": "Remove a pin", "tags": [ "Filesystem" ], "responses": { "204": { "description": "Pin removed." }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "example": "daily" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/label-content": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "get": { "operationId": "readFileLabel", "summary": "Read pinned file bytes", "tags": [ "Filesystem" ], "responses": { "200": { "description": "Bytes of the pinned file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Object was not found.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Conflict, nonempty destination or referenced object.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Storage, I/O or corruption failure.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "example": "notes" } } ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/sqlite/{database}/hrana/v3/pipeline": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "mydb" } } ], "post": { "operationId": "hranaPipeline", "summary": "Execute a Hrana JSON v3 pipeline", "tags": [ "SQLite" ], "description": "SDK base /v1/disks/{disk}/sqlite/{database}/hrana/. Named databases are independent within a disk. Bearer authentication is required on every continuation. Transaction TTL defaults to 60 seconds, idle sessions outside a transaction to 30 seconds. The previous custom SQL and libsql URI routes are disabled. Protobuf, WebSocket and replication are outside this profile.", "requestBody": { "required": true, "x-max-body-bytes": 4194304, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HranaPipelineRequest" }, "example": { "requests": [ { "type": "execute", "stmt": { "sql": "SELECT 1 AS n" } }, { "type": "close" } ] } } } }, "responses": { "200": { "description": "Protocol results; statement errors can occur inside HTTP 200. SQL COMMIT acknowledges buffered state without an object-store flush. Cursor EOF alone does not commit an open transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HranaPipelineResponse" }, "example": { "baton": null, "base_url": null, "results": [ { "type": "ok", "response": { "type": "execute", "result": { "cols": [ { "name": "n", "decltype": null } ], "rows": [ [ { "type": "integer", "value": "1" } ] ], "affected_row_count": 0, "last_insert_rowid": null } } }, { "type": "ok", "response": { "type": "close" } } ] } } } }, "400": { "description": "Invalid names or protocol request." }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Invalid, expired, wrong-scope or retired-session baton." }, "408": { "description": "SQL execution/admission/backpressure deadline expired." }, "413": { "description": "Request or configured resource limit exceeded." }, "503": { "description": "SQL execution unavailable or storage failure." } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/sqlite/{database}/hrana/v3/cursor": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "database", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "mydb" } } ], "post": { "operationId": "hranaCursor", "summary": "Execute a Hrana JSON v3 cursor", "tags": [ "SQLite" ], "description": "SDK base /v1/disks/{disk}/sqlite/{database}/hrana/. Named databases are independent within a disk. Bearer authentication is required on every continuation. Transaction TTL defaults to 60 seconds, idle sessions outside a transaction to 30 seconds. The previous custom SQL and libsql URI routes are disabled. Protobuf, WebSocket and replication are outside this profile.", "requestBody": { "required": true, "x-max-body-bytes": 4194304, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HranaCursorRequest" }, "example": { "batch": { "steps": [ { "stmt": { "sql": "SELECT 1 AS n" } } ] } } } } }, "responses": { "200": { "description": "Protocol results; statement errors can occur inside HTTP 200. SQL COMMIT acknowledges buffered state without an object-store flush. Cursor EOF alone does not commit an open transaction.", "content": { "application/x-ndjson": { "schema": { "type": "string", "x-record-schema": "#/components/schemas/HranaCursorRecord" }, "example": "{\"base_url\":null,\"baton\":\"YOUR_CURSOR_BATON\"}\n{\"type\":\"step_begin\",\"step\":0,\"cols\":[{\"name\":\"n\",\"decltype\":null}]}\n{\"type\":\"row\",\"row\":[{\"type\":\"integer\",\"value\":\"1\"}]}\n{\"type\":\"step_end\",\"affected_row_count\":0,\"last_insert_rowid\":null}\n{\"type\":\"replication_index\",\"replication_index\":null}\n" } } }, "400": { "description": "Invalid names or protocol request." }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Invalid, expired, wrong-scope or retired-session baton." }, "408": { "description": "SQL execution/admission/backpressure deadline expired." }, "413": { "description": "Request or configured resource limit exceeded." }, "503": { "description": "SQL execution unavailable or storage failure." } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ] } }, "/v1/disks/{disk}/git/info/refs": { "get": { "summary": "Git ref advertisement", "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "service", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "git-upload-pack", "git-receive-pack" ] } } ], "responses": { "200": { "description": "Git protocol response" }, "400": { "description": "Unsupported operation" }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "409": { "description": "Branch conflict" }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "tags": [ "Git" ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "operationId": "advertiseGitRefs" } }, "/v1/disks/{disk}/git/git-upload-pack": { "post": { "summary": "Fetch objects", "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "responses": { "200": { "description": "Git protocol response.", "content": { "application/x-git-upload-pack-result": {} } }, "400": { "description": "Unsupported operation" }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "409": { "description": "Branch conflict" }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "tags": [ "Git" ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "operationId": "uploadGitPack", "requestBody": { "required": true, "content": { "application/x-git-upload-pack-request": {} } }, "x-codeSamples": [ { "lang": "sh", "label": "Git", "source": "git -c \"http.extraHeader=Authorization: Bearer YOUR_PROJECT_API_KEY\" \\\n fetch 'https://api.wabe.sh/v1/disks/demo/git'" } ] } }, "/v1/disks/{disk}/git/git-receive-pack": { "post": { "summary": "Push objects", "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." } ], "responses": { "200": { "description": "Git protocol response.", "content": { "application/x-git-receive-pack-result": {} } }, "400": { "description": "Unsupported operation" }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "409": { "description": "Branch conflict" }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "tags": [ "Git" ], "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "operationId": "receiveGitPack", "requestBody": { "required": true, "content": { "application/x-git-receive-pack-request": {} } }, "x-codeSamples": [ { "lang": "sh", "label": "Git", "source": "git -c \"http.extraHeader=Authorization: Bearer YOUR_PROJECT_API_KEY\" \\\n push 'https://api.wabe.sh/v1/disks/demo/git' HEAD:refs/heads/main" } ] } }, "/v1/disks/{disk}/redis/{namespace}/pipeline": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "app" }, "description": "Namespace on this disk." } ], "post": { "operationId": "postRedisPipeline", "summary": "Run a Redis pipeline", "tags": [ "Redis" ], "responses": { "200": { "description": "One reply per command.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } }, "example": [ { "result": "OK" }, { "result": 1 } ] }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisCommand" } }, "example": [ [ "SET", "count", "0" ], [ "INCR", "count" ] ] } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "description": "Execute commands in order. Other clients can interleave commands.", "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } }, { "name": "Upstash-Response-Format", "in": "header", "description": "Reply format. RESP2 requires the default encoding.", "schema": { "type": "string", "enum": [ "json", "resp2" ], "default": "json" } } ] }, "put": { "operationId": "putRedisPipeline", "summary": "Run a Redis pipeline", "tags": [ "Redis" ], "responses": { "200": { "description": "One reply per command.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } }, "example": [ { "result": "OK" }, { "result": 1 } ] }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisCommand" } }, "example": [ [ "SET", "count", "0" ], [ "INCR", "count" ] ] } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "description": "Execute commands in order. Other clients can interleave commands.", "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } }, { "name": "Upstash-Response-Format", "in": "header", "description": "Reply format. RESP2 requires the default encoding.", "schema": { "type": "string", "enum": [ "json", "resp2" ], "default": "json" } } ] } }, "/v1/disks/{disk}/redis/{namespace}/multi-exec": { "parameters": [ { "name": "disk", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Project disk name, or the disk ID in the actor runtime disk URL." }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "app" }, "description": "Namespace on this disk." } ], "post": { "operationId": "postRedisTransaction", "summary": "Run a Redis transaction", "tags": [ "Redis" ], "responses": { "200": { "description": "One reply per command.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } }, "example": [ { "result": "OK" }, { "result": 1 } ] } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisCommand" } }, "example": [ [ "SET", "count", "0" ], [ "INCR", "count" ] ] } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "description": "Execute commands as one isolated transaction.", "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } } ] }, "put": { "operationId": "putRedisTransaction", "summary": "Run a Redis transaction", "tags": [ "Redis" ], "responses": { "200": { "description": "One reply per command.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } }, "example": [ { "result": "OK" }, { "result": 1 } ] } } }, "400": { "description": "Invalid command, arguments, request shape or encoding.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "401": { "description": "Missing, invalid or revoked project API key, or an invalid runtime access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Actor runtime token does not authorize this disk or instance generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "413": { "description": "wabe Disk request or response limit exceeded.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "500": { "description": "Storage failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedisReply" }, { "type": "array", "items": { "$ref": "#/components/schemas/RedisReply" } } ] } } } }, "503": { "description": "Disk unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedisCommand" } }, "example": [ [ "SET", "count", "0" ], [ "INCR", "count" ] ] } } }, "security": [ { "bearerAuth": [] }, { "runtimeAccess": [] } ], "description": "Execute commands as one isolated transaction.", "parameters": [ { "name": "Upstash-Encoding", "in": "header", "description": "Encoding for byte-string replies.", "schema": { "type": "string", "enum": [ "json", "base64" ], "default": "json" } } ] } }, "/llm.txt": { "get": { "tags": [ "System" ], "operationId": "readCloudIndex", "summary": "Read the Cloud API index", "responses": { "200": { "description": "Cloud API index.", "content": { "text/plain": {} } } }, "security": [] } }, "/v1/disks": { "get": { "tags": [ "Disks" ], "operationId": "listDisks", "summary": "List project disks", "responses": { "200": { "description": "Disks in the current project.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Disk" } }, "example": [ { "name": "demo" } ] } } }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/v1/disks/{disk}": { "parameters": [ { "name": "disk", "in": "path", "required": true, "description": "Disk name in the current project.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" } } ], "get": { "tags": [ "Disks" ], "operationId": "getDisk", "summary": "Read a disk", "responses": { "200": { "description": "Disk metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disk" }, "example": { "name": "demo" } } } }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } }, "put": { "tags": [ "Disks" ], "operationId": "createDisk", "summary": "Create a disk", "responses": { "200": { "description": "New or existing disk.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disk" }, "example": { "name": "demo" } } } }, "400": { "description": "Invalid disk name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "409": { "description": "Organization disk limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "description": "Reserve a disk name in the current project. Data requests activate the disk on demand." } }, "/v1/projects": { "get": { "tags": [ "Projects" ], "operationId": "listProjects", "summary": "List projects", "responses": { "200": { "description": "Projects in the current organization.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } }, "401": { "description": "Missing or invalid dashboard login JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "loginJwt": [] } ] }, "post": { "tags": [ "Projects" ], "operationId": "createProject", "summary": "Create a project", "responses": { "201": { "description": "Project created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Invalid project name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "401": { "description": "Missing or invalid dashboard login JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "409": { "description": "Name already exists in the current organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "loginJwt": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "1–128 UTF-8 bytes after trimming, without control characters." } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "My application" } } } } } }, "/v1/projects/{project}/api-keys": { "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project ID.", "schema": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" } } ], "get": { "tags": [ "Projects" ], "operationId": "listProjectApiKeys", "summary": "List project API keys", "responses": { "200": { "description": "Key metadata.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectApiKey" } } } } }, "401": { "description": "Missing or invalid dashboard login JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Project or key not found in the current organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "loginJwt": [] } ] }, "post": { "tags": [ "Projects" ], "operationId": "createProjectApiKey", "summary": "Create a project API key", "responses": { "201": { "description": "Key metadata and the new bearer secret. Copy the secret from this response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ProjectApiKey" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Project API key. Returned once.", "example": "ncp_YOUR_PROJECT_API_KEY" } }, "required": [ "secret" ] } ] } } } }, "401": { "description": "Missing or invalid dashboard login JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Project or key not found in the current organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "loginJwt": [] } ] } }, "/v1/projects/{project}/api-keys/{key}": { "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project ID.", "schema": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" } }, { "name": "key", "in": "path", "required": true, "description": "API key ID.", "schema": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" } } ], "delete": { "tags": [ "Projects" ], "operationId": "revokeProjectApiKey", "summary": "Revoke a project API key", "responses": { "204": { "description": "Key revoked." }, "401": { "description": "Missing or invalid dashboard login JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Project or key not found in the current organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "loginJwt": [] } ] } }, "/v1/actor": { "get": { "tags": [ "Actors" ], "operationId": "listActors", "summary": "List actor registrations", "responses": { "200": { "description": "Registrations in the current project.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Actor" } } } } }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "503": { "description": "Actor API temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } } } }, "post": { "tags": [ "Actors" ], "operationId": "registerActor", "summary": "Register an actor endpoint", "responses": { "201": { "description": "Actor registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Actor" } } } }, "400": { "description": "Invalid registration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "404": { "description": "Disk not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "409": { "description": "Registration name already exists in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "503": { "description": "Actor API temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } } }, "description": "Register your HTTPS handler. Supply an existing disk only when you also want a fixed-disk public invocation URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "chat" }, "disk": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "chat-state", "description": "Optional default disk for the public invocation URL." }, "endpoint": { "type": "string", "format": "uri", "example": "https://chat.example.com/wabe", "description": "Public HTTPS endpoint with a DNS hostname. A path is allowed. Omit credentials, query and fragment." }, "endpointSecret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$", "writeOnly": true, "description": "Shared secret used to authenticate the Wabe broker to your handler.", "example": "replace_with_a_random_base64url_secret" } }, "required": [ "name", "endpoint", "endpointSecret" ], "additionalProperties": false }, "example": { "name": "chat", "endpoint": "https://chat.example.com/wabe", "endpointSecret": "replace_with_a_random_base64url_secret" } } } } } }, "/v1/actor/{name}": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Registration name in the current project.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "chat" } } ], "get": { "tags": [ "Actors" ], "operationId": "getActor", "summary": "Read an actor registration", "responses": { "200": { "description": "Actor registration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Actor" } } } }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "404": { "description": "Registration not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "503": { "description": "Actor API temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } } } }, "patch": { "tags": [ "Actors" ], "operationId": "updateActor", "summary": "Update an actor endpoint", "responses": { "200": { "description": "Updated registration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Actor" } } } }, "400": { "description": "Invalid update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "404": { "description": "Registration not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "503": { "description": "Actor API temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "format": "uri", "example": "https://chat.example.com/wabe", "description": "Public HTTPS endpoint with a DNS hostname. A path is allowed. Omit credentials, query and fragment." }, "endpointSecret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$", "writeOnly": true, "description": "Shared secret used to authenticate the Wabe broker to your handler.", "example": "replace_with_a_random_base64url_secret" } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "example": { "endpoint": "https://chat.example.com/wabe" } } } } }, "delete": { "tags": [ "Actors" ], "operationId": "deleteActor", "summary": "Delete an actor registration", "responses": { "204": { "description": "Registration deleted." }, "401": { "description": "Missing, invalid or revoked project API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "404": { "description": "Registration not found in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "503": { "description": "Actor API temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } } } } }, "/v1/runtime/sessions/{session}/refresh": { "parameters": [ { "name": "session", "in": "path", "required": true, "description": "Session ID from the actor runtime.", "schema": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" } } ], "post": { "tags": [ "Actors" ], "operationId": "refreshActorSession", "summary": "Refresh an actor session", "responses": { "200": { "description": "Rotated runtime credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorSession" } } } }, "400": { "description": "Invalid or missing Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "401": { "description": "Invalid or expired refresh token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "403": { "description": "Instance generation or disk grant changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "409": { "description": "Session or refresh conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "429": { "description": "Refresh rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } }, "503": { "description": "Actor API temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActorError" } } } } }, "security": [ { "runtimeRefresh": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" }, "description": "Reuse the key when retrying the same refresh." } ] } }, "/v1/actor/{actor_id}/instances/{instance}/fetch": { "parameters": [ { "name": "actor_id", "in": "path", "required": true, "description": "Actor registration ID.", "schema": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" } }, { "name": "instance", "in": "path", "required": true, "description": "Instance name on the selected actor and disk.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "room-1" } } ], "get": { "tags": [ "Actors" ], "operationId": "fetchActorGet", "summary": "GET public actor instance", "responses": { "101": { "description": "WebSocket upgrade." }, "200": { "description": "Handler response. Streaming handlers can return an event stream.", "content": { "text/event-stream": {}, "*/*": {} } }, "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "head": { "tags": [ "Actors" ], "operationId": "fetchActorHead", "summary": "HEAD public actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --head 'https://api.wabe.sh/v1/actor/779742ad-cd09-4e1c-9170-f20968b344d4/instances/room-1/fetch'" } ] }, "post": { "tags": [ "Actors" ], "operationId": "fetchActorPost", "summary": "POST public actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "put": { "tags": [ "Actors" ], "operationId": "fetchActorPut", "summary": "PUT public actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "patch": { "tags": [ "Actors" ], "operationId": "fetchActorPatch", "summary": "PATCH public actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "delete": { "tags": [ "Actors" ], "operationId": "fetchActorDelete", "summary": "DELETE public actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "options": { "tags": [ "Actors" ], "operationId": "fetchActorOptions", "summary": "OPTIONS public actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "trace": { "tags": [ "Actors" ], "operationId": "fetchActorTrace", "summary": "TRACE public actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --request TRACE 'https://api.wabe.sh/v1/actor/779742ad-cd09-4e1c-9170-f20968b344d4/instances/room-1/fetch'" } ] } }, "/v1/actor/{actor_id}/instances/{instance}/fetch/{rest}": { "parameters": [ { "name": "actor_id", "in": "path", "required": true, "description": "Actor registration ID.", "schema": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" } }, { "name": "instance", "in": "path", "required": true, "description": "Instance name on the selected actor and disk.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "room-1" } }, { "name": "rest", "in": "path", "required": true, "description": "Path suffix. Encode each component and preserve slash separators.", "schema": { "type": "string", "example": "messages" } } ], "get": { "tags": [ "Actors" ], "operationId": "fetchActorGetPath", "summary": "GET public actor instance path", "responses": { "101": { "description": "WebSocket upgrade." }, "200": { "description": "Handler response. Streaming handlers can return an event stream.", "content": { "text/event-stream": {}, "*/*": {} } }, "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "head": { "tags": [ "Actors" ], "operationId": "fetchActorHeadPath", "summary": "HEAD public actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --head 'https://api.wabe.sh/v1/actor/779742ad-cd09-4e1c-9170-f20968b344d4/instances/room-1/fetch/messages'" } ] }, "post": { "tags": [ "Actors" ], "operationId": "fetchActorPostPath", "summary": "POST public actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "put": { "tags": [ "Actors" ], "operationId": "fetchActorPutPath", "summary": "PUT public actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "patch": { "tags": [ "Actors" ], "operationId": "fetchActorPatchPath", "summary": "PATCH public actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "delete": { "tags": [ "Actors" ], "operationId": "fetchActorDeletePath", "summary": "DELETE public actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "options": { "tags": [ "Actors" ], "operationId": "fetchActorOptionsPath", "summary": "OPTIONS public actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "trace": { "tags": [ "Actors" ], "operationId": "fetchActorTracePath", "summary": "TRACE public actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [], "description": "The application authenticates the request. Wabe routes the request to the named instance on the registration’s default disk. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --request TRACE 'https://api.wabe.sh/v1/actor/779742ad-cd09-4e1c-9170-f20968b344d4/instances/room-1/fetch/messages'" } ] } }, "/v1/actor/{name}/disks/{disk}/instances/{instance}/fetch": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Registration name in the current project.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "chat" } }, { "name": "disk", "in": "path", "required": true, "description": "Disk name in the current project.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" } }, { "name": "instance", "in": "path", "required": true, "description": "Instance name on the selected actor and disk.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "room-1" } } ], "get": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskGet", "summary": "GET disk-scoped actor instance", "responses": { "101": { "description": "WebSocket upgrade." }, "200": { "description": "Handler response. Streaming handlers can return an event stream.", "content": { "text/event-stream": {}, "*/*": {} } }, "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "head": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskHead", "summary": "HEAD disk-scoped actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --head 'https://api.wabe.sh/v1/actor/chat/disks/demo/instances/room-1/fetch' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY'" } ] }, "post": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskPost", "summary": "POST disk-scoped actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "put": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskPut", "summary": "PUT disk-scoped actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "patch": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskPatch", "summary": "PATCH disk-scoped actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "delete": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskDelete", "summary": "DELETE disk-scoped actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "options": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskOptions", "summary": "OPTIONS disk-scoped actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "trace": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskTrace", "summary": "TRACE disk-scoped actor instance", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --request TRACE 'https://api.wabe.sh/v1/actor/chat/disks/demo/instances/room-1/fetch' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY'" } ] } }, "/v1/actor/{name}/disks/{disk}/instances/{instance}/fetch/{rest}": { "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Registration name in the current project.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "chat" } }, { "name": "disk", "in": "path", "required": true, "description": "Disk name in the current project.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" } }, { "name": "instance", "in": "path", "required": true, "description": "Instance name on the selected actor and disk.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "room-1" } }, { "name": "rest", "in": "path", "required": true, "description": "Path suffix. Encode each component and preserve slash separators.", "schema": { "type": "string", "example": "messages" } } ], "get": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskGetPath", "summary": "GET disk-scoped actor instance path", "responses": { "101": { "description": "WebSocket upgrade." }, "200": { "description": "Handler response. Streaming handlers can return an event stream.", "content": { "text/event-stream": {}, "*/*": {} } }, "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "head": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskHeadPath", "summary": "HEAD disk-scoped actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --head 'https://api.wabe.sh/v1/actor/chat/disks/demo/instances/room-1/fetch/messages' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY'" } ] }, "post": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskPostPath", "summary": "POST disk-scoped actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "put": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskPutPath", "summary": "PUT disk-scoped actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "patch": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskPatchPath", "summary": "PATCH disk-scoped actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "delete": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskDeletePath", "summary": "DELETE disk-scoped actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "requestBody": { "description": "Application-defined request body.", "content": { "*/*": {} } } }, "options": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskOptionsPath", "summary": "OPTIONS disk-scoped actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/)." }, "trace": { "tags": [ "Actors" ], "operationId": "fetchActorOnDiskTracePath", "summary": "TRACE disk-scoped actor instance path", "responses": { "default": { "description": "Handler status, headers and body, or a broker error." } }, "security": [ { "bearerAuth": [] } ], "description": "The project key authorizes the call and selects the namespace. Wabe creates the named disk if needed and consumes the project key before forwarding the request. See the [actor transport protocol](https://docs.wabe.sh/cloud/actor-protocol/).", "x-codeSamples": [ { "lang": "sh", "label": "cURL", "source": "curl --fail-with-body --request TRACE 'https://api.wabe.sh/v1/actor/chat/disks/demo/instances/room-1/fetch/messages' \\\n -H 'Authorization: Bearer YOUR_PROJECT_API_KEY'" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Project API key from the Wabe Dashboard." }, "loginJwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Dashboard login JWT scoped to the organization." }, "runtimeAccess": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Actor runtime access token for the disk URL supplied by the broker." }, "runtimeRefresh": { "type": "http", "scheme": "bearer", "description": "Refresh token from the actor runtime session." } }, "schemas": { "Key": { "oneOf": [ { "type": "string", "maxLength": 16384, "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed." }, { "type": "object", "properties": { "base64": { "type": "string", "contentEncoding": "base64", "maxLength": 21848 } }, "required": [ "base64" ], "additionalProperties": false } ], "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.", "x-max-decoded-bytes": 16384 }, "Value": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "json" }, "value": {} }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "bytes" }, "value": { "type": "string", "contentEncoding": "base64", "maxLength": 1398104 } }, "required": [ "type", "value" ], "additionalProperties": false } ], "description": "At most 1048576 stored UTF-8/decoded payload bytes, excluding the storage type header.", "x-max-stored-bytes": 1048576 }, "Mutation": { "oneOf": [ { "type": "object", "properties": { "op": { "const": "put" }, "key": { "$ref": "#/components/schemas/Key" }, "value": { "$ref": "#/components/schemas/Value" } }, "required": [ "op", "key", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "delete" }, "key": { "$ref": "#/components/schemas/Key" } }, "required": [ "op", "key" ], "additionalProperties": false } ] }, "KvRequest": { "oneOf": [ { "type": "object", "properties": { "op": { "const": "get" }, "key": { "$ref": "#/components/schemas/Key" } }, "required": [ "op", "key" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "exists" }, "key": { "$ref": "#/components/schemas/Key" } }, "required": [ "op", "key" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "delete" }, "key": { "$ref": "#/components/schemas/Key" } }, "required": [ "op", "key" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "put" }, "key": { "$ref": "#/components/schemas/Key" }, "value": { "$ref": "#/components/schemas/Value" } }, "required": [ "op", "key", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "batch" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Mutation" } } }, "required": [ "op", "operations" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "scan" }, "prefix": { "$ref": "#/components/schemas/Key" }, "after": { "$ref": "#/components/schemas/Key" }, "limit": { "type": "integer", "minimum": 0 }, "reverse": { "type": "boolean", "default": false } }, "required": [ "op" ], "additionalProperties": false } ], "discriminator": { "propertyName": "op" } }, "KvEntry": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/Key" }, "value": { "$ref": "#/components/schemas/Value" }, "revision": { "type": "string", "pattern": "^[0-9]+$", "description": "Opaque decimal sequence string." } }, "required": [ "key", "value", "revision" ], "additionalProperties": false }, "Success": { "type": "object", "properties": { "success": { "const": true } }, "required": [ "success" ], "additionalProperties": false }, "Metadata": { "type": "object", "properties": { "version": { "const": 2 }, "kind": { "oneOf": [ { "const": "Directory" }, { "type": "object", "properties": { "File": { "type": "object", "properties": { "size": { "type": "integer", "minimum": 0 }, "chunk_bytes": { "type": "integer", "minimum": 4096, "maximum": 4194304 }, "content_root": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" } }, "required": [ "content_root", "size", "chunk_bytes" ], "additionalProperties": false } }, "required": [ "File" ], "additionalProperties": false } ] }, "object_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "branch_id": { "type": "string", "format": "uuid", "description": "Origin of the version; inherited or imported versions may refer to an internal or deleted branch absent from the branch list." }, "revision": { "type": "integer", "minimum": 0 }, "first_edit_at_ms": { "type": "integer", "minimum": 0 }, "last_edit_at_ms": { "type": "integer", "minimum": 0 }, "mode": { "type": "integer", "enum": [ 16384, 33188, 33261, 40960 ] } }, "required": [ "version", "kind", "object_id", "version_id", "branch_id", "revision", "first_edit_at_ms", "last_edit_at_ms", "mode" ], "additionalProperties": false }, "Entry": { "type": "object", "properties": { "path": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "path", "metadata" ], "additionalProperties": false }, "ExecutionRecord": { "oneOf": [ { "type": "object", "properties": { "type": { "enum": [ "stdout", "stderr" ] }, "data": { "type": "string", "contentEncoding": "base64" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "result" }, "value": {} }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "exit" }, "code": { "type": "integer" } }, "required": [ "type", "code" ], "additionalProperties": false } ] }, "KvResponse": { "oneOf": [ { "$ref": "#/components/schemas/Success" }, { "type": "object", "properties": { "exists": { "type": "boolean" } }, "required": [ "exists" ], "additionalProperties": false }, { "type": "object", "properties": { "found": { "const": false } }, "required": [ "found" ], "additionalProperties": false }, { "type": "object", "properties": { "found": { "const": true }, "entry": { "$ref": "#/components/schemas/KvEntry" } }, "required": [ "found", "entry" ], "additionalProperties": false } ] }, "RedisCommand": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Redis command name followed by positional arguments." }, "RedisReply": { "type": "object", "properties": { "result": {}, "error": { "type": "string" } }, "description": "One result or error envelope. Pipeline/multi return an array of these." }, "NotificationSettings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "retention": { "type": "object", "properties": { "max_count": { "type": [ "integer", "null" ], "minimum": 1 }, "max_bytes": { "type": [ "integer", "null" ], "minimum": 1 } }, "additionalProperties": false, "required": [] }, "coalesce_window_ms": { "type": "integer", "minimum": 0, "maximum": 60000 }, "include_value": { "type": "boolean" } }, "required": [ "enabled", "retention", "coalesce_window_ms", "include_value" ], "additionalProperties": false }, "NotificationUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "retention": { "type": "object", "properties": { "max_count": { "type": [ "integer", "null" ], "minimum": 1 }, "max_bytes": { "type": [ "integer", "null" ], "minimum": 1 } }, "additionalProperties": false }, "coalesce_window_ms": { "type": "integer", "minimum": 0, "maximum": 60000 }, "include_value": { "type": "boolean" } }, "additionalProperties": false }, "NotificationError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "NotificationRecord": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "notification", "checkpoint", "value_chunk", "value_end", "error" ] } }, "description": "NDJSON or SSE data record. Notifications carry sequence, entity (file/kv), operation, revision, resource metadata and value_available. Checkpoints carry sequence. Value chunks carry sequence, offset and base64; value_end carries sequence and bytes. Errors carry code and message." }, "VersionMatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 0 } }, "required": [ "id", "revision" ], "additionalProperties": false }, "WriteResult": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0 }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "bytes", "metadata" ], "additionalProperties": false }, "StorageConfig": { "type": "object", "properties": { "chunk_bytes": { "type": "integer", "minimum": 4096, "maximum": 4194304 }, "autosave_interval_ms": { "type": "integer", "minimum": 0 }, "history_retention_ms": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "chunk_bytes", "autosave_interval_ms", "history_retention_ms" ], "additionalProperties": false }, "BranchInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "root_directory_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 0 }, "base_commit": { "type": [ "string", "null" ], "format": "uuid" }, "head_commit": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "name", "root_directory_id", "revision", "base_commit", "head_commit" ], "additionalProperties": false }, "CommitInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "branch_id": { "type": "string", "format": "uuid" }, "root_directory_id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 0 }, "base_commit": { "type": [ "string", "null" ], "format": "uuid" }, "parent_commit": { "type": [ "string", "null" ], "format": "uuid" }, "created_at_ms": { "type": "integer", "minimum": 0 }, "message": { "type": "string" }, "git_oid": { "type": [ "string", "null" ] }, "parent_commits": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "id", "branch_id", "root_directory_id", "revision", "base_commit", "parent_commit", "created_at_ms", "message", "git_oid", "parent_commits" ], "additionalProperties": false }, "VersionInfo": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/Metadata" }, "sealed": { "type": "boolean" } }, "required": [ "metadata", "sealed" ], "additionalProperties": false }, "LabelInfo": { "type": "object", "properties": { "name": { "type": "string" }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "commit" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "object" }, "version": { "type": "string", "format": "uuid" }, "directory": { "type": "boolean" } }, "required": [ "kind", "version", "directory" ], "additionalProperties": false } ] } }, "required": [ "name", "target" ], "additionalProperties": false }, "GcStats": { "type": "object", "properties": { "reclaimed_bytes": { "type": "integer", "description": "Filesystem blob payload bytes tombstoned, plus removed Redis collection payload bytes during full collection.", "minimum": 0 }, "removed_blobs": { "type": "integer", "minimum": 0 }, "removed_nodes": { "type": "integer", "minimum": 0 }, "removed_versions": { "type": "integer", "minimum": 0 }, "examined_entries": { "type": "integer", "minimum": 0 }, "batches": { "type": "integer", "minimum": 0 }, "removed_index_entries": { "type": "integer", "minimum": 0 } }, "required": [ "reclaimed_bytes", "removed_blobs", "removed_nodes", "removed_versions", "examined_entries", "batches", "removed_index_entries" ], "additionalProperties": false }, "HranaPipelineRequest": { "type": "object", "required": [ "requests" ], "properties": { "baton": { "type": [ "string", "null" ], "description": "Omit or use null for a new session. Pass the latest baton to continue; the SDK rotates tokens. A cursor header baton becomes usable only after body EOF." }, "requests": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "execute", "batch", "sequence", "describe", "get_autocommit", "store_sql", "close_sql", "close" ] } }, "description": "Operation payload follows the Hrana JSON v3 profile; execute has stmt, batch has batch.steps, SQL-cache operations use sql_id and SQL text." } } } }, "HranaCursorRequest": { "type": "object", "required": [ "batch" ], "properties": { "baton": { "type": [ "string", "null" ], "description": "Omit or use null for a new session. Pass the latest baton to continue; the SDK rotates tokens. A cursor header baton becomes usable only after body EOF." }, "batch": { "type": "object", "required": [ "steps" ], "properties": { "steps": { "type": "array", "items": { "type": "object", "required": [ "stmt" ], "properties": { "stmt": { "type": "object", "description": "One sql or sql_id, typed args or named_args, and optional want_rows (default true)." }, "condition": { "type": [ "object", "null" ], "description": "Hrana ok/error/not/and/or/is_autocommit condition; step references point to earlier steps." } } } } } } } }, "HranaPipelineResponse": { "type": "object", "required": [ "baton", "base_url", "results" ], "properties": { "baton": { "type": [ "string", "null" ], "description": "Omit or use null for a new session. Pass the latest baton to continue; the SDK rotates tokens. A cursor header baton becomes usable only after body EOF." }, "base_url": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "ok", "error" ] }, "response": { "type": "object", "description": "Successful operation result, including typed statement values or batch step results/errors." }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "extended_code": { "type": "string" } } } } } } } }, "HranaCursorRecord": { "type": "object", "description": "One NDJSON record: session header (baton/base_url), then Hrana step_begin, row, step_end, step_error or fatal error records. The response is bounded and must be consumed or closed; abandonment closes the session and rolls back an open transaction." }, "GatewayError": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "ActorError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Disk": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "demo" } }, "required": [ "name" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-11-09T12:00:00Z" } }, "required": [ "id", "name", "created_at" ] }, "ProjectApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" }, "project_id": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" }, "display_prefix": { "type": "string", "example": "ncp_abc12345" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-11-09T12:00:00Z" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "example": null } }, "required": [ "id", "project_id", "display_prefix", "created_at", "revoked_at" ] }, "Actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" }, "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "chat" }, "disk": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "example": "chat-state", "description": "Optional default disk for the public invocation URL." }, "endpoint": { "type": "string", "format": "uri", "example": "https://chat.example.com/wabe" }, "fetchUrlTemplate": { "type": "string", "example": "https://api.wabe.sh/v1/actor/chat/disks/{disk}/instances/{instance}/fetch" } }, "required": [ "id", "name", "endpoint", "fetchUrlTemplate" ] }, "ActorSession": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "example": "779742ad-cd09-4e1c-9170-f20968b344d4" }, "accessToken": { "type": "string", "example": "YOUR_RUNTIME_TOKEN" }, "accessExpiresAt": { "type": "integer", "format": "int64", "description": "Unix timestamp in seconds." }, "refreshToken": { "type": "string", "example": "YOUR_RUNTIME_TOKEN" }, "refreshUrl": { "type": "string", "format": "uri", "example": "https://api.wabe.sh/v1/runtime/sessions/779742ad-cd09-4e1c-9170-f20968b344d4/refresh" }, "sessionExpiresAt": { "type": "integer", "format": "int64", "description": "Unix timestamp in seconds." } }, "required": [ "sessionId", "accessToken", "accessExpiresAt", "refreshToken", "refreshUrl", "sessionExpiresAt" ] } } }, "servers": [ { "url": "https://api.wabe.sh" } ], "tags": [ { "name": "Projects" }, { "name": "Actors" }, { "name": "Disks" }, { "name": "Filesystem" }, { "name": "Redis" }, { "name": "SQLite" }, { "name": "Git" }, { "name": "Execution" }, { "name": "KV" }, { "name": "Notifications" }, { "name": "Configuration" }, { "name": "System" } ] }