#Image List & Search

Query your image library with filtering, full-text search, and cursor-based pagination.

#Authentication

Include your credentials in every request:

X-Client-Id: px_cl_your_client_id
X-Client-Secret: pk_your_secret_key

#List Images

GET /api/{project}/images

Returns a paginated list of images for a project.

#Query Parameters

Parameter

Type

Default

Description

limit

int

50

Number of images to return per page

cursor

string

—

Pagination cursor from a previous response's nextCursor

search

string

—

Full-text search across image ID, filename, and name

category

string

—

Filter by category (exact match, case-insensitive)

keyword

string

—

Filter by keyword (contains match, case-insensitive)

author

string

—

Filter by author (contains match, case-insensitive)

isVideo

bool

—

true for videos only, false for images only

folder

string

—

Filter by folder path (exact match). Empty string returns root-level only

includeDerived

bool

false

Include EPS-derived assets (rasterizations, page splits)

#Response 200 OK

{
  "images": [
    {
      "imageId": "img_01JKXYZ",
      "projectId": "myapp",
      "originalFileName": "hero-banner.jpg",
      "contentType": "image/jpeg",
      "sizeBytes": 2456789,
      "width": 4000,
      "height": 3000,
      "name": "Hero Banner",
      "caption": "Mountain landscape at sunset",
      "category": "portfolio",
      "folder": "portfolio/landscapes",
      "keywords": ["landscape", "mountain", "sunset"],
      "author": "Jane Doe",
      "uploadedAt": "2026-03-15T10:30:00Z"
    }
  ],
  "nextCursor": "img_01JKXYW"
}

The nextCursor field is null when there are no more results. Pass it as the cursor parameter to fetch the next page.

#Examples

# List first 20 images
curl "https://img.pixault.io/api/myapp/images?limit=20" \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"
# Search by text
curl "https://img.pixault.io/api/myapp/images?search=sunset"
# Filter by category
curl "https://img.pixault.io/api/myapp/images?category=headshot"
# Filter by keyword
curl "https://img.pixault.io/api/myapp/images?keyword=landscape"
# Filter by folder
curl "https://img.pixault.io/api/myapp/images?folder=portfolio/landscapes"
# Videos only
curl "https://img.pixault.io/api/myapp/images?isVideo=true"
# Paginate through results
curl "https://img.pixault.io/api/myapp/images?limit=50&cursor=img_01JKXYW"
# Combine filters
curl "https://img.pixault.io/api/myapp/images?category=portfolio&author=Jane&keyword=mountain"

#Get Image Metadata

GET /api/{project}/{imageId}/metadata

Returns the full metadata for a single image.

curl https://img.pixault.io/api/myapp/img_01JKXYZ/metadata \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"

#Response 200 OK

Returns the full ImageMetadata object.

#Response 404 Not Found

Image does not exist in the project.

#Delete Image

DELETE /api/{project}/{imageId}

Permanently deletes an image and all its cached transform variants.

curl -X DELETE https://img.pixault.io/api/myapp/img_01JKXYZ \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"

#Response 204 No Content

Image deleted. Storage usage is updated automatically.

#Delete Folder

DELETE /api/{project}/folders/{folderPath}

Deletes a folder and all images within it.

curl -X DELETE https://img.pixault.io/api/myapp/folders/portfolio/landscapes \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"

#Response 204 No Content

Folder and all contained images deleted.