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

[API reference](/docs/api/)

# 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.

-   GET [List and search images from a signed-in session](#dashboard_list_images)
-   POST [Upload an image or PDF from a signed-in session](#dashboard_upload)
-   GET [List the account's AI tags with counts (signed-in session)](#dashboard_list_tags)
-   POST [Start an AI description for an existing image (signed-in session)](#dashboard_describe_image)
-   DELETE [Delete an image from a signed-in session](#dashboard_delete_image)

## 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`](/docs/api/images/#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`](/docs/errors/#validation_error): `q` longer than 100 characters, more than 20 or malformed `ids`, or an invalid `tag`.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no dashboard session, or it is invalid or expired.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 1,200 list requests per hour from this IP.
    

Request

curlNode.jsPython

```
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`](/docs/api/images/#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

-   201
    
    Image stored
    
-   400
    
    [`missing_file`](/docs/errors/#missing_file): no `file` field. [`invalid_file`](/docs/errors/#invalid_file): the bytes are not a supported image or PDF.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no dashboard session, or it is invalid or expired.
    
-   402
    
    [`upload_limit_reached`](/docs/errors/#upload_limit_reached), [`storage_limit_reached`](/docs/errors/#storage_limit_reached): a plan quota is full. Plan ceilings, not rate limits.
    
-   403
    
    [`email_verification_required`](/docs/errors/#email_verification_required): an unverified account already stores 5 images. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    `no_project`: the account has no project to upload into.
    
-   413
    
    [`file_too_large`](/docs/errors/#file_too_large): larger than the plan's per-file cap (5 MB Free, 10 MB Starter, 15 MB Pro).
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 200 uploads per hour for the account (or 300 requests per hour from one IP). Honour `Retry-After`.
    

Request

curlNode.jsPython

```
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`](/docs/api/uploads/#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`](/docs/errors/#unauthorized): no dashboard session, or it is invalid or expired.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 1,200 list requests per hour from this IP.
    

Request

curlNode.jsPython

```
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`](/docs/api/uploads/#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`](/docs/errors/#unauthorized): no dashboard session, or it is invalid or expired.
    
-   403
    
    [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no such image in this account.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 200 dashboard writes per hour for the account (or 300 from one IP).
    

Request

curlNode.jsPython

```
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`](/docs/api/images/#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

-   200
    
    Image deleted
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no dashboard session, or it is invalid or expired.
    
-   404
    
    [`image_not_found`](/docs/errors/#image_not_found): no such image in this account.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 300 dashboard writes per hour from this IP.
    

Request

curlNode.jsPython

```
curl -X DELETE https://api.pixelvault.dev/v1/uploads/img_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN"
```

Response 200

```
{
  "success": true
}
```
