curl examples

Set your key once in your shell, then copy-paste any of the recipes below.

export PHOTOPICK_API_KEY="pp_live_xxxxxxxxxxxxxxxx"
export PHOTOPICK_API="https://api.photopick.cz/api/v1"

1. Verify your key (`/me`)

Smallest possible request. Confirms the key is alive and shows its scopes and rate limit.

curl -sS "$PHOTOPICK_API/me" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" | jq

{
  "apiKeyId": 42,
  "customerId": 7,
  "name": "Integration with X",
  "scopes": ["customer:read", "photos:read", "tags:read"],
  "rateLimit": { "limit": 300, "remaining": 299, "reset": 1748340060 }
}

Required scope: customer:read.

2. List photos (paginated)

Fetch the first page of 50 photos, then follow the cursor.

# First page
curl -sS "$PHOTOPICK_API/photos?limit=50" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" | jq '.data | length, .pagination'

# Next page (cursor from previous response)
curl -sS "$PHOTOPICK_API/photos?limit=50&cursor=eyJpZCI6MTI4NX0" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" | jq

Loop until done:

CURSOR=""
while :; do
  URL="$PHOTOPICK_API/photos?limit=100${CURSOR:+&cursor=$CURSOR}"
  RES=$(curl -sS "$URL" -H "Authorization: Bearer $PHOTOPICK_API_KEY")
  echo "$RES" | jq '.data[] | .id'
  HAS_MORE=$(echo "$RES" | jq -r '.pagination.hasMore')
  [ "$HAS_MORE" = "true" ] || break
  CURSOR=$(echo "$RES" | jq -r '.pagination.nextCursor')
done

Required scope: photos:read.

3. Fetch a single photo + download original

Two-step: read metadata, then fetch the file.

PHOTO_ID=1234

# Metadata
curl -sS "$PHOTOPICK_API/photos/$PHOTO_ID" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" | jq

# Original file → ./photo-1234.jpg
curl -sS -L "$PHOTOPICK_API/photos/$PHOTO_ID/download" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" \
  -o "photo-$PHOTO_ID.jpg"

# Resized + re-encoded variant — Full HD WebP
curl -sS -L "$PHOTOPICK_API/photos/$PHOTO_ID/download?size=fhd&format=webp" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" \
  -o "photo-$PHOTO_ID-fhd.webp"

The download endpoint returns the original binary file with the correct Content-Type and a redirect to a short-lived signed URL (handled transparently by curl -L).

Two optional query params control resize and re-encoding (defaults match the original):

Param	Values	Meaning
`size`	`original` (default), `a4`, `fhd`, `web`	Output dimensions. `original` = untouched. `a4` = print-ready A4. `fhd` = 1920px long edge. `web` = web-thumbnail.
`format`	`original` (default), `jpeg`, `webp`	Output encoding. `original` = source format. `jpeg` / `webp` re-encode.

Required scope: photos:read.

4. Tag CRUD

Create a tag, attach it to a photo, list, rename, delete.

# Create
TAG=$(curl -sS -X POST "$PHOTOPICK_API/tags" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Selects","color":"#e94b60"}')
TAG_ID=$(echo "$TAG" | jq -r '.id')

# Attach to photo (replaces full tag list on that photo)
curl -sS -X PUT "$PHOTOPICK_API/photos/1234/tags" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"tagIds\":[$TAG_ID]}" | jq

# List all tags
curl -sS "$PHOTOPICK_API/tags" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" | jq '.data[] | {id, name}'

# Rename
curl -sS -X PATCH "$PHOTOPICK_API/tags/$TAG_ID" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Final selects"}' | jq

# Delete
curl -sS -X DELETE "$PHOTOPICK_API/tags/$TAG_ID" \
  -H "Authorization: Bearer $PHOTOPICK_API_KEY" -w "\nHTTP %{http_code}\n"

Required scopes: tags:write (create, rename, delete), tags:read (list), photos:write (attach).

What’s next

Try these from the browser in the API reference — Scalar’s try-it-out renders the same requests interactively.
Handle errors gracefully — see Errors for the codes you’ll encounter.
Respect the budget — see Rate limits for retry patterns.