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

# API reference

The PixelVault API is a JSON REST API for hosting images, PDF documents, original MP4 video and original audio. Every page here is generated from the [OpenAPI 3.1 spec](https://api.pixelvault.dev/openapi.json), the same file agents and SDK generators read, so the reference and the API cannot disagree.

## Base URL

```
https://api.pixelvault.dev
```

Media is served from the CDN at `https://img.pixelvault.dev/{project_id}/{asset_id}.{ext}`, not from the API host. Image URLs take on-the-fly transform parameters; see [Image Delivery](/docs/api/image-delivery/#serve_image) and [Transforms](/docs/transforms/).

## Authentication

Send an API key as a Bearer token. Secret keys start with `pv_live_` (production) or `pv_test_` (test) and grant full access to their project. Publishable keys (`pv_pub_`) are safe in browser code: upload-only, and restricted to an allowlist of request origins. Keys are hashed server-side; the raw key is shown once.

Example request

curlNode.jsPythonCLI

```
curl "https://api.pixelvault.dev/v1/images?per_page=20" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

Signing up needs no key ([create an account](/docs/api/authentication/#register_account), or sign in with an [emailed code](/docs/api/authentication/#device_login_start)), and a [multipart image upload](/docs/api/images/#upload_image) works without one too, but is then temporary (expires in 30 days). Endpoints the web dashboard drives also accept a dashboard session token. Each operation lists what it accepts under **Authentication**. More in [Authentication & API keys](/docs/authentication/).

## Responses and errors

Requests and responses are JSON unless an endpoint says otherwise (raw MP4 and audio uploads, tar export downloads). A successful response wraps its payload in a top-level `data` object; paginated lists add a `meta` object with pagination. A few responses (export jobs, billing URLs) return their object directly; each operation's response example shows the exact shape.

Success

```
{
  "data": {
    "id": "img_abc123",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png"
  }
}
```

List

```
{
  "data": [ { "id": "img_abc123" } ],
  "meta": { "total": 42, "page": 1, "per_page": 20 }
}
```

Error

```
{
  "error": {
    "code": "invalid_file",
    "message": "Human-readable description"
  }
}
```

A failed request returns an `error` object with a stable, machine-readable `code` and a human-readable `message`; branch on the code. Plan quotas return `402`, not `429`: retrying cannot succeed until you delete media, upgrade, or the month resets. Every code, what causes it and whether to retry is in the [error catalog](/docs/errors/); quota and rate limits are in [Limits](/docs/limits/).

## Conventions

-   **Retries.** Uploads accept an `Idempotency-Key` header, so a retry after a timeout never stores a second copy. See [Idempotency](/docs/idempotency/).
-   **Pagination.** Paginated lists take `page` and `per_page` and return `meta.total`. See [Pagination](/docs/pagination/).
-   **Long-running work.** Descriptions, video jobs, transcription and exports run in the background; poll the resource or subscribe to [webhooks](/docs/api/webhooks/). See [Async jobs](/docs/async-jobs/).
-   **Identifiers.** IDs are prefixed by type: `img_`, `vid_`, `aud_`, `col_`, `exp_`, `key_`, `whk_`, `proj_`.

## Versioning

Every endpoint lives under `/v1`. This reference is generated from spec version `1.0.0`. Fetch [`/openapi.json`](https://api.pixelvault.dev/openapi.json) to generate a client or to give an agent the full contract.

## Resources

-   [**Authentication** Create an account and get an API key without a browser: `register_account` returns a live key instantly; the emailed-code flow (`device_login_start` + `device_login_complete`) signs an existing account in and mints a new key. 3 endpoints](/docs/api/authentication/)
-   [**Images** Upload, import, generate, edit, describe, list and delete images and PDF documents. Every image gets a permanent CDN URL on img.pixelvault.dev that supports on-the-fly transforms; private images are served behind signed URLs. 11 endpoints](/docs/api/images/)
-   [**Videos** Host original MP4 files byte-for-byte with a seekable CDN URL and a poster frame. Optional jobs create a social-ready H.264/AAC copy, a transcript and a storyboard. Files over 100 MB use the multipart upload session endpoints. 14 endpoints](/docs/api/videos/)
-   [**Audio** Host original MP3, WAV, M4A and OGG files without transcoding (max 25,000,000 bytes), served with HTTP range support. Optional transcription produces plain-text, WebVTT and timestamped JSON transcripts. 7 endpoints](/docs/api/audio/)
-   [**Collections** A collection is a typed group of media (a CI run, a generation set, an album) with shared metadata and its own lifecycle. Batch uploads create or reuse one; images, videos and audio can be filtered by `collection_id`. 3 endpoints](/docs/api/collections/)
-   [**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. 3 endpoints](/docs/api/exports/)
-   [**Projects** Isolate media, API keys, usage, webhooks and idempotency keys inside one account. Free includes 1 project, Starter 3 and Pro 10. 4 endpoints](/docs/api/projects/)
-   [**Custom Domains** Serve one project's media from a customer-owned hostname. Starter includes 1 hostname per account and Pro 3. Add the CNAME target returned by the API; Cloudflare provisions and renews HTTPS automatically. 4 endpoints](/docs/api/custom-domains/)
-   [**API Keys** List, create and revoke the secret keys on a project, so an agent can rotate its own credentials. All key endpoints need a secret key (`pv_live_` / `pv_test_`); publishable keys get 403. 3 endpoints](/docs/api/api-keys/)
-   [**Usage** Plan, limits and current usage for the calling key's project, so an agent can check quota before a bulk upload. 1 endpoint](/docs/api/usage/)
-   [**Billing** Start an upgrade or open the Stripe customer portal without a dashboard session. Both return a Stripe URL for a person to open; nothing is charged by the API call itself. 2 endpoints](/docs/api/billing/)
-   [**Webhooks** Starter and Pro projects receive signed HTTPS callbacks for media lifecycle events (up to 3 endpoints on Starter, 10 on Pro). Manage endpoints, rotate signing secrets and read the delivery log. 6 endpoints](/docs/api/webhooks/)
-   [**Uploads** Media-library endpoints the web dashboard calls. They authenticate with a dashboard session token (JWT), not an API key; callers with an API key should use the Images endpoints. 5 endpoints](/docs/api/uploads/)
-   [**Playground** Anonymous, rate-limited endpoints behind the free browser tools: temporary uploads and generations that expire within 24 hours unless claimed into an account with `claim_upload`. 5 endpoints](/docs/api/playground/)
-   [**Image Delivery** The CDN on img.pixelvault.dev serves every image and applies on-the-fly transforms from query parameters. No API call or auth for public images; private images need a signed URL. 1 endpoint](/docs/api/image-delivery/)
-   [**Health** Liveness check for the API worker. 1 endpoint](/docs/api/health/)
