# Fondly Told — guide for AI agents

Fondly Told makes small printed photo books and keepsakes from a person's own Instagram Stories and posts. This page describes the service and its API so that an AI assistant can help someone make one.

_Guide updated 2026-09-21: a session is now **one upload and one link**. Earlier copies of this guide described sending small previews first; that is no longer needed._

**Status: private preview.** The service currently accepts photos and returns a preview of the book. Nothing is printed or shipped yet. A $1.00 test order is available to try the payment step; it is refunded.

Operated by InfoTech AI · hello@info-tech.ai · API description: https://fondlytold.com/openapi.json

## What the person gets
A small portrait-format book, one photo or story per page, in date order, with a cover title. After upload the API returns a **preview link** that opens on a phone.

Editions:
| Edition | For |
|---|---|
| Our Story So Far | a partner — anniversaries, Christmas, Valentine's |
| Still Our Story | a longer relationship, several years |
| The First Year | a baby's first year, often for grandparents |
| The Story Deck | a friend or group of friends (a deck of cards rather than a book) |

A useful first question for the person is **who the book is for** — it decides the edition, the title and which photos belong.

## Starting from nothing
Many people arrive without anything prepared. Before any request to Fondly Told, a session usually needs:
1. **Instagram connected** to the assistant. If it isn't, that comes first; the person connects their own account in the assistant's settings.
2. **Who the book is for and who should be in it** — a name and, for a partner or friend, their Instagram handle or a photo the person points to, so the right photos can be found. People who have made a book before may already have this remembered.
3. **The period** — "this year", "since we met", "the first year".
4. **Gathering candidates** from posts and the stories archive. This can take a few minutes on a large account; telling the person so, and roughly how many photos were found, keeps them oriented.

**People who have made a book before.** Books and links last 24 hours, so an earlier book is usually gone. When someone asks to make a book, that means a new one, from a fresh upload, unless they say they want to go back to an earlier one. It is worth re-reading this guide at the start of each session, as the service is changing quickly.

At every pause the person should know what happens next and what, if anything, they need to do — for example "open this link, choose your photos, and the preview and checkout follow on the same page".

## What content can be used
- Photos and story stills from the person's **own** connected Instagram account, including stories of theirs that reshare someone else's.
- Personal (non-professional) accounts are supported.
- Images from other people's accounts are not part of this service.

## How the service expects a session to go
The whole session is **one request and one link**.
1. The assistant gathers the candidate photos — usually 20 to 60 — and marks the ones it would suggest.
2. The person agrees to the upload, knowing: the candidates go to Fondly Told at full resolution, are stored for at most 24 hours during this preview, and the ones they leave out are deleted when they order.
3. The assistant uploads all candidates in **one** request (see Upload) and gives the person the `book_url` from the response.
4. On that page the person does everything else themselves: **chooses the photos → sees the book → changes it if they like → orders and pays.** Nothing needs to be pasted back into the chat, and the assistant does not need to make another request.

When a book is about a particular person, automatic matching of faces is often wrong. The selection step on the page is where the person corrects that, so a few doubtful candidates are better included than left out.

When handing over the link, it helps to say what is on it, for example: *"Here's your book. Pick the photos you want, and you'll see the book straight away — you can order from the same page."*

## Adding photos to a book
The book page has an **Add more photos** button. It gives the person a message to paste to their assistant, containing the book ID. The assistant then helps them find more photos (asking what they are looking for, and showing what it finds), and sends the chosen ones in **one** request to `POST https://fondlytold.com/v1/media?book=<book_id>`, numbered from `photo_1` again. The new photos appear ticked on the same `book_url`; the pages re-order themselves by date. Afterwards the person only needs to be told to open their book link again.

## Data the API accepts
Image files only — JPEG, PNG or WebP, at the highest resolution available. Story stills are fine. Video is not accepted during the preview.
Optional per image: a date and a kind. Other text fields (captions, usernames, names, locations, messages) are not used; if sent, they are discarded and listed in the response as ignored.

