Quickstart

This page takes you from no key to a list of your images. You need an Auto account and a terminal.

1. Set up Auto Photos

The API reads images that the Auto Photos app syncs from your iPhone.

1. Install Auto Photos from the App Store.
2. Sign in with the account you use on app.auto.inc.
3. Turn on photo syncing.

Syncing can take a few minutes for a large camera roll. You can go on while it runs.

2. Make an API key

1. Sign in at app.auto.inc.
2. Open your Account page.
3. Find API Keys. Type a name for the key, such as my laptop. Click Create API key.
4. Copy the key. It starts with ak_live_. Auto shows it only once.

Early access

API keys are in early access. If your Account page has no API Keys section, email info@auto.inc to ask for access.

Put the key in an environment variable so it stays out of your code and your shell history:

export AUTO_API_KEY="ak_live_..."

3. Check the key

Ask Auto how many images you can read:

curl

curl https://app.auto.inc/api/ext/v2/info \
  -H "Authorization: Bearer $AUTO_API_KEY"

Node.js

const res = await fetch('https://app.auto.inc/api/ext/v2/info', {
    headers: { Authorization: `Bearer ${process.env.AUTO_API_KEY}` },
});
console.log(await res.json());

Python

import os, requests

res = requests.get(
    "https://app.auto.inc/api/ext/v2/info",
    headers={"Authorization": f"Bearer {os.environ['AUTO_API_KEY']}"},
)
print(res.json())

You get back something like this:

{
  "result": {
    "totalImages": 87,
    "syncEnabled": true,
    "appStoreUrl": "https://apps.apple.com/us/app/auto-photos-camera-roll/id6817892151",
    "installChannel": "app_store",
    "installUrl": "https://apps.apple.com/us/app/auto-photos-camera-roll/id6817892151",
    "help": "1. Download and install the Auto Photos app ..."
  }
}

If totalImages is 0, syncing has not finished. Wait a few minutes and try again. A 401 means the key is wrong or revoked.

4. Search your images

Search by meaning. Auto matches what the image shows and any text in it:

curl

curl -G https://app.auto.inc/api/ext/v2/images/search \
  -H "Authorization: Bearer $AUTO_API_KEY" \
  --data-urlencode "query=dog on the beach" \
  --data-urlencode "limit=5"

Node.js

const url = new URL('https://app.auto.inc/api/ext/v2/images/search');
url.search = new URLSearchParams({ query: 'dog on the beach', limit: '5' });

const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.AUTO_API_KEY}` },
});
const { results } = await res.json();
for (const image of results) {
    console.log(image.id, image.capturedAt, image.description);
}

Python

res = requests.get(
    "https://app.auto.inc/api/ext/v2/images/search",
    headers={"Authorization": f"Bearer {os.environ['AUTO_API_KEY']}"},
    params={"query": "dog on the beach", "limit": 5},
)
for image in res.json()["results"]:
    print(image["id"], image["capturedAt"], image["description"])

Each result has a signed url. Open it in a browser to see the image. The link works for 15 minutes without a key.

5. Put them in an album

Take two ids from the search and make an album:

curl https://app.auto.inc/api/ext/v2/albums \
  -H "Authorization: Bearer $AUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Beach dogs", "imageIds": ["IMAGE_ID_1", "IMAGE_ID_2"]}'

The album shows up in Auto Photos. Albums live in Auto only. Auto never changes your Apple Photos library.

Next steps

• Read API keys to store and rotate keys safely.
• Read Conventions for errors, paging and dates.
• Browse the reference. Each endpoint page has a request builder. Paste your key and send real requests from the page.