Photo To URL logo

API documentation

API access requires an active Pro or Premium subscription. Authenticate with an API key, then upload images to the same library you see in the Dashboard. Quotas match your paid plan on the website.

Product Images

Upload an image

POST /api/v1/upload with multipart/form-data.

Parameters

Authorization
Required. Request header. Format: Bearer YOUR_API_KEY.
file
Required. A binary file or base64 data.
name
Optional. Filename; auto-detected when you upload a local file via multipart.

Example request

Binary file

curl https://phototourl.com/api/v1/upload \
  -X POST \
  -H "Authorization: Bearer ptu_live_YOUR_KEY" \
  -F "file=@./product.jpg"

Base64

curl https://phototourl.com/api/v1/upload \
  -X POST \
  -H "Authorization: Bearer ptu_live_YOUR_KEY" \
  -F "file=R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" \
  -F "name=pixel.gif"

Always use POST when uploading a local file. GET is not supported for uploads.

Response fields

id
Resource id in your library.
url
CDN URL you can use on product pages.
fileName
Original filename.
fileSize
File size in bytes.
mimeType
MIME type of the uploaded file.
createdAt
Upload time in UTC, formatted as YYYY-MM-DD HH:mm:ss.
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
  "fileName": "product.jpg",
  "fileSize": 128472,
  "mimeType": "image/jpeg",
  "createdAt": "2026-11-05 10:20:30"
}

List images

GET /api/v1/images with optional page and pageSize (max 100).

curl "https://phototourl.com/api/v1/images?page=1&pageSize=20" \
  -H "Authorization: Bearer ptu_live_YOUR_KEY"

Response fields

resources
Array of images: id, fileName, url, fileSize, mimeType, createdAt.
page
Current page number.
pageSize
Items per page.
total
Total images in the library.
{
  "resources": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fileName": "product.jpg",
      "url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
      "fileSize": 128472,
      "mimeType": "image/jpeg",
      "createdAt": "2026-11-05 10:20:30"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

Delete an image

DELETE /api/v1/images/:id. Removes the file from storage and your library.

curl -X DELETE https://phototourl.com/api/v1/images/RESOURCE_ID \
  -H "Authorization: Bearer ptu_live_YOUR_KEY"

Response fields

success
true when the image was deleted.
{ "success": true }

Limits

API is not available on Free. Pro and Premium use your plan’s upload, storage, and file-size limits. When you exceed a limit, the API returns an error with upgradeUrl.

Errors

Failed requests return an error code. Quota errors may include upgradeUrl.

  • dailyLimitReached— Daily upload limit reached (HTTP 429).
  • storageLimitReached— Storage quota exceeded (HTTP 413).
  • fileTooLarge— File larger than your plan allows (HTTP 400).
  • 401— Missing, invalid, or revoked API key.
{
  "error": "dailyLimitReached",
  "errorParams": { "limit": 1000 },
  "plan": "paid",
  "limit": 1000,
  "upgradeUrl": "https://www.phototourl.com/pricing"
}