Share feedback
Answers are generated based on the documentation.

Experimental

Product manualDownload OpenAPI specificationMarkdown

Download streams file headers, bytes, and per-file errors.

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

{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.

Use one of these alternatives. Requirements within an alternative apply together.

  • sandboxBearer

Parameters

paths query Required

paths naming stable regular files or absent entries at canonical absolute paths yield contiguous results in request order, including duplicates.

Type: array

Array item

Type: string

All schema constraints and annotations
{
  "type": "string"
}
All schema constraints and annotations
{
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "title": "paths",
  "type": "array"
}

Request and responses

Response 200

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.

multipart/mixed

Stream item

One or more alternatives must match

Schema: FileHeader

All schema constraints and annotations
{
  "contentMediaType": "application/octet-stream"
}

Schema: FileError

Schema: Error

All schema constraints and annotations
{
  "anyOf": [
    {
      "$ref": "#/components/schemas/FileHeader"
    },
    {
      "contentMediaType": "application/octet-stream"
    },
    {
      "$ref": "#/components/schemas/FileError"
    },
    {
      "$ref": "#/components/schemas/Error"
    }
  ]
}
itemEncoding: content types and part headers
{
  "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

The structured Error body identifies the failure with a stable code and optional typed details.

application/json

Schema: Error

Schema example

{
  "code": "notFound",
  "details": [],
  "message": "sandbox not found"
}

Referenced schemas

#/components/schemas/Error

#/components/schemas/FileError

#/components/schemas/FileHeader

#/components/schemas/FilesDownloadRequest

#/components/schemas/FilesDownloadResponse

Complete operation contract
{
  "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"
}