API

Endpoints

Legacy /api/v1/… paths still work. Prefer /v1/….

Query

let cursor = null;
const files = [];
do {
  const url = new URL(
    "https://api.pixeldrive.dev/v1/projects/YOUR_PUBLIC_ID",
  );
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);
  const page = await fetch(url).then((res) => res.json());
  files.push(...page.files);
  cursor = page.nextCursor;
} while (cursor);

const res = await fetch(
  "https://api.pixeldrive.dev/v1/projects/YOUR_PUBLIC_ID?recursive=true",
);
const project = await res.json();
// Nested files include folderPath, e.g. "selects/outtakes"

Response

{
  "name": "summer-lookbook",
  "files": [
    {
      "publicId": "6dec2e93a1b2c3d4e5f6a7b8c9d0e1f2",
      "name": "eng-448.jpg",
      "url": "https://cdn.pixeldrive.dev/{projectId}/{publicId}/v1",
      "stableUrl": "https://cdn.pixeldrive.dev/f/{publicId}",
      "optimizable": true,
      "src": "https://cdn.pixeldrive.dev/f/{publicId}?w=1280",
      "srcset": "https://cdn.pixeldrive.dev/f/{publicId}?w=320 320w, …",
      "contentType": "image/jpeg",
      "kind": "image",
      "size": 4821933,
      "width": 5695,
      "height": 3797,
      "blurhash": "LGF5]+Yk^6#M@-5c,1J5",
      "tags": ["favorites"],
      "uploadedAt": 1734567890123
    }
  ],
  "folders": [
    { "publicId": "b86a4c21d0e1f2a3b4c5d6e7f8a9b0c1", "name": "selects" }
  ],
  "nextCursor": null
}

Authorization

Create a key in project settings. Shown once. Send it as Authorization: Bearer pd_live_…. One key is scoped to one project. Write can upload; Read can list and mint URLs. Read keys 404 on upload routes. Keys work on public projects even when the public API toggle is off. Private-project keys mint expiring /f/ URLs. Keys keep working after a plan change, under the current file-size and storage caps.

Allowed types

Same allowlist on the dashboard, POST /v1/upload, the SDK, and MCP. kind is derived from MIME — callers never send it. HTML, SVG, and JavaScript are rejected, including on private projects.

A project can tighten this list and the max file size in Settings → Uploads. It cannot raise the account plan cap. Keys inherit the project’s rules.

Upload

Write key required. The key’s project is implicit — do not send projectId. size is required so we choose put (≤ 32 MB) vs multipart (16 MB parts). PUT the bytes to the returned URLs; never POST the file body to this API. Caps and rate limits are in Limits. The project’s Settings → Uploads rules apply here too.

{
  "name": "selects/hero.jpg",
  "contentType": "image/jpeg",
  "size": 4821933,
  "folder": "optional-folder-publicId",
  "tags": ["favorites"],
  "replace": "optional-file-publicId",
  "upsert": true
}

Path segments in name find-or-create folders (max 8). Optional folder is a folder publicId; the path is relative to it. Tags are stored on start and applied only after complete. Optional replace is a file publicId in this project — same complete/abort URLs, folder and tags stay, name becomes the new basename, kind may change. upsert: true replaces the ready file at that path instead of minting a second one (do not send it with replace). Paths are unique per folder; a colliding upload without upsert is 409. GET /v1/files?path= looks up by that path. Optional Idempotency-Key header (24 hours). DELETE /v1/files/{publicId} is 204. Cached public URLs may still serve until TTL.

{
  "id": "6dec2e93…",
  "name": "hero.jpg",
  "folderPath": "selects",
  "contentType": "image/jpeg",
  "size": 4821933,
  "upload": { "mode": "put", "url": "https://…" }
}

Multipart: { "mode": "multipart", "partSize": 16777216, "parts": [{ "partNumber": 1, "url": "…" }] }. Complete with part ETags. Complete returns the same JSON as GET /v1/files/{id}. Abort is 204 while the file is still uploading or replacing.

TypeScript: @pixeldrive-dev/sdk (npm i @pixeldrive-dev/sdk). Agents: @pixeldrive-dev/mcp with PIXELDRIVE_API_KEY.

import { readFile } from "node:fs/promises";
import { Pixeldrive } from "@pixeldrive-dev/sdk";

const pd = new Pixeldrive({ apiKey: process.env.PIXELDRIVE_API_KEY });

const file = await pd.upload({
  file: await readFile("./brief.pdf"),
  name: "contracts/brief.pdf",
  contentType: "application/pdf",
});

Headers

Errors

Private containers look like missing ones. Don’t treat 404 as “this id never existed.”

Limits

Upload uses the same account plan as the dashboard. A project can tighten allowed types and max file size below that plan (Settings → Uploads); keys cannot raise it. Rate limits are per key, not per account.

A folder with thousands of files is listed by looping nextCursor. For a large tree, paginate the container, then GET /v1/folders/{id} for each child. recursive=true is for small lookbooks, not a full-library dump.