Conventions

These rules apply across the API. Each endpoint page in the reference lists its own details.

Requests

• Send JSON bodies with Content-Type: application/json. A body can be up to 500 KB.
• Query values are strings. Send numbers as plain digits, like limit=50.
• Lists in a query string are comma-separated, like categories=food,recipes. If you repeat a key, Auto uses the first value.
• Image and album ids use the letters A-Z, a-z, the digits 0-9, _ and -. They are at most 128 characters long.

Responses

A single object comes back in result:

{ "result": { "id": "alb_9", "title": "Lisbon 2026" } }

A list comes back in results, with paging details next to it:

{ "results": [], "pagination": { "total": 0, "offset": 0, "limit": 20 } }

Every field is always present. A field with no value is null, never left out. Times are ISO 8601 strings in UTC, such as 2026-04-12T18:22:05.000Z.

Errors

Errors use standard HTTP status codes. The body has one error field with a message you can show to a person:

{ "error": "Album not found" }

The one exception is 401, which has a message field instead.

Status	Means	What to do
400	A parameter or the body is not valid. The message names the field.	Fix the request.
401	The key is missing, wrong or revoked.	Check the Authorization header.
403	The image belongs to someone else.	Use an id from your own results.
404	Nothing with that id is readable.	Check the id. See Free plan window.
409	The request conflicts with the account state. For example, Auto Photos is not set up, or the account has 500 albums.	Show the message to the user.
502	Search is down for a moment.	Wait and retry.
5xx	Something failed on Auto's side.	Retry with backoff.

Don't parse the message text. It can change. Use the status code to decide what your code does.

Paging

Lists page in two ways.

Images. Image lists have limit (1 to 100) and no cursor. Results come newest first. To get the next page, set endDate to the capturedAt of the last image you got, then ask again. In these lists pagination.total is the number of results on the page.

# Page 1
curl -G .../ext/v2/images -d limit=100
# Page 2: everything older than the last image on page 1
curl -G .../ext/v2/images -d limit=100 -d endDate=2026-03-02T09:14:00.000Z

The endDate filter includes its own time. Skip ids you already have.

Albums. Use limit (1 to 100) and offset (0 to 500). Here pagination.total is the full number of albums.

Dates

startDate and endDate filter by capture time. Send ISO 8601. A time with no zone, like 2026-04-01T09:00, is read as UTC. A date alone, like 2026-04-01, means midnight UTC.

Places

To filter by place, send latitude, longitude and radiusMeters together. Auto returns images taken inside that circle. On a search, each result has distanceMeters from the center.

On List images, the circle filters only the newest images, so a page can come back short. For "photos taken in Lisbon", use Search images with the circle. Search covers the whole library.

Search

Search images needs at least one of these:

• query: plain words, such as receipt from the hardware store
• albumId: search in one album
• a full circle: latitude, longitude and radiusMeters

With a query, Auto matches on two channels and merges the results:

• image matches what the image looks like.
• text matches the image's description and any words in it, read by OCR. When this channel matches, matchedText holds the text that matched.

Results are ranked best first, and score holds the similarity. Set channels=text or channels=image to use one channel. You can't set channels together with a circle or an album.

Image URLs and renditions

Auto never serves the original file. It serves these renditions:

Name	Format	Size
webp-full	WebP	Full size
webp-medium	WebP	Longest side 1200 px
webp-thumb	WebP	Longest side 512 px

Each image has a url for the best display size. Get an image also fills renditions with a URL for every size. List and search leave renditions empty to stay fast.

These URLs are signed. They work for 15 minutes without a key, so you can put them straight into an <img> tag. After that, get the image again for fresh URLs. Don't store the URLs. Store the image id.

Auto Photos setup

Image and album endpoints need the user to have Auto Photos. If they don't, those endpoints answer 409 with a message that says how to install it.

Get library info never answers 409. Call it first. If totalImages is 0 or syncEnabled is false, show the user the help text and the installUrl.

Free plan window

On the free plan, Auto Photos keeps a window of the user's newest photos. Images outside that window, and deleted images, answer 404, as if they don't exist. Paid plans have no window.

Limits

Limit	Value
Results per page	100
Image ids per album call	100
Albums per account	500
Album title	1 to 100 characters
Request body	500 KB
Signed image URL life	15 minutes

The API has no published rate limit today. Keep to a few requests a second per key and back off on 5xx answers. Auto can add limits later to protect the service.

Changes

Auto adds endpoints and fields without notice. Your code must ignore fields it does not know. Breaking changes go in a new version path.