Bulk Download Files

Stream a selection of workspace files as one zip. Select files by id and folders by path, each as one comma-separated parameter; a folder expands to all its descendants, and a path matching no folder is rejected rather than ignored. Each parameter accepts at most 100 entries — the same ceiling the resolved selection is held to — and the resolved file count and total bytes are checked again, so an over-broad selection answers 400 rather than streaming indefinitely. Downloading records an audit event, so it is not a safe read. A HEAD skips the effect but is authorized exactly as the GET is, so it answers 400, 401, 403, or 404 wherever the GET would and an empty 200 otherwise. Skipping the effect means skipping the read that produces the payload, so that 200 carries none of the response headers documented below — it answers whether the GET would be allowed, not what the GET would return. In particular a HEAD does not report Content-Length, so it cannot be used to size a download in advance; read the size from the file resource instead.

GET/api/v2/files/bulk-download

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Query Parameters

workspaceId*string

Workspace containing the selection.

Length1 <= length <= 128
fileIds?string

File identifiers to include, comma-separated. At most 100 entries.

folderPaths?string

Folder paths to include with all their descendants, comma-separated. At most 100 entries, and the files they resolve to count against the same 100-file download ceiling. A path that matches no folder is rejected rather than ignored.

Response Body

application/zip

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/files/bulk-download?workspaceId=string" \  -H "X-API-Key: YOUR_API_KEY"
"string"
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "CONFLICT",
    "message": "File already exists"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
POSTDelete FilesPOSTComplete File Upload