Reference

Pixel Wand API

Programmatic access to your workspace. Authenticate with a Bearer token issued from Settings → API Keys. All requests return JSON unless noted otherwise.

Authentication

Include your API key as a Bearer token on every request. Keys start with ak_live_ and are only shown once at creation — if you lose one, revoke it and create a replacement.

Authorization: Bearer ak_live_REPLACE_ME

API keys are scoped to a single organization and carry a scopes array. read unlocks every GET endpoint; write is required for POST, PATCH, and DELETE.

Rate limits

Per-key requests-per-second caps, enforced in-process. Responses over the limit return 429 Too Many Requests.

PlanRequests / second
FreeAPI access disabled (upgrade required)
Team3 req/sec
Business10 req/sec
Enterprise100 req/sec

Errors

Standard HTTP status codes. Error bodies follow the shape { "error": string }. Common codes:

Assets

GET/api/v1/assets

List assets in the workspace with optional filters.

Query params: q (search), type (IMAGE | VIDEO), collectionId, tags (comma-separated), page, pageSize (max 200).

curl https://pixel-wand.com/api/v1/assets?page=1&pageSize=50 \
  -H "Authorization: Bearer ak_live_REPLACE_ME"

Response

{
  "items": [
    {
      "id": "clx...",
      "name": "hero-2024.jpg",
      "originalName": "hero.jpg",
      "size": 182341,
      "mimeType": "image/jpeg",
      "mediaType": "IMAGE",
      "storageKey": "orgs/.../hero.jpg",
      "tags": ["hero", "2024"],
      "collectionId": null,
      "locationX": 0,
      "locationY": 0,
      "uploadedAt": "2026-04-22T21:00:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "totalPages": 1
}
POST/api/v1/assets

Upload an asset in two steps: presign, then finalize.

Use mode: "presign" first to get a presigned PUT URL, send the raw file bytes to that URL with Content-Type matching what you declared, then call this endpoint again with mode: "finalize" and the storageKey you were given.

# Step 1 — get upload credentials
curl https://pixel-wand.com/api/v1/assets \
  -X POST \
  -H "Authorization: Bearer ak_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "presign",
    "originalName": "hero.jpg",
    "mimeType": "image/jpeg",
    "size": 182341
  }'

# Step 2 — finalize the row after your upload succeeded
curl https://pixel-wand.com/api/v1/assets \
  -X POST \
  -H "Authorization: Bearer ak_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "finalize",
    "originalName": "hero.jpg",
    "mimeType": "image/jpeg",
    "size": 182341,
    "storageKey": "orgs/<orgId>/2026/04/<uuid>-hero.jpg",
    "tags": ["hero", "2024"]
  }'
GET/api/v1/assets/{id}

Fetch a single asset row.

curl https://pixel-wand.com/api/v1/assets/clx... \
  -H "Authorization: Bearer ak_live_REPLACE_ME"
PATCH/api/v1/assets/{id}

Update name, tags, or collectionId on an existing asset.

curl https://pixel-wand.com/api/v1/assets/clx... \
  -X PATCH \
  -H "Authorization: Bearer ak_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["marketing", "q2"] }'
DELETE/api/v1/assets/{id}

Delete an asset. Storage objects are cleaned up later by a background sweeper.

curl https://pixel-wand.com/api/v1/assets/clx... \
  -X DELETE \
  -H "Authorization: Bearer ak_live_REPLACE_ME"

Collections

GET/api/v1/collections

List collections in the workspace.

Query params: name (exact match), parentId (filter by parent; pass null for top-level only).

curl https://pixel-wand.com/api/v1/collections \
  -H "Authorization: Bearer ak_live_REPLACE_ME"

Response

{
  "collections": [
    {
      "id": "clx...",
      "name": "Campaign Q2",
      "parentId": null,
      "color": "#6366f1",
      "createdAt": "2026-04-22T21:00:00.000Z"
    }
  ]
}
POST/api/v1/collections

Create a collection, or return the existing one if a collection with that name already exists (idempotent).

curl https://pixel-wand.com/api/v1/collections \
  -X POST \
  -H "Authorization: Bearer ak_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campaign Q2",
    "color": "#6366f1",
    "parentId": null
  }'

Export presets

Named output specs you can reference by name on the /api/v1/assets/{id}/export-url endpoint. Saves repeating format/quality/size params on every call.

GET/api/v1/export-presets

List all export presets for the workspace.

curl https://pixel-wand.com/api/v1/export-presets \
  -H "Authorization: Bearer ak_live_REPLACE_ME"
POST/api/v1/export-presets

Create or update a preset by name.

curl https://pixel-wand.com/api/v1/export-presets \
  -X POST \
  -H "Authorization: Bearer ak_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "shopify-thumb",
    "format": "WEBP",
    "quality": 85,
    "maxWidth": 800,
    "maxHeight": 800,
    "preserveAspect": true
  }'
GET/api/v1/assets/{id}/export-url

Get a short-lived signed URL to a transformed copy of one image.

Query params: preset (saved preset name), or inline format / quality / maxWidth / maxHeight / preserveAspect. Optional ttl (seconds, 60–86400, default 3600).

# Using a saved preset
curl "https://pixel-wand.com/api/v1/assets/clx.../export-url?preset=shopify-thumb" \
  -H "Authorization: Bearer ak_live_REPLACE_ME"

# Inline params
curl "https://pixel-wand.com/api/v1/assets/clx.../export-url?format=WEBP&maxWidth=800&ttl=7200" \
  -H "Authorization: Bearer ak_live_REPLACE_ME"

Response

{
  "assetId": "clx...",
  "url": "https://...",
  "format": "WEBP",
  "ttlSeconds": 3600,
  "expiresAt": "2026-04-22T22:00:00.000Z",
  "cached": true
}

Exports

POST/api/v1/exports

Batch-export assets. Returns a ZIP stream synchronously.

Up to 500 assets per request. The ZIP streams back directly — save the response body as a file. Subject to a 30 second serverless timeout; chunk larger batches across multiple requests.

curl https://pixel-wand.com/api/v1/exports \
  -X POST \
  -H "Authorization: Bearer ak_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -o export.zip \
  -d '{
    "assetIds": ["clx1...", "clx2..."],
    "config": {
      "format": "webp",
      "quality": 85,
      "maxWidth": 2560,
      "maxHeight": 2560,
      "preserveAspect": true,
      "renameOnExport": false
    }
  }'