Objects & Storage
Documentation for Objects & Storage
Base path: /api/v1/objects
Provides endpoints for file downloads and storage usage statistics. Files produced during workflow execution are stored in object storage (S3-compatible) and can be downloaded via pre-signed URLs.
Endpoints Overview
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/objects/download | None | Download a file by object key |
| GET | /api/v1/objects/storage-usage | JWT | Get storage usage statistics |
GET /api/v1/objects/download
Downloads a file from object storage using its object key. This endpoint is public — no authentication required. Object keys act as access tokens (they are long, random, and hard to guess).
Authentication
None required.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
objectKey | string | Yes | The object storage key (path) of the file |
type | string | No | Download disposition: "attachment" (download prompt) or "inline" (display in browser) |
Behavior
The server generates a pre-signed URL for the object and redirects the browser to it, or streams the file directly. The type parameter controls the Content-Disposition header.
Example
Response
Redirects to the file or streams it directly. Status 302 redirect to a pre-signed URL.
Errors
| Status | Reason |
|---|---|
400 Bad Request | Missing objectKey parameter |
404 Not Found | Object not found in storage |
GET /api/v1/objects/storage-usage
Returns storage usage statistics for the active organization (or a specific user).
Authentication
Requires JWT (authMiddleware).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
createdBy | string (UUID) | No | Filter to a specific user's uploads (admin use) |
Response 200 OK
| Field | Type | Description |
|---|---|---|
orgKey | string | Organization key |
totalBytes | number | Total storage used in bytes |
inputBytes | number | Bytes used by input files |
outputBytes | number | Bytes used by output files |
fileCount | number | Total number of stored files |
breakdown | array | Per-workflow breakdown of storage usage |
Breakdown item fields:
| Field | Type | Description |
|---|---|---|
workflowId | string (UUID) | Workflow ID |
workflowName | string | Workflow name |
bytes | number | Storage used by this workflow's runs |
fileCount | number | Number of files for this workflow |
Example
Object Key Format
Object keys follow a structured path format:
These keys are used when building download URLs for workflow run outputs.