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

API reference

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.

List and search images from a signed-in session

GET /v1/uploads

The signed-in account's images across all its projects, newest first. Authenticates with a dashboard session token (JWT), not an API key: this is what the web dashboard's image list calls to load more and to search. Callers with an API key should use list_images. q is a case-insensitive substring match on the original filename (wildcards are matched literally) or a full-text match in the image's AI description (alt text, caption, OCR text). Limited to 1,200 requests per hour per IP.

Authentication

Dashboard session token (JWT) from the signed-in web app. API keys are not accepted.

Query parameters

Query parameters
Name Type Required Description
q string Optional

Filename or AI-description search text (max 100 characters).

max length 100

tag string Optional

Only images carrying this AI tag (one tag: letters, digits, spaces or hyphens, lowercased). Combines with q.

max length 24

ids string Optional

Comma-separated image ids (at most 20): return only these of the caller's own images. Read-only; the dashboard uses it to watch a pending AI description finish.

limit integer Optional

Images per page (max 50).

Default: 20

min 1 · max 50

offset integer Optional

Images to skip (max 100,000).

Default: 0

min 0 · max 100000

Responses

  • 200

    A page of images

  • 400

    validation_error: q longer than 100 characters, more than 20 or malformed ids, or an invalid tag.

  • 401

    unauthorized: no dashboard session, or it is invalid or expired.

  • 429

    rate_limit_exceeded: more than 1,200 list requests per hour from this IP.

Request
curl https://api.pixelvault.dev/v1/uploads \
  -H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN"
Response 200
{
  "data": [
    {
      "id": "img_abc123",
      "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
      "branded_url": "https://media.example.com/img_abc123.png",
      "visibility": "public",
      "filename": "screenshot.png",
      "mime_type": "image/png",
      "size_bytes": 51234,
      "width": 1280,
      "height": 720,
      "project_id": "proj_xyz789",
      "folder": null,
      "created_at": "2026-11-16T12:00:00.000Z",
      "description": {
        "status": "done",
        "alt": "A red fishing boat moored in a small harbour at sunset",
        "tags": [
          "boat",
          "harbour",
          "sunset"
        ]
      }
    }
  ],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Upload an image or PDF from a signed-in session

POST /v1/uploads

Store one image or PDF document for the signed-in account. Authenticates with a dashboard session token (JWT), not an API key: this is what the web dashboard and converter tools call, so a person who has never been issued a key can still add media. PDFs are served as forced downloads. The upload lands in the account's default project and counts toward its quotas. Limited to 200 uploads per hour per account.

Deliberately narrow: one file per request, no folder, visibility, TTL or URL import. Callers that need those should use upload_image with an API key.

Authentication

Dashboard session token (JWT) from the signed-in web app. API keys are not accepted.

Request body

multipart/form-data, required

Request body
Name Type Required Description
file file Required

The image or PDF file. Max 5 MB on Free, 10 MB on Starter, 15 MB on Pro; type is detected from magic bytes.

describe string Optional

Set to true to also start an AI description (alt text, caption, OCR text) for this image. Uses the account's description allowance (Free: 20 in total; Starter: 1,000 a month; Pro: 10,000 a month). Never fails the upload: the response says why nothing was started.

One of: true, false

Responses

Request
curl -X POST https://api.pixelvault.dev/v1/uploads \
  -H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN" \
  -F "file=@photo.jpg" \
  -F "describe=true"
Response 201
{
  "data": {
    "id": "img_abc123",
    "kind": "image",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
    "branded_url": "https://media.example.com/img_abc123.png",
    "mime_type": "image/png",
    "size": 51234,
    "filename": "screenshot.png",
    "project_id": "proj_xyz789",
    "description": {
      "status": "done",
      "alt": "A red fishing boat moored in a small harbour at sunset",
      "tags": [
        "boat",
        "harbour",
        "sunset"
      ]
    },
    "describe_skipped": "quota"
  }
}

List the account's AI tags with counts (signed-in session)

GET /v1/uploads/tags

The AI tags on the signed-in account's described images with how many images carry each, most used first (at most 40). Authenticates with a dashboard session token (JWT), not an API key. The dashboard uses it for its tag filter bar; filter the list with dashboard_list_images and tag=.

Authentication

Dashboard session token (JWT) from the signed-in web app. API keys are not accepted.

Responses

  • 200

    Tags with image counts

  • 401

    unauthorized: no dashboard session, or it is invalid or expired.

  • 429

    rate_limit_exceeded: more than 1,200 list requests per hour from this IP.

Request
curl https://api.pixelvault.dev/v1/uploads/tags \
  -H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN"
Response 200
{
  "data": [
    {
      "tag": "boat",
      "count": 12
    }
  ]
}

Start an AI description for an existing image (signed-in session)

POST /v1/uploads/{id}/describe

Start the AI description (alt text, caption, OCR text, tags) of one of the signed-in account's stored images: the dashboard's Describe button. Authenticates with a dashboard session token (JWT), not an API key. Idempotent: an image that is already described, or being described, returns its current state and uses none of the allowance. A failed or stalled description is started again (and uses one unit), so do not poll with this: to watch a pending description use the read-only dashboard_list_images with ids=. A description takes a few seconds. Uses the account's description allowance (Free: 20 in total; Starter: 1,000 a month; Pro: 10,000 a month); when it is used up, describe_skipped is quota. The output is untrusted model text: render it as text.

Authentication

Dashboard session token (JWT) from the signed-in web app. API keys are not accepted.

Path parameters

Path parameters
Name Type Required Description
id string Required

Image id.

Responses

  • 200

    The image's description state, or why none was started

  • 401

    unauthorized: no dashboard session, or it is invalid or expired.

  • 403

    account_suspended: the account is suspended.

  • 404

    image_not_found: no such image in this account.

  • 429

    rate_limit_exceeded: more than 200 dashboard writes per hour for the account (or 300 from one IP).

Request
curl -X POST https://api.pixelvault.dev/v1/uploads/img_abc123/describe \
  -H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN"
Response 200
{
  "data": {
    "id": "img_abc123",
    "description": {
      "status": "done",
      "alt": "A red fishing boat moored in a small harbour at sunset",
      "tags": [
        "boat",
        "harbour",
        "sunset"
      ]
    },
    "describe_skipped": "quota"
  }
}

Delete an image from a signed-in session

DELETE /v1/uploads/{id}

Permanently delete one of the signed-in account's images (the stored file and its record) and free its storage. Authenticates with a dashboard session token (JWT), not an API key: this is what the web dashboard's Delete button calls. Callers with an API key should use delete_image. An id that does not exist or belongs to another account returns 404.

Authentication

Dashboard session token (JWT) from the signed-in web app. API keys are not accepted.

Path parameters

Path parameters
Name Type Required Description
id string Required

Image id.

Responses

Request
curl -X DELETE https://api.pixelvault.dev/v1/uploads/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN"
Response 200
{
  "success": true
}