{ "openapi": "3.1.0", "info": { "title": "AlphaBox Owner Files Public API", "version": "1.0.0", "description": "API keys access only their owner’s files and allowance. Account and key management require browser sessions. Decimal byte limits; ISO 8601 UTC timestamps. Never forward Authorization to presigned R2 URLs. Upload URL PUT requests are separate from this API; local=true uses this trusted API origin. Production origins must be configured explicitly." }, "servers": [ { "url": "https://api.alphabox.fyi", "description": "Production preview; operations may be temporarily unavailable" } ], "tags": [ { "name": "account:read" }, { "name": "files:read" }, { "name": "files:write" }, { "name": "files:delete" }, { "name": "shares:write" }, { "name": "files:download" } ], "paths": { "/v1/me/storage": { "get": { "operationId": "getvmestorage", "summary": "Inspect own growth limits and used/reserved bytes", "tags": [ "account:read" ], "security": [ { "bearer": [] } ], "x-required-scope": "account:read", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Storage" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads": { "post": { "operationId": "postvuploads", "summary": "Reserve quota and initiate multipart upload", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[\\w-]+$" }, "description": "Persist across retries. Owner and operation scoped. Initiation binds filename and size; verify local content before resume. Repeated extension keys never add another extension." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Initiate" } } } } }, "get": { "operationId": "getvuploads", "summary": "List up to three resumable active uploads", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } } }, "required": [ "uploads" ], "additionalProperties": false } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads/{id}": { "get": { "operationId": "getvuploadsid", "summary": "Inspect own upload and acknowledged parts", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deletevuploadsid", "summary": "Cancel unfinished upload and release reservation", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads/{id}/parts": { "post": { "operationId": "postvuploadsidparts", "summary": "Authorize exact PUT parts for five minutes", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartUrls" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partNumbers": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "type": "integer", "minimum": 1 } } }, "required": [ "partNumbers" ], "additionalProperties": false } } } } } }, "/v1/uploads/{id}/parts/{number}/ack": { "post": { "operationId": "postvuploadsidpartsnumberack", "summary": "Record ETag after successful part PUT", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "etag": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "etag" ], "additionalProperties": false } } } } } }, "/v1/uploads/{id}/complete": { "post": { "operationId": "postvuploadsidcomplete", "summary": "Complete or recover a completed object idempotently", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files": { "get": { "operationId": "getvfiles", "summary": "List own files with opaque cursor pagination", "tags": [ "files:read" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "files", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{id}": { "get": { "operationId": "getvfilesid", "summary": "Inspect own file, including unavailable metadata", "tags": [ "files:read" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deletevfilesid", "summary": "Make own file inaccessible and schedule irreversible deletion", "tags": [ "files:delete" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{id}/extend": { "post": { "operationId": "postvfilesidextend", "summary": "Add seven days in final 72 hours, at most three times", "tags": [ "files:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[\\w-]+$" }, "description": "Persist across retries. Owner and operation scoped. Initiation binds filename and size; verify local content before resume. Repeated extension keys never add another extension." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{id}/share": { "patch": { "operationId": "patchvfilesidshare", "summary": "Change enabled state/password and revoke prior grants", "tags": [ "shares:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "shares:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "password": { "anyOf": [ { "type": "string", "minLength": 8, "maxLength": 128 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false, "anyOf": [ { "required": [ "enabled" ] }, { "required": [ "password" ] } ] } } } } } }, "/v1/files/{id}/share/regenerate": { "post": { "operationId": "postvfilesidshareregenerate", "summary": "Replace share token and revoke previous grants", "tags": [ "shares:write" ], "security": [ { "bearer": [] } ], "x-required-scope": "shares:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{id}/download": { "get": { "operationId": "getvfilesiddownload", "summary": "Stream own currently available file; supports one byte range", "tags": [ "files:download" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:download", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "Single byte range only, for example bytes=0-1023 or bytes=-512." } ], "responses": { "200": { "description": "Attachment with Content-Length, Content-Disposition, Accept-Ranges and no-store", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial content; Content-Range describes actual bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Invalid or unsatisfiable range; empty body", "headers": { "Content-Range": { "schema": { "type": "string" }, "description": "bytes */" } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "operationId": "headvfilesiddownload", "summary": "Stream own currently available file; supports one byte range", "tags": [ "files:download" ], "security": [ { "bearer": [] } ], "x-required-scope": "files:download", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "Single byte range only, for example bytes=0-1023 or bytes=-512." } ], "responses": { "200": { "description": "Attachment with Content-Length, Content-Disposition, Accept-Ranges and no-store" }, "206": { "description": "Partial content; Content-Range describes actual bytes" }, "400": { "description": "Invalid body, byte size, or required idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid, expired, or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or inactive account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is absent or not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Quota, lifecycle, concurrency, or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "File expired, deleted, or no longer available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File or request exceeds limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Invalid or unsatisfiable range; empty body", "headers": { "Content-Range": { "schema": { "type": "string" }, "description": "bytes */" } } }, "429": { "description": "Rate limited; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry" } } }, "500": { "description": "Internal failure; retry only safe operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage configuration/provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Scoped expiring abx_ API key. One-time display; never put into URLs." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Storage": { "type": "object", "properties": { "ageDays": { "type": "integer", "minimum": 0 }, "storageLimit": { "type": "integer", "minimum": 0 }, "fileLimit": { "type": "integer", "minimum": 0 }, "nextIncreaseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "usedBytes": { "type": "integer", "minimum": 0 }, "reservedBytes": { "type": "integer", "minimum": 0 }, "availableBytes": { "type": "integer", "minimum": 0 } }, "required": [ "ageDays", "storageLimit", "fileLimit", "nextIncreaseAt", "usedBytes", "reservedBytes", "availableBytes" ], "additionalProperties": false }, "File": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "completedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "extensionCount": { "type": "integer", "minimum": 0, "maximum": 3 }, "state": { "type": "string", "enum": [ "active", "expired_pending_cleanup", "deleted_pending_cleanup", "deleted" ] }, "enabled": { "type": "boolean" }, "passwordRequired": { "type": "boolean" }, "shareUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canExtend": { "type": "boolean" } }, "required": [ "id", "filename", "size", "completedAt", "expiresAt", "extensionCount", "state", "enabled", "passwordRequired", "shareUrl", "canExtend" ], "additionalProperties": false }, "Part": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "etag": { "type": "string" } }, "required": [ "partNumber", "etag" ], "additionalProperties": false }, "Upload": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "partSize": { "type": "integer", "minimum": 0 }, "partCount": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "initiating", "uploading", "completing", "completed", "abort_pending", "aborted" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/Part" } } }, "required": [ "id", "filename", "size", "partSize", "partCount", "status", "expiresAt", "parts" ], "additionalProperties": false }, "Initiate": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "No path separators or control characters." }, "size": { "type": "integer", "minimum": 1, "maximum": 1000000000, "description": "Declared total size in decimal bytes; current owner limit may be lower." } }, "required": [ "filename", "size" ], "additionalProperties": false }, "PartUrls": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "local": { "type": "boolean" }, "method": { "type": "string", "const": "PUT" }, "size": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "partNumber", "url", "headers", "local", "method", "size", "expiresAt" ], "additionalProperties": false } } }, "required": [ "parts" ], "additionalProperties": false }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }