# Download streams file headers, bytes, and per-file errors. [API catalog](/reference/api/) · [Docker Sandboxes overview](/reference/api/sandboxes/latest/) · [Product manual](https://docs.docker.com/ai/sandboxes-api/) · [OpenAPI specification](/reference/api/sandboxes/api.yaml) API version: v1 > This API is experimental. Features, interfaces, > and behavior may change. `GET /v1/files/download` Download streams file headers, bytes, and per-file errors. A path that leaves the jail through a symlink, or names a non-regular object, reports a FileError with a error reason instead of reading through it. ## Connection and access [API connection and authentication guidance](/reference/api/sandboxes/latest/#authentication) Server: `{endpoint}` `endpoint`: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. ```json [ { "sandboxBearer": [] } ] ``` ## Example request Replace placeholders and provide the required credentials or request body. ```console curl \ --request GET \ --header "Authorization: Bearer ${TOKEN}" \ --header 'Accept: multipart/mixed' \ 'https://sandbox.invalid/v1/files/download?paths=%3CPATHS%3E' ``` ## Parameters ### paths Location: query. Required: yes. paths naming stable regular files or absent entries at canonical absolute paths yield contiguous results in request order, including duplicates. ```json { "description": "paths naming stable regular files or absent entries at canonical absolute paths\nyield contiguous results in request order, including duplicates.", "in": "query", "name": "paths", "pointer": "/paths/~1v1~1files~1download/get/parameters/0", "required": true, "schema": { "items": { "type": "string" }, "minItems": 1, "title": "paths", "type": "array" } } ``` ## Request and responses ### Response 200 multipart/mixed Success Read metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures. Stream item schema: ```json { "anyOf": [ { "$ref": "#/components/schemas/FileHeader" }, { "contentMediaType": "application/octet-stream" }, { "$ref": "#/components/schemas/FileError" }, { "$ref": "#/components/schemas/Error" } ] } ``` itemEncoding: ```json { "contentType": "application/json, application/octet-stream", "headers": { "Content-Disposition": { "required": true, "schema": { "enum": [ "attachment; name=metadata", "attachment; name=content", "attachment; name=error", "attachment; name=stream-error" ], "type": "string" } } } } ``` ### Response default application/json The structured Error body identifies the failure with a stable code and optional typed details. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` Schema example: ```json { "code": "notFound", "details": [], "message": "sandbox not found" } ``` ## Complete operation contract ```json { "description": "Download streams file headers, bytes, and per-file errors. A path that\nleaves the jail through a symlink, or names a non-regular object, reports\na FileError with a error reason instead of reading through it.", "operationId": "download", "parameters": [ { "description": "paths naming stable regular files or absent entries at canonical absolute paths\nyield contiguous results in request order, including duplicates.", "in": "query", "name": "paths", "required": true, "schema": { "items": { "type": "string" }, "minItems": 1, "title": "paths", "type": "array" } } ], "responses": { "200": { "content": { "multipart/mixed": { "itemEncoding": { "contentType": "application/json, application/octet-stream", "headers": { "Content-Disposition": { "required": true, "schema": { "enum": [ "attachment; name=metadata", "attachment; name=content", "attachment; name=error", "attachment; name=stream-error" ], "type": "string" } } } }, "itemSchema": { "anyOf": [ { "$ref": "#/components/schemas/FileHeader" }, { "contentMediaType": "application/octet-stream" }, { "$ref": "#/components/schemas/FileError" }, { "$ref": "#/components/schemas/Error" } ] }, "x-sbx-framing": { "description": "Read metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures.", "parts": { "content": { "contentType": "application/octet-stream", "schema": { "contentMediaType": "application/octet-stream" } }, "error": { "contentType": "application/json", "schema": { "$ref": "#/components/schemas/FileError" } }, "metadata": { "contentType": "application/json", "schema": { "$ref": "#/components/schemas/FileHeader" } }, "stream-error": { "contentType": "application/json", "schema": { "$ref": "#/components/schemas/Error" } } }, "repeatedItems": true, "requiresClosingDelimiter": true, "requiresTerminal": false } } }, "description": "Success\n\nRead metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The structured Error body identifies the failure with a stable code and optional typed details." } }, "security": [ { "sandboxBearer": [] } ], "servers": [ { "url": "{endpoint}", "variables": { "endpoint": { "default": "https://sandbox.invalid", "description": "The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control." } } } ], "summary": "Download streams file headers, bytes, and per-file errors.", "tags": [ "Files" ], "x-sbx-authenticated-only": false, "x-sbx-conditional-permissions": [], "x-sbx-http-transfer": { "response": { "bytesField": "data", "errorField": "error", "mediaType": "multipart/mixed", "metadataField": "header", "repeatedItems": true } }, "x-sbx-plane": "data", "x-sbx-request-schema": { "$ref": "#/components/schemas/FilesDownloadRequest" }, "x-sbx-required-permissions": [ "sandboxesFilesRead" ], "x-sbx-response-schema": { "$ref": "#/components/schemas/FilesDownloadResponse" }, "x-sbx-serving-surface": "sandboxEndpoint" } ``` ## Referenced schemas - [#/components/schemas/Error](/reference/api/sandboxes/latest/schemas/Error/) - [#/components/schemas/FileError](/reference/api/sandboxes/latest/schemas/FileError/) - [#/components/schemas/FileHeader](/reference/api/sandboxes/latest/schemas/FileHeader/) - [#/components/schemas/FilesDownloadRequest](/reference/api/sandboxes/latest/schemas/FilesDownloadRequest/) - [#/components/schemas/FilesDownloadResponse](/reference/api/sandboxes/latest/schemas/FilesDownloadResponse/)