{ "info": { "title": "UniCAS Space API", "version": "1.0.0", "description": "App-scoped Space API for immutable content-addressed nodes, leases, usage accounting, garbage collection, and atomic Root Ref commits.\n\nEvery request uses a version 1 JWT capability on the version 1 HTTP API. The registered issuer establishes App authority; the token's signed `spaceId` must match the route and its exact operation permission must authorize the request.\n\nPrincipal identity and Profile metadata are independent of Space ownership and authorization." }, "servers": [ { "url": "https://api.unicas.work", "description": "Production" } ], "tags": [ { "name": "Nodes", "description": "Read immutable nodes and establish temporary protection leases within a Space." }, { "name": "Root Refs", "description": "Read and atomically update business-root balances in the verified capability's refDomain." }, { "name": "Operations", "description": "Inspect Space accounting and run bounded garbage collection." } ], "security": [ { "spaceCapability": [] } ], "components": { "securitySchemes": { "spaceCapability": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Version 1 Space capability. Issuer authority and signed spaceId must match the request path, and the permission set must contain the operation's exact CAS authority." } } }, "openapi": "3.1.1", "paths": { "/v1/apps/{appId}/spaces/{spaceId}/cas/nodes/{hash}/content": { "get": { "operationId": "readContent", "summary": "Read immutable node content", "description": "Streams canonical bytes for a ready node in the requested Space. Requires cas:nodes:read.", "tags": [ "Nodes" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "App that establishes issuer authority and storage isolation." } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Space authorized by the capability for this request." } }, { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase SHA-256 content digest." } } ], "responses": { "200": { "description": "OK", "content": {} }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PAYLOAD_TOO_LARGE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "RESOURCE_EXHAUSTED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{appId}/spaces/{spaceId}/cas/nodes/{hash}/metadata": { "get": { "operationId": "readMetadata", "summary": "Read node metadata", "description": "Returns immutable metadata and mutable retention state for one Space node. Requires cas:nodes:read.", "tags": [ "Nodes" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "App that establishes issuer authority and storage isolation." } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Space authorized by the capability for this request." } }, { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase SHA-256 content digest." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Digest that identifies this immutable node." }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Logical content length in bytes." }, "contentType": { "type": "string", "minLength": 1, "description": "Media type recorded for the immutable content." }, "refs": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of canonical CAS node bytes." }, "readOnly": true, "description": "Ordered child-node digests." } }, "required": [ "hash", "size", "contentType", "refs" ], "readOnly": true }, "state": { "type": "object", "properties": { "leaseStartedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Start of the current uninterrupted lease period." }, "leaseExpiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Deadline before which collection cannot delete the node." }, "childRefCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Stored parent edges that reference this node." }, "rootRefCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Aggregate business Root Ref balance for this node." } }, "required": [ "leaseStartedAt", "leaseExpiresAt", "childRefCount", "rootRefCount" ], "readOnly": true } }, "required": [ "metadata", "state" ], "readOnly": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PAYLOAD_TOO_LARGE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "RESOURCE_EXHAUSTED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{appId}/spaces/{spaceId}/cas/nodes/{hash}/lease": { "post": { "operationId": "leaseNode", "summary": "Lease a node", "description": "Advances the lease-driven node state machine and returns the resulting ready, upload, replacement-upload, or dependency state. Requires cas:nodes:lease.", "tags": [ "Nodes" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "App that establishes issuer authority and storage isolation." } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Space authorized by the capability for this request." } }, { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase SHA-256 content digest." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "leaseDurationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Requested lease duration in milliseconds." } }, "required": [ "leaseDurationMs" ], "readOnly": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of canonical CAS node bytes." }, "state": { "const": "ready" }, "leaseStartedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Unix timestamp in milliseconds since 1970-01-01T00:00:00Z." }, "leaseExpiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Unix timestamp in milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "hash", "state", "leaseStartedAt", "leaseExpiresAt" ], "readOnly": true }, { "type": "object", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of canonical CAS node bytes." }, "state": { "const": "awaiting_upload" }, "upload": { "type": "object", "properties": { "method": { "const": "PUT" }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Unix timestamp in milliseconds since 1970-01-01T00:00:00Z." }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "readOnly": true } }, "required": [ "method", "url", "expiresAt", "headers" ], "readOnly": true } }, "required": [ "hash", "state", "upload" ], "readOnly": true }, { "type": "object", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of canonical CAS node bytes." }, "state": { "const": "awaiting_replacement_upload" }, "rejection": { "type": "object", "properties": { "code": { "enum": [ "NODE_TOO_LARGE", "NODE_DIGEST_MISMATCH", "INVALID_CANONICAL_NODE", "NODE_CONFLICT" ], "type": "string" }, "message": { "type": "string", "minLength": 1 } }, "required": [ "code", "message" ], "readOnly": true }, "upload": { "type": "object", "properties": { "method": { "const": "PUT" }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Unix timestamp in milliseconds since 1970-01-01T00:00:00Z." }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "readOnly": true } }, "required": [ "method", "url", "expiresAt", "headers" ], "readOnly": true } }, "required": [ "hash", "state", "rejection", "upload" ], "readOnly": true }, { "type": "object", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of canonical CAS node bytes." }, "state": { "const": "validated_awaiting_children" }, "childHashes": { "type": "array", "minItems": 1, "maxItems": 256, "items": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of canonical CAS node bytes." }, "readOnly": true } }, "required": [ "hash", "state", "childHashes" ], "readOnly": true } ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PAYLOAD_TOO_LARGE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "RESOURCE_EXHAUSTED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{appId}/spaces/{spaceId}/cas/usage": { "get": { "operationId": "getUsage", "summary": "Read Space CAS usage", "description": "Returns current operational accounting for one Space. Requires cas:usage:read.", "tags": [ "Operations" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "App that establishes issuer authority and storage isolation." } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Space authorized by the capability for this request." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "nodeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Node metadata rows owned by the Space." }, "readyContentBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Logical bytes with ready canonical content." }, "readyStoredBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Physical bytes attributed to ready content." }, "reservedBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Known bytes reserved by validated or server-mediated incomplete uploads; pre-validation direct R2 bytes are excluded." }, "notReadyNodeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Nodes without ready canonical content." }, "leasedNodeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Nodes protected by an unexpired lease." } }, "required": [ "nodeCount", "readyContentBytes", "readyStoredBytes", "reservedBytes", "notReadyNodeCount", "leasedNodeCount" ], "readOnly": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PAYLOAD_TOO_LARGE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "RESOURCE_EXHAUSTED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{appId}/spaces/{spaceId}/cas/gc": { "post": { "operationId": "runGc", "summary": "Run Space garbage collection", "description": "Runs one bounded and race-safe garbage-collection pass within the Space. Requires cas:gc:execute.", "tags": [ "Operations" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "App that establishes issuer authority and storage isolation." } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Space authorized by the capability for this request." } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxNodes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 } }, "readOnly": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "examined": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deleted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reclaimedContentBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "examined", "deleted", "reclaimedContentBytes" ], "readOnly": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PAYLOAD_TOO_LARGE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "RESOURCE_EXHAUSTED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{appId}/spaces/{spaceId}/root-refs": { "get": { "operationId": "listRootRefs", "summary": "List Space Root Ref balances", "description": "Returns a revision-stable page for the refDomain in the verified capability. Requires cas:root-refs:read and a valid signed refDomain.", "tags": [ "Root Refs" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "App that establishes issuer authority and storage isolation." } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Space authorized by the capability for this request." } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1 }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "refDomain": { "type": "string", "minLength": 1, "description": "Business lifecycle namespace from the verified capability." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Stable snapshot revision represented by this page." }, "items": { "type": "array", "items": { "type": "object", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of canonical CAS node bytes." }, "refCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hash", "refCount" ], "readOnly": true }, "readOnly": true }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "refDomain", "revision", "items", "nextCursor" ], "readOnly": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PAYLOAD_TOO_LARGE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "RESOURCE_EXHAUSTED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "updateRootRefs", "summary": "Apply Space Root Ref changes", "description": "Atomically applies signed Root Ref deltas in the capability's refDomain. Requires cas:root-refs:update and a valid signed refDomain.", "tags": [ "Root Refs" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "App that establishes issuer authority and storage isolation." } }, { "name": "spaceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Space authorized by the capability for this request." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable idempotency identity for this commit." }, "changes": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "additionalProperties": { "type": "integer", "minimum": -1000000, "maximum": 1000000, "not": { "const": 0 } }, "readOnly": true, "minProperties": 1, "maxProperties": 1000, "description": "One to 1,000 non-zero signed Root Ref deltas keyed by lowercase SHA-256 digest." } }, "required": [ "requestId", "changes" ], "readOnly": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "idempotent": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "success", "idempotent", "revision" ], "readOnly": true } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "FORBIDDEN" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "CONFLICT" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "413", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "PAYLOAD_TOO_LARGE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "RESOURCE_EXHAUSTED" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string" } }, "required": [ "error" ] } } } } } } } } }