Exports
Download every non-expired image, video and audio original in a project as one tar archive with a manifest.json. Exports run asynchronously: start one, poll the job, then download it within 24 hours.
The Export job object
An export job.
Properties
| Property | Type | Description |
|---|---|---|
id | string | |
status | string |
|
image_count | integer | Images and PDFs. |
video_count | integer | |
audio_count | integer | |
asset_count | integer | |
processed_count | integer | Parent assets written so far. |
bytes | integer | Archive bytes written so far. |
created_at | string (date-time) | |
expires_at | string (date-time) | When the archive expires (24 hours after the export started). |
download_url | string | Path of |
error | string | Present when the job failed: the internal error message. Start a new export to retry. |
{
"id": "exp_abc123",
"status": "complete",
"image_count": 327,
"video_count": 4,
"audio_count": 1,
"asset_count": 332,
"processed_count": 332,
"bytes": 734003200,
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"download_url": "/v1/export-jobs/exp_abc123/download"
}Start a media export
POST /v1/export
Starts an asynchronous export of every non-expired image, PDF, video and audio original in the project as one .tar with a manifest.json. Poll get_export_job (pending → processing → complete, or failed/expired), then fetch it with download_export within 24 hours. One export per project can run at a time. Emits export.completed or export.failed.
The manifest keeps its existing images entries and adds videos and audios, custom metadata, folder and collection membership, job state, and parent relationships for every available poster, social-ready copy, transcript and storyboard. Private bytes are included behind the owner-authenticated download, but private manifest URLs are null: no permanent or stale bearer links. Pending and failed jobs are recorded without invented artifact files. Assets already expired or deleted at snapshot time are omitted; an asset deleted after the snapshot stays in the manifest and its missing bytes are skipped. Existing image archive paths and manifest fields are unchanged for backward compatibility.
Authenticate with a secret key, or a dashboard token plus project_id. Limited to 10 starts per hour per IP. The response is not wrapped in data.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Optional | Required only when authenticating with a dashboard token; ignored for secret-key auth (the key already identifies the project). |
Responses
- 202
Export job accepted. Poll
status_urluntilstatusiscomplete. - 400
project_id_required: dashboard-token auth needs theproject_idquery parameter. - 401
missing_credentials: no Bearer token.invalid_api_key: unknown or revoked key.unauthorized: invalid or expired dashboard token. - 403
publishable_key_forbidden: use a secret key.account_suspended: the account is suspended. - 404
project_not_found: the dashboard account has no project with that id. - 409
export_in_progress: an export for this project is already pending or processing; the error also carries itsjob_id. - 429
rate_limit_exceeded: more than 10 export starts per hour from this IP. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/export \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"job_id": "exp_abc123",
"status": "pending",
"asset_count": 332,
"image_count": 327,
"video_count": 4,
"audio_count": 1,
"status_url": "/v1/export-jobs/exp_abc123"
} Get media export job status
GET /v1/export-jobs/{id}
Poll an export job until status is complete (pending → processing → complete, or failed/expired). processed_count counts parent assets, not derived files. When the job is complete and unexpired the response adds download_url; archives expire 24 hours after the export started. Auth is the same as start_export; limited to 120 requests per minute per IP. The response is not wrapped in data.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Export job id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Optional | Required only with a dashboard token. |
Responses
- 200
Job status
- 400
project_id_required: dashboard-token auth needs theproject_idquery parameter. - 401
missing_credentials: no Bearer token.invalid_api_key: unknown or revoked key.unauthorized: invalid or expired dashboard token. - 403
publishable_key_forbidden: use a secret key.account_suspended: the account is suspended. - 404
export_job_not_found: no export job with this id in the project.project_not_found: the dashboard account has no project with that id. - 429
rate_limit_exceeded: more than 120 requests per minute from this IP.
curl https://api.pixelvault.dev/v1/export-jobs/exp_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"id": "exp_abc123",
"status": "complete",
"image_count": 327,
"video_count": 4,
"audio_count": 1,
"asset_count": 332,
"processed_count": 332,
"bytes": 734003200,
"created_at": "2026-11-16T12:00:00.000Z",
"expires_at": "2026-11-17T12:00:00.000Z",
"download_url": "/v1/export-jobs/exp_abc123/download"
} Download a finished export
GET /v1/export-jobs/{id}/download
Stream the completed export as a tar archive (application/x-tar, Content-Disposition: attachment; filename="pixelvault-export-<project_id>.tar") containing manifest.json plus every exported original and available artifact. Private bytes are included: keep the archive private. Auth is the same as start_export.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Export job id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | Optional | Required only with a dashboard token. |
Responses
- 200
The tar archive.
- 400
project_id_required: dashboard-token auth needs theproject_idquery parameter. - 401
missing_credentials: no Bearer token.invalid_api_key: unknown or revoked key.unauthorized: invalid or expired dashboard token. - 403
publishable_key_forbidden: use a secret key.account_suspended: the account is suspended. - 404
export_job_not_found: no export job with this id in the project.project_not_found: the dashboard account has no project with that id. - 409
export_not_ready: the job is not complete yet; keep pollingget_export_job. - 410
export_expired: the archive is older than 24 hours or gone; start a new export. - 429
rate_limit_exceeded: more than 120 requests per minute from this IP.
curl https://api.pixelvault.dev/v1/export-jobs/exp_abc123/download \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-o export.tar