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
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Optional | Filename or AI-description search text (max 100 characters). |
tag | string | Optional | Only images carrying this AI tag (one tag: letters, digits, spaces or hyphens, lowercased). Combines with |
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). |
offset | integer | Optional | Images to skip (max 100,000). |
Responses
- 200
A page of images
- 400
validation_error:qlonger than 100 characters, more than 20 or malformedids, or an invalidtag. - 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.
curl https://api.pixelvault.dev/v1/uploads \
-H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN" {
"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
| 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 |
Responses
- 201
Image stored
- 400
missing_file: nofilefield.invalid_file: the bytes are not a supported image or PDF. - 401
unauthorized: no dashboard session, or it is invalid or expired. - 402
upload_limit_reached,storage_limit_reached: a plan quota is full. Plan ceilings, not rate limits. - 403
email_verification_required: an unverified account already stores 5 images.account_suspended: the account is suspended. - 404
no_project: the account has no project to upload into. - 413
file_too_large: larger than the plan's per-file cap (5 MB Free, 10 MB Starter, 15 MB Pro). - 429
rate_limit_exceeded: more than 200 uploads per hour for the account (or 300 requests per hour from one IP). HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/uploads \
-H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN" \
-F "file=@photo.jpg" \
-F "describe=true" {
"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.
curl https://api.pixelvault.dev/v1/uploads/tags \
-H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN" {
"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
| 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).
curl -X POST https://api.pixelvault.dev/v1/uploads/img_abc123/describe \
-H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Image id. |
Responses
- 200
Image deleted
- 401
unauthorized: no dashboard session, or it is invalid or expired. - 404
image_not_found: no such image in this account. - 429
rate_limit_exceeded: more than 300 dashboard writes per hour from this IP.
curl -X DELETE https://api.pixelvault.dev/v1/uploads/img_abc123 \
-H "Authorization: Bearer $PIXELVAULT_SESSION_TOKEN" {
"success": true
}