Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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, 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 and 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
curl "https://api.pixelvault.dev/v1/images?per_page=20" \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

Signing up needs no key (create an account, or sign in with an emailed code), and a multipart image upload 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.

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; quota and rate limits are in Limits.

Conventions

  • Retries. Uploads accept an Idempotency-Key header, so a retry after a timeout never stores a second copy. See Idempotency.
  • Pagination. Paginated lists take page and per_page and return meta.total. See Pagination.
  • Long-running work. Descriptions, video jobs, transcription and exports run in the background; poll the resource or subscribe to webhooks. See 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 to generate a client or to give an agent the full contract.

Resources