## Order codes
An order code, formatted `KEEP-XXXX-XXXX`, ties a person's requests together. It goes **in the URL** of each request: `?code=KEEP-XXXX-XXXX`. (A bearer header is also accepted, but the URL form is the dependable one.)
- If the person's message includes a code (they started on the website), that code is used.
- Otherwise **no separate step is needed**: the first request to `/v1/media` (or `/v1/orders`) sent without a code is accepted, and its response includes a new `order_code` to use from then on.

The person should be told their code; it lets them return to the same book. Codes are not guessable and are not shared between people.

## Number of requests
Each request to fondlytold.com may need the person's approval in their assistant, so the service is designed for as few as possible — a whole session is **one request**: the upload. Choosing, previewing, changing and paying happen on the page it returns. One optional status check exists for when the person asks whether their order went through. Failed requests return a message saying what to change; repeating the same request unchanged will fail the same way.

## Upload
```
POST https://fondlytold.com/v1/media          (add ?code=KEEP-XXXX-XXXX only if the person's message included one)
Content-Type: multipart/form-data
```
| Form field | Required | Value |
|---|---|---|
| `photo_1` … `photo_60` | yes | every candidate image, full resolution, in date order |
| `date_1` … | no | `YYYY-MM-DD` |
| `kind_1` … | no | `post`, `story` or `repost` |
| `pick_1` … | no | `1` for the photos the assistant suggests; they appear pre-selected. If no picks are sent, all photos start selected |
| `title` | no | cover title, up to 40 characters, e.g. `Our Story So Far` |

Limits: 60 images per request, 24 MB per file. One request is best. If more are needed, further batches go to the same URL with `?book=<book_id>` from the first response; numbering restarts at `photo_1`.

## Response
```json
{
  "ok": true,
  "book_id": "…",
  "summary": {"received": 23, "median_short_side_px": 1260, "min_short_side_px": 640},
  "print_quality": "good for a 6×6 in book",
  "book_url": "https://fondlytold.com/v1/books/…",
  "status_url": "https://fondlytold.com/v1/status?book=…",
  "order_code": "KEEP-XXXX-XXXX",
  "ignored_text_fields": [],
  "status": "Preview only. No order placed, nothing charged.",
  "files": [{"field": "photo_1", "width": 1260, "height": 2240, "detected_type": "image/jpeg"}]
}
```
What is useful to pass on to the person: the `book_url` with a sentence on what they'll do there (it stops working within 24 hours); the `print_quality` line in plain words; and, where `min_short_side_px` is below 900, which photos are small (from `files`). Uploading is not an order: nothing has been bought.

`status_url` needs no order code. It returns `stage`: `choosing`, `previewing`, `at_checkout` or `paid`. It is for answering the person if they come back and ask; there is no need to check it otherwise.

## Test order — $1.00, optional
The **Order this book** button on the book page takes the person to Stripe's checkout (card, Apple Pay, Google Pay or Link). It is a real $1.00 charge to the person's own payment method; checkout asks for a US shipping address to exercise that step; nothing ships, and Fondly Told refunds the charge. Afterwards the page tells them what happens next.

An assistant can also create the order itself — `POST https://fondlytold.com/v1/orders?code=<order code>` with body `{}` returns a `checkout_url` and a `status_url`, and `payment` details for Stripe shared payment tokens where switched on — but this costs a further request and is not needed when the person uses the page.

## Errors
| Response | Meaning |
|---|---|
| `401 order_code_missing` / `order_code_unreadable` / `order_code_unknown` | the response's `message` says what was received and what to send instead; `POST /v1/sessions` also issues a fresh code. On `/v1/media` and `/v1/orders` a lapsed code does not fail: a new `order_code` is issued and returned |
| `413 too_many_files` / `file_too_large` | over the limits above |
| `415` | request was not multipart/form-data |
| `422 no_files` | no image files were attached |
| `429 preview_full_today` | the preview's daily limit was reached |
| `501 payments_not_configured` | token payment isn't switched on yet; hosted checkout may still be |
| `5xx` | a fault on our side; one retry is reasonable |

Responses are returned as-is so they can be shown to the person. Preview links and confirmations only ever come from the API.

## Not available yet
Printing, shipping, video, and page layout editing beyond choosing photos. These are planned; the current step is the preview.