Use the API from an agent

This page is for AI agents that call HTTP endpoints, and for the people who write their instructions. You can paste the Agent rules section into a system prompt or a skill file.

If your agent runtime supports MCP, use the MCP server instead. It signs the user in with OAuth, so nobody has to handle a key, and it can show images to the user inline. See the MCP agent guide.

Setup

• Read the key from the AUTO_API_KEY environment variable. If it is not set, stop and ask the user to set it. Never guess or invent a key.
• The base URL is https://app.auto.inc/api.
• Send Authorization: Bearer $AUTO_API_KEY on every request.
• Never print the key, write it to a file, or put it in a URL.

A shell helper that fails fast when the key is missing:

: "${AUTO_API_KEY:?Set AUTO_API_KEY to your Auto API key}"
auto() {
  curl --fail-with-body -sS -G \
    -H "Authorization: Bearer $AUTO_API_KEY" \
    "https://app.auto.inc/api$1" "${@:2}"
}

auto /ext/v2/images/search --data-urlencode "query=passport"

--fail-with-body makes curl exit with an error on 4xx and 5xx and still print Auto's message.

Agent rules

1. Call GET /ext/v2/info first. If totalImages is 0 or syncEnabled is false, show the user the help text and stop. Don't call other endpoints until the user has set up Auto Photos.
2. Search, don't scan. To find something, call GET /ext/v2/images/search with a query in plain words. Don't page through the whole library to look for it.
3. Use a circle for places. For "photos from Lisbon", geocode the place yourself and call search with latitude, longitude and radiusMeters. Don't use the circle on the list endpoint. There it filters only the newest images.
4. Use dates for time. For "last March", set startDate and endDate in ISO 8601 UTC.
5. Ask for small pages. Start with limit=10 or 20. Raise it only when the user wants more.
6. Show the image, don't describe the URL. Each result has a signed url that works for 15 minutes. Link it or render it. Don't save it for later turns. Fetch the image again by id instead.
7. Albums are safe to repeat. POST /ext/v2/albums reuses an album with the same title. You don't need to list albums first.
8. Confirm before you delete. Ask the user before DELETE /ext/v2/albums/{id}, unless they named that album. Deleting an album keeps its images.
9. Read missing. Album calls return ids they could not use in missing. Tell the user if any were skipped.
10. Pass messages on. A 409 message is written for the user. Show it to them as it is.

Answer shapes

• One object: {"result": {...}}
• A list: {"results": [...], "pagination": {"total", "offset", "limit"}}
• An error: {"error": "..."}, or {"message": "Unauthorized"} for a bad key

Each image has id, url, capturedAt, placeLabel, description, details and albumIds. On a search, score holds the match strength and matchedText holds the words that matched. See the Image schema for every field.

Paging

Image lists have no cursor. To go further back, call again with endDate set to the capturedAt of the last result, and skip ids you already have. Stop when a page brings no new ids.

Errors

Status	Do this
400	Read the message. Fix the named parameter and try once more.
401	Stop. Tell the user the key is not valid.
404	The id is wrong, the image was deleted, or it is outside the free plan window. Don't retry.
409	Show the message to the user.
502	Search is down. Wait a few seconds and retry once.

Limits

• At most 100 results per call.
• At most 100 image ids per album call.
• At most 500 albums per account.
• Signed image URLs last 15 minutes.