Import from pics.io
If your brand files live in pics.io, you can bring them into the Library with their collections and metadata. There are two routes, and which one you take depends on your pics.io plan:
- Your plan includes the pics.io API. Connect pics.io on a brand and import from inside Cauldron. You pick collections, Cauldron shows you exactly what will happen, then it copies the files for you.
- Your plan doesn’t include the API. Export your library from pics.io and ask an AI tool connected to Cauldron to move it over.
Either way, the import copies. It never changes or deletes anything in pics.io. Files land as drafts.
Which route is yours
Section titled “Which route is yours”Small and Enterprise plans include the pics.io API. Solo and Micro plans only have it with the paid add-on.
If you’re not sure, try connecting. When the plan can’t use the API, Cauldron says so and shows you the route without it. Nothing is saved.
Who can use it
Section titled “Who can use it”Anyone who can add files to a brand can import into it: a Creator or Brand manager on that brand, or a studio owner or admin. Viewers and Approvers see a note on the brand’s Integrations tab: “You need Creator access on brand to import here.” Ask a brand manager. Guests can’t import from pics.io, whatever their role on a brand.
Connect pics.io
Section titled “Connect pics.io”A pics.io connection belongs to one person and imports into one brand. Everyone on that brand’s team can see what it imports, and nobody else. To import into a second brand, connect again on that brand.
- Make a personal access token in pics.io. Click your avatar, then My account → Security → Personal access token. Copy the whole token.
- Open the brand’s Integrations tab in Cauldron, find pics.io, and click Connect. You can also start from Library → Import → From pics.io.
- Paste the token into Connect pics.io and click Connect.
Once connected, the pics.io row shows your pics.io email, your pics.io team, and when you connected, with an Import button.
The connection is read-only. Cauldron can list and copy files. It never changes anything in pics.io, and the token is stored encrypted.
If the token is refused
Section titled “If the token is refused”| Message | What it means |
|---|---|
| ”pics.io didn’t accept this token. Check you copied all of it, or make a new one.” | The token is wrong, incomplete, or was revoked. Paste it again or make a new one |
| ”Your pics.io plan doesn’t include the API, so Cauldron can’t read your library directly.” | Use the route without the API |
| ”This token can’t read your pics.io library. Your plan may not include the API, or your pics.io role can’t see the files.” | Ask a pics.io team admin about your role, or use the route without the API |
| ”pics.io didn’t answer. Nothing was saved — try again in a moment.” | pics.io is unreachable. Click Try again |
When the plan has no API, the dialog shows Bring pics.io over without the API, with the steps below and buttons to set up Claude Code and open this guide. You can open the same panel yourself from My plan doesn’t include the API.
Import from the app
Section titled “Import from the app”- Open the import. Click Import on the pics.io row of the brand’s Integrations tab, or pick Library → Import → From pics.io.
- Choose collections. Tick the collections you want. See Choose collections.
- Click Review plan once every pick is counted.
- Read the preview and make your choices. See Preview. Nothing has been copied yet.
- Click Import n files. The files are copied from pics.io straight to storage. You can close the window.
- Check the result when it’s done, then approve the drafts in the Library.
Choose collections
Section titled “Choose collections”The window opens on Choose collections and starts reading your pics.io library straight away. The tree fills in as it goes: “Scanning… n files in m collections so far”. You don’t have to wait. Keep picking, and the counts fill in.
Each collection shows its Files, Size, and how many it Can’t import. Use Filter collections to find one by name. Ticking a collection ticks everything inside it.
- An asset that sits in several collections is copied once and filed in each.
- Assets that aren’t in any collection appear as (not in a collection) once the whole library is read. They come along when everything is picked.
- Review plan stays off until every collection you picked is counted.
A library with more than 100,000 files. Counting stops and reads “This library holds more than 100,000 files, so counting stopped. Pick the collections you want and count just those.” Tick what you want and click Count just these.
Preview
Section titled “Preview”The preview shows every decision on one page. There’s no review step after it.
- Brand. Set by the connection. It can’t be changed here.
- Collections you picked. With a file count for each. Change collections takes you back.
- Collection depth. For deep libraries, pick fewer levels to join deeper collections into one name, like “Autumn 2026 / Originals”. The tree on the right follows the setting. Up to 8 levels are kept as collections.
- What comes with each file. How many files carry each kind of metadata. See What comes across.
- Bring my lightboards. Optional, off unless you turn it on. See Lightboards.
- Where it lands. On a first import, everything goes into a new collection named after pics.io and the date, with your pics.io collections inside it. On a later import you choose: Add to the collection from the earlier import, so files join the collections they came from, or Create a new collection.
- Duplicates. Files with identical content are matched. One of each is kept and filed everywhere its copies were, and the rest are left out.
- Can’t import. Files Cauldron can’t take, with the reason for each.
Files land as drafts. You’ll approve them in the Library before anyone works from them.
While it imports
Section titled “While it imports”The import runs on Cauldron’s servers, not in your browser. You can minimize the window, close it, or leave. The bell tells you when it’s done. It goes through four stages:
- Copy from pics.io. Straight from pics.io to storage.
- Process. Previews, sizes, and colors for each file.
- File into collections. Each file goes into every collection it was in on pics.io, with its keywords, rating, and comments.
- Done. Everything lands as a draft.
Comments are read from pics.io while the import runs, so the window counts them as they arrive: “Coming along: n comments so far.”
When it’s done
Section titled “When it’s done”The last step reads “n imported into collection” and “Everything is filed in the collections it had in pics.io.” It also shows what came along, such as “Came along: 120 comments, 3 lightboards”. Click Open in Library to review the drafts, or Import more from pics.io.
Before you cancel pics.io, compare these counts with your pics.io library.
What comes across
Section titled “What comes across”| From pics.io | In Cauldron |
|---|---|
| The file | The current version only. Older versions aren’t imported |
| Collections | Collections, nested the same way, up to the depth you chose |
| Keywords | Tags, by the keyword’s last name: “Product / Rings / Gold” becomes Gold. The first 20 per file |
| Description | The description |
| Rating | The rating |
| Comments | Comments on the file, with their author and date |
| Title, flag, color, custom fields, date added to pics.io | Kept on the file under “From pics.io” |
| Lightboards | Only if you turn on Bring my lightboards |
Every file lands as a draft, whatever its status was in pics.io.
Lightboards
Section titled “Lightboards”Lightboards are private in pics.io. Turning on Bring my lightboards makes them collections that everyone on the brand can see, so Cauldron asks you to confirm: “Make n private lightboards visible to everyone on brand?” Click Make them visible to bring them. They land in a Lightboards collection.
Import again without duplicates
Section titled “Import again without duplicates”Cauldron remembers what you’ve imported from pics.io. Pick the same collections again later and only new or changed files are copied. The rest show in the preview as already imported. This is also how you carry on after hitting a limit.
When something goes wrong
Section titled “When something goes wrong”pics.io stopped accepting the sign-in
Section titled “pics.io stopped accepting the sign-in”This happens when the token is revoked or expires in pics.io, or your pics.io access changes. The pics.io row on the Integrations tab reads “pics.io stopped accepting this connection. Reconnect to keep importing.”
- Before importing. The window reads pics.io stopped accepting the sign-in. Click Reconnect pics.io and paste a new access token. You go back to choosing collections with your picks kept. Nothing was imported.
- During an import. The import pauses: “pics.io stopped accepting the sign-in partway through. Files already imported are safe.” Reconnect with a new token, and the same import picks up where it stopped. Nothing is copied twice.
Some files failed
Section titled “Some files failed”If a few files don’t arrive, the last step lists them with a reason for each.
| Reason | What to do |
|---|---|
| ”Removed from pics.io since the preview” | The file was deleted in pics.io after you previewed |
| ”Grew past limit since the preview” | The file is now over the size limit for its type |
| ”pics.io didn’t send this file. Retrying usually works.” | Click Retry n failed |
| ”Storage was full when this file arrived” | Free up space or change plan, then retry. See Billing |
| ”Couldn’t read this file” | The file may be damaged. Check that it opens in pics.io |
| ”pics.io stopped accepting the sign-in before this file arrived” | Reconnect, then retry |
Retry n failed tries only the files that failed.
Canceling
Section titled “Canceling”To stop an import, click Cancel import and confirm. Files already imported stay in the Library as drafts. Your pics.io library is untouched. To bring in the rest later, import the same collections again, and only the missing files are copied.
Without the API
Section titled “Without the API”If your plan doesn’t include the pics.io API, export the library from pics.io and let an AI tool connected to Cauldron move it over. It matches each file to its metadata, shows you the plan first, and only uploads once you say yes.
- Export the metadata. In pics.io, export your library’s metadata as a CSV.
- Download the files. Download them as archives, 300 files at a time, with Organize files by collections turned on.
- Ask your AI tool to migrate. With Cauldron connected, point it at the CSV and the downloaded files and ask it to bring them into a brand. For example: “Migrate my pics.io export in ~/Downloads/picsio into the Acme brand.”
It uploads the files and files them into the Library through presign_uploads and import_assets. Collections, keywords, descriptions, ratings, and comments come along when they’re in the CSV, and files land as drafts. Running it again on the same export skips files that already arrived.
Import with a connected AI tool
Section titled “Import with a connected AI tool”If your plan includes the API, an AI tool connected to Cauldron can also run the in-app import for you. It uses the same preview, limits, and duplicate rules as the app.
- Connect pics.io in Cauldron first. An AI tool can’t do this for you. If you haven’t connected, it asks you to connect on the brand and tell it when you’re done.
- Ask for what you want. For example: “Import my pics.io collection Product Shoots into the Acme brand.”
- Read the preview. It tells you how many files will be imported, which are already in Cauldron, which duplicates are left out, what can’t be imported, and where everything lands. Nothing is copied until you say yes.
- Let it run. The import runs in Cauldron, so you can close your AI tool and check on it later.
Disconnect
Section titled “Disconnect”Open the brand’s Integrations tab, find your pics.io row, and click Disconnect.
- A confirmation reads “pics.io disconnected. Files you imported stay in the Library.”
- You can’t disconnect while one of your imports is running. Finish or cancel it first.
Disconnecting stops Cauldron using your token. To revoke the token itself, delete it in pics.io under My account → Security.
Studio owners and admins see every pics.io connection in the studio under Settings → Integrations, with whose it is and which brand it imports into. They can Remove anyone’s connection there.
Limits
Section titled “Limits”| Limit | Amount |
|---|---|
| New files copied in one import | 5,000 |
| Files selected in one import, including ones that won’t be copied | 20,000 |
| Files counted when reading your library | 100,000. Past that, count just the collections you pick |
| Imports running at once, per person | 2 |
| Imports started per hour, per person | 20 |
| Collection levels | 8. Deeper collections are joined into the last level’s name |
| Keywords brought in per file | The first 20 |
More than 5,000 files to copy? The preview says one import copies up to 5,000 files, and Import stays off. Untick some collections, import, then come back for the rest. Files already imported don’t count toward the 5,000.
More than 20,000 files selected? The preview reads “One import can look at up to 20,000 files. Untick some folders and import the rest next.”
Two imports already running? Starting a third reads “Two imports are already running. Start this one when one of them finishes.”
Troubleshooting
Section titled “Troubleshooting”“Couldn’t finish reading your pics.io library. Try again.” Reading the library was interrupted. Click Try again.
“That collection list was out of date, so we read your pics.io library again.” Something changed since Cauldron read your library. Check your picks and carry on.
There’s no pics.io option under Library → Import. You need Creator access on the brand. See Who can use it.
The import landed in the wrong brand. A connection only imports into the brand it was made on. Connect pics.io on the right brand and import again from there.