Images API

Endpoints for listing and managing images in your Picora library.

List Images

Retrieve a paginated list of your uploaded images, sorted by upload date (newest first).

Endpoint

GET https://api.picora.com/v1/images

Authentication

Requires Bearer token (API key or JWT access token).

Query Parameters

Parameter	Type	Required	Description
`cursor`	string	No	Pagination cursor from the previous page’s `nextCursor`. Omit for the first page.
`limit`	number	No	Number of images per page. Default: `20`. Maximum: `100`.
`tag`	string	No	Filter by tag name. Returns only images with this tag.

Example Request

# First page
curl "https://api.picora.com/v1/images?limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Next page (using cursor from previous response)
curl "https://api.picora.com/v1/images?cursor=eyJpZCI6IlhLOU1SMlBRN3ZCIiwiY3JlYXRlZEF0IjoiMjAyNi0wNC0xNiJ9&limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "xK9mR2pQ7vB",
        "url": "https://img.picora.com/xK9mR2pQ7vB.webp",
        "filename": "photo.jpg",
        "size": 102400,
        "width": 1920,
        "height": 1080,
        "is_public": true,
        "tags": ["blog", "2026"],
        "created_at": "2026-04-17T08:00:00.000Z"
      }
    ],
    "nextCursor": "eyJpZCI6IlhLOU1SMlBRN3ZCIiwiY3JlYXRlZEF0IjoiMjAyNi0wNC0xNiJ9",
    "total": 142
  }
}

Response Fields

Field	Type	Description
`items`	array	Array of image objects for this page.
`nextCursor`	string \| null	Cursor for the next page. `null` if this is the last page.
`total`	number	Total number of images in your library (not limited to current page).

Delete Image

Permanently delete an image from your library and storage.

Endpoint

DELETE https://api.picora.com/v1/images/:id

Path Parameters

Parameter	Type	Description
`id`	string	The 11-character image ID (from the image URL or list response).

Example Request

curl -X DELETE "https://api.picora.com/v1/images/xK9mR2pQ7vB" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response

Status: 204 No Content

No response body is returned on success.

Error Responses

Status	Code	Description
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`403`	`FORBIDDEN`	The image belongs to a different user.
`404`	`NOT_FOUND`	No image with this ID exists in your library.
`500`	`INTERNAL`	Internal server error.