{ "openapi": "3.1.0", "info": { "title": "Stashbay Upload API", "version": "1.0.0", "description": "Upload files, inspect their status and obtain normal share links using a Bay API key." }, "servers": [ { "url": "https://stashbay.net/api/v1", "description": "This environment" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Generate a key in Bay → Security. Never send the Stashbay key to a presigned storage URL." } } }, "paths": { "/account": { "get": { "operationId": "account", "summary": "Check your account", "description": "Read your storage allowance before uploading. Reserved space for pending uploads is included in storageUsedBytes. Keys and accounts belong to one environment.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "username": { "type": "string" }, "status": { "type": "string" }, "tier": { "type": "string" }, "storageUsedBytes": { "type": "integer", "minimum": 0 }, "storageCapBytes": { "type": "integer", "minimum": 0 }, "storageAvailableBytes": { "type": "integer", "minimum": 0 }, "remoteUploadEnabled": { "type": "boolean" } }, "required": [ "userId", "username", "status", "tier", "storageUsedBytes", "storageCapBytes", "storageAvailableBytes", "remoteUploadEnabled" ] }, "example": { "userId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB", "username": "publisher", "status": "active", "tier": "starter", "storageUsedBytes": 0, "storageCapBytes": 1073741824, "storageAvailableBytes": 1073741824, "remoteUploadEnabled": false } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/uploads/init": { "post": { "operationId": "init", "summary": "Start an upload", "description": "Reserve storage and receive a transfer plan. Files up to 64 MiB use a single PUT; larger files use multipart uploads. Follow the returned strategy, partSize and partCount. Each call creates a new upload, so do not automatically retry an initialization whose response was lost.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 1 }, "mime": { "type": "string" }, "category": { "type": "string" } }, "required": [ "filename", "sizeBytes" ] }, "example": { "filename": "manual.pdf", "sizeBytes": 1048576 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "strategy": { "enum": [ "proxy", "presigned" ] }, "partSize": { "type": "integer", "minimum": 0 }, "partCount": { "type": "integer", "minimum": 0 }, "single": { "type": "boolean" }, "uploadUrl": { "type": [ "string", "null" ] }, "uploadHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "partUrlTemplate": { "type": [ "string", "null" ] }, "expiresIn": { "type": [ "integer", "null" ] } }, "required": [ "fileId", "strategy", "partSize", "partCount", "single", "uploadUrl", "uploadHeaders", "partUrlTemplate", "expiresIn" ] }, "example": { "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB", "strategy": "proxy", "partSize": 1048576, "partCount": 1, "single": true, "uploadUrl": "/api/v1/uploads/object?fileId=01K4J7Y4H8ZQX2W3N5V6R9T0AB", "uploadHeaders": {}, "partUrlTemplate": null, "expiresIn": null } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/uploads/object": { "put": { "operationId": "object", "summary": "Transfer a small file", "description": "For strategy=proxy, PUT the raw file bytes to uploadUrl with your bearer key. Do not wrap them in a form or JSON. For strategy=presigned, PUT to the returned absolute URL instead, without your Stashbay key. Send the exact declared byte length. For a signed single-file PUT, include uploadHeaders from initialization (If-None-Match: *) to prevent replacing received bytes. Both strategies require the completion step.", "parameters": [ { "name": "fileId", "in": "query", "required": true, "description": "The fileId returned by initialization.", "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "etag": { "type": [ "string", "null" ] } }, "required": [ "etag" ] }, "example": { "etag": "returned-object-etag" } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/uploads/parts": { "post": { "operationId": "parts", "summary": "Get multipart URLs", "description": "Request between 1 and 64 consecutive part URLs. Part numbers start at 1 and cannot exceed the plan's partCount. Request another batch as needed; repeating this call refreshes signed URLs for the same pending upload.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "from": { "type": "integer", "minimum": 1 }, "count": { "type": "integer", "minimum": 1, "maximum": 64 } }, "required": [ "fileId", "from", "count" ] }, "example": { "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB", "from": 1, "count": 2 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 0 }, "url": { "type": "string" } }, "required": [ "partNumber", "url" ] } } }, "required": [ "parts" ] }, "example": { "parts": [ { "partNumber": 1, "url": "/api/v1/uploads/part?fileId=01K4J7Y4H8ZQX2W3N5V6R9T0AB&partNumber=1" }, { "partNumber": 2, "url": "/api/v1/uploads/part?fileId=01K4J7Y4H8ZQX2W3N5V6R9T0AB&partNumber=2" } ] } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/uploads/part": { "put": { "operationId": "part", "summary": "Transfer a part", "description": "For proxy uploads, send raw bytes and your bearer key. For presigned uploads, use the returned absolute URL without the key. Each part must equal partSize except the final remainder. Keep each partNumber and ETag; for presigned PUTs, read the ETag response header and remove surrounding quotes. A failed part can be uploaded again with the same number.", "parameters": [ { "name": "fileId", "in": "query", "required": true, "description": "The fileId returned by initialization.", "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "partNumber", "in": "query", "required": true, "description": "A part number from the upload plan.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1, "maximum": 10000 }, "etag": { "type": "string" } }, "required": [ "partNumber", "etag" ] }, "example": { "partNumber": 1, "etag": "returned-part-etag" } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/uploads/complete": { "post": { "operationId": "complete", "summary": "Complete and get a share link", "description": "Call after all bytes have arrived. Multipart uploads require all partNumber/etag pairs in parts; single uploads can omit parts. File screening runs before publication. Repeating completion for an active file returns its current share link without uploading again. shareUrl is the normal download page and may be null if its link has been disabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1, "maximum": 10000 }, "etag": { "type": "string" } }, "required": [ "partNumber", "etag" ] }, "maxItems": 10000 }, "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }, "archivePassword": { "type": "string", "description": "Optional encrypted ZIP password, at most 256 UTF-8 bytes. Used for inspection, never a public share password." } }, "required": [ "fileId" ] }, "example": { "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "filename": { "type": "string" }, "status": { "enum": [ "pending", "active", "blocked", "deleted" ] }, "sizeBytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": [ "string", "null" ] }, "shareUrl": { "type": [ "string", "null" ] } }, "required": [ "fileId", "filename", "status", "sizeBytes", "sha256", "shareUrl" ] }, "example": { "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB", "filename": "manual.pdf", "status": "active", "sizeBytes": 1048576, "sha256": null, "shareUrl": "https://stsh.in/abcdefgh" } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/files/{fileId}": { "get": { "operationId": "file", "summary": "Check file status", "description": "Read only your own file's status and existing share link. Pending files are not downloadable. If completion's response was lost, check here before starting over. When status is active, repeating completion safely recovers or creates the share link.", "parameters": [ { "name": "fileId", "in": "path", "required": true, "description": "The fileId returned by initialization.", "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "filename": { "type": "string" }, "status": { "enum": [ "pending", "active", "blocked", "deleted" ] }, "sizeBytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": [ "string", "null" ] }, "shareUrl": { "type": [ "string", "null" ] } }, "required": [ "fileId", "filename", "status", "sizeBytes", "sha256", "shareUrl" ] }, "example": { "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB", "filename": "manual.pdf", "status": "active", "sizeBytes": 1048576, "sha256": null, "shareUrl": "https://stsh.in/abcdefgh" } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/uploads/abort": { "post": { "operationId": "abort", "summary": "Cancel a pending upload", "description": "Cancel a pending upload and release its storage reservation. This does not delete a published file. A second abort returns 409 because the upload is no longer pending.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "fileId" ] }, "example": { "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] }, "example": { "ok": true } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/uploads/remote": { "post": { "operationId": "remote", "summary": "Import from a URL", "description": "Available only when account.remoteUploadEnabled is true. Submit a publicly reachable HTTP(S) file URL up to 20 GiB; the source is validated and the import runs asynchronously. An account can have 2 pending imports and submit 20 imports totaling 50 GiB in a rolling 24 hours. Submissions are limited to 3 per minute; a full shared import queue also returns 429. Private addresses and Stashbay source URLs are refused. Do not automatically retry this POST: it creates another import.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "category": { "type": "string" } }, "required": [ "url" ] }, "example": { "url": "https://example.com/manual.pdf", "filename": "manual.pdf" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "remoteUploadId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "filename": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0 } }, "required": [ "remoteUploadId", "fileId", "filename", "sizeBytes" ] }, "example": { "remoteUploadId": "01K4J7Y4H8ZQX2W3N5V6R9T0AC", "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB", "filename": "manual.pdf", "sizeBytes": 1048576 } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "remote_status", "summary": "Check remote import progress", "description": "Pass 1–25 comma-separated remoteUploadIds in ids. Only jobs belonging to your account are returned. Poll no more than once every five seconds. Once done, call completion with its fileId to obtain a share link; do not complete a queued or fetching import.", "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "Comma-separated remoteUploadIds; maximum 25.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "fileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "enum": [ "queued", "fetching", "done", "failed" ] }, "bytesFetched": { "type": "integer", "minimum": 0 }, "declaredSizeBytes": { "type": "integer", "minimum": 0 }, "lastError": { "type": [ "string", "null" ] } }, "required": [ "id", "fileId", "status", "bytesFetched", "declaredSizeBytes", "lastError" ] } } }, "required": [ "jobs" ] }, "example": { "jobs": [ { "id": "01K4J7Y4H8ZQX2W3N5V6R9T0AC", "fileId": "01K4J7Y4H8ZQX2W3N5V6R9T0AB", "status": "fetching", "bytesFetched": 524288, "declaredSizeBytes": 1048576, "lastError": null } ] } } } }, "400": { "description": "Invalid JSON, fields, part numbers or byte lengths. Correct the request before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing, invalid, rotated or revoked API key. Send a current bearer key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Inactive account, cross-site request, insufficient permission, or remote imports disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Unknown endpoint, file or upload; another account's files also return 404. Proxy PUT routes return 404 in presigned mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "405": { "description": "Wrong HTTP method for an upload endpoint. Check the Allow response header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Insufficient storage, a closed upload, missing bytes or an upload conflict. Inspect the file status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "JSON request exceeds 1 MiB. File bytes belong in the separate PUT requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "415": { "description": "Wrong request content type, unsupported file format, or file screening refused the upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Request rate, pending uploads or rolling daily allowance reached, or the import queue is full. Honor Retry-After; daily allowances may require a longer wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "451": { "description": "File matches a takedown restriction and cannot be hosted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Unexpected server failure. Check upload status before retrying a state-changing request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "File inspection or a dependency is unavailable. Follow the response's recovery instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } } } }