<!-- Markdown twin of https://pixelvault.dev/docs/api/exports/ -->

[API reference](/docs/api/)

# 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](#object)
-   POST [Start a media export](#start_export)
-   GET [Get media export job status](#get_export_job)
-   GET [Download a finished export](#download_export)

## The Export job object

An export job.

### Properties

The Export job object properties

Property

Type

Description

`id`

string

`status`

string

`expired`: completed but past `expires_at`; start a new export.

One of: `pending`, `processing`, `complete`, `failed`, `expired`

`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 [`download_export`](/docs/api/exports/#download_export). Present only when complete and unexpired.

`error`

string

Present when the job failed: the internal error message. Start a new export to retry.

The Export job object

```
{
  "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`](/docs/api/exports/#get_export_job) (`pending` → `processing` → `complete`, or `failed`/`expired`), then fetch it with [`download_export`](/docs/api/exports/#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

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_url` until `status` is `complete`.
    
-   400
    
    [`project_id_required`](/docs/errors/#project_id_required): dashboard-token auth needs the `project_id` query parameter.
    
-   401
    
    [`missing_credentials`](/docs/errors/#missing_credentials): no Bearer token. [`invalid_api_key`](/docs/errors/#invalid_api_key): unknown or revoked key. [`unauthorized`](/docs/errors/#unauthorized): invalid or expired dashboard token.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`project_not_found`](/docs/errors/#project_not_found): the dashboard account has no project with that id.
    
-   409
    
    [`export_in_progress`](/docs/errors/#export_in_progress): an export for this project is already pending or processing; the error also carries its `job_id`.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 10 export starts per hour from this IP. Honour `Retry-After`.
    

Request

curlNode.jsPythonCLI

```
curl -X POST https://api.pixelvault.dev/v1/export \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 202

```
{
  "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`](/docs/api/exports/#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

Path parameters

Name

Type

Required

Description

`id`

string

Required

Export job id.

### Query parameters

Query parameters

Name

Type

Required

Description

`project_id`

string

Optional

Required only with a dashboard token.

### Responses

-   200
    
    Job status
    
-   400
    
    [`project_id_required`](/docs/errors/#project_id_required): dashboard-token auth needs the `project_id` query parameter.
    
-   401
    
    [`missing_credentials`](/docs/errors/#missing_credentials): no Bearer token. [`invalid_api_key`](/docs/errors/#invalid_api_key): unknown or revoked key. [`unauthorized`](/docs/errors/#unauthorized): invalid or expired dashboard token.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`export_job_not_found`](/docs/errors/#export_job_not_found): no export job with this id in the project. [`project_not_found`](/docs/errors/#project_not_found): the dashboard account has no project with that id.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 120 requests per minute from this IP.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/export-jobs/exp_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Response 200

```
{
  "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`](/docs/api/exports/#start_export).

### Authentication

API key, or a dashboard session token, sent as `Authorization: Bearer <token>`.

### Path parameters

Path parameters

Name

Type

Required

Description

`id`

string

Required

Export job id.

### Query parameters

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`](/docs/errors/#project_id_required): dashboard-token auth needs the `project_id` query parameter.
    
-   401
    
    [`missing_credentials`](/docs/errors/#missing_credentials): no Bearer token. [`invalid_api_key`](/docs/errors/#invalid_api_key): unknown or revoked key. [`unauthorized`](/docs/errors/#unauthorized): invalid or expired dashboard token.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`export_job_not_found`](/docs/errors/#export_job_not_found): no export job with this id in the project. [`project_not_found`](/docs/errors/#project_not_found): the dashboard account has no project with that id.
    
-   409
    
    [`export_not_ready`](/docs/errors/#export_not_ready): the job is not complete yet; keep polling [`get_export_job`](/docs/api/exports/#get_export_job).
    
-   410
    
    [`export_expired`](/docs/errors/#export_expired): the archive is older than 24 hours or gone; start a new export.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 120 requests per minute from this IP.
    

Request

curlNode.jsPython

```
curl https://api.pixelvault.dev/v1/export-jobs/exp_abc123/download \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -o export.tar
```

Response 200

Body: `application/x-tar`. The tar archive.
