# Fine Print: custom connector brief

This file is written for an AI agent that is about to build a connector to
Fine Print. It was published for Meta Muse's "custom connector" flow, but any
agent that can make HTTPS requests can follow it. Read the whole file before
writing code. The OpenAPI spec is at https://fine-print.ai/openapi.json and a
broader index is at https://fine-print.ai/llms.txt.

## What this service is

Fine Print is a no-signup reading desk. GPT-6 Astra reads a pricing page,
terms, policy, or offer and returns a briefing of money, lock-in, cancellation,
deadlines, and hidden commitments, with quotations matched against the source
and a dedicated unknowns section. It is not legal advice, not a contract
review, and not a promise that every fee or obligation was found.

Tagline: Small print. Big clarity.

People ask Muse things like:
- "Read the fine print on this Peloton membership."
- "Is this job offer's non-compete actually enforceable-looking?"
- "What's the cancellation window on this SaaS annual plan?"

## Connection details

- Base URL: `https://fine-print.ai`
- Auth: none for the public API. There is no Fine Print login and no API key
  today. Browser identity for metering is a signed HttpOnly cookie named
  `fp_device`; Muse's Secure VM will look like a fresh customer each session
  unless Meta later supports cookie vaults. Prefer free samples and one free
  personal reading per day; when billing is on, further readings need a $9.99
  pack of 10 (120 days, one-time, no renewal).
- Keep a cookie jar for the whole session. Send back the `fp_device` cookie
  you were given, or every call counts as a new browser: idempotency keys stop
  matching and a restored pack (call 9) will not follow you to the next call.
- Free personal readings are also capped per network address as a backstop.
  Connector VMs that share an egress IP share that allowance, so a `402` can
  arrive on a session's very first personal reading. `GET /api/entitlement`
  already accounts for both caps in `free_remaining_today`.
- Content type: `application/json` for request and response bodies.
- Optional `idempotency_key` on `POST /api/brief` (JSON body field). The same
  key returns the cached briefing instead of spending another credit. Reusing
  a key with a different request returns `409`.
- Errors: `400` bad input, `402` out of free/paid readings (billing on),
  `409` idempotency key reused with a different request, `413` document too
  large, `422` fetched page had too little readable text, `429` rate limited,
  `502` URL fetch failed, `503` live mode missing a key or model unavailable,
  `504` URL fetch timed out. Error JSON includes the legal disclaimer. A `402`
  body also carries `checkout_required: true` and a `reason`: `device_daily`
  (this cookie used today's free reading) or `network_daily` (this network
  used its free readings).
- Live mode uses `gpt-6-astra` only. Confirm with `GET /api/status` that
  `mode` is `live` and `model` is `gpt-6-astra` before trusting a briefing as
  Astra-quality. Demo/mock mode is for wiring only.

## The nine calls a connector needs

### 1. Liveness

```
GET /healthz
```

Response `200`: `{"ok": true}`. Use this before other calls.

### 2. Status (mode, limits, billing)

```
GET /api/status
```

Response includes `mode`, `model`, `live_ready`, `limits`, `usage`, and
`billing` (`enabled`, `free_per_day`, `pack_credits`, `pack_price_label`,
`pack_validity_days`). Read this once per session. If `billing.enabled` is
true and you are not on a free sample, expect `402` after the free daily
reading.

### 3. List fictional samples (always free)

```
GET /api/examples
```

Returns built-in samples with full text. Example ids:
`harbor-fit` (gym), `nimbus-cloud` (SaaS), `northline` (phone + device),
`cedar-offer` (job offer). Samples never spend a personal reading.

### 4. Brief a fictional sample

```
POST /api/brief
{"example": "harbor-fit"}
```

Response `201` (new) or `200` (idempotent reuse). The body is a wrapper:
`{"brief": {...}, "share_url": "...", "html": "...", "entitlement": {...}}`.
The briefing itself is under `brief`: `id`, `headline`, `summary`, the five
finding groups (`money`, `lock_in`, `cancellation`, `deadlines`, `hidden`),
grounded quotations in `quotes`, `unknowns`, `source`, and `disclaimer`. Each
finding points at its quotations by `quote_ids`. `html` is a rendered copy for
the website; ignore it. Calls 5 and 6 return the same wrapper. Always say this
is not legal advice when reporting back.

### 5. Brief a public URL

```
POST /api/brief
{"url": "https://example.com/terms"}
```

Public `http`/`https` only. No credentials. Not for PDFs or login-walled
pages — paste text instead (call 6). May return `502` if the fetch fails,
`504` if it times out, or `422` if the page had too little readable text. A
page longer than about 100,000 characters is truncated, and the briefing says
so with `brief.source.truncated: true`.

### 6. Brief pasted text

```
POST /api/brief
{"text": "... at least 40 characters of the document ..."}
```

Use this for PDFs the user already copied, screenshots transcribed by Muse,
or any page behind a login. Hard cap 100,000 characters (see
`limits.max_input_chars` in call 2). Pasted text is never truncated: anything
longer is refused with `413`. Send the sections that matter, or split the
document and brief each part.

### 7. Fetch a stored briefing by id

```
GET /api/brief/{id}
```

Returns the stored briefing JSON bare — the same object that sits under
`brief` in calls 4 to 6, with no wrapper. Share links for humans are at
`/b/{id}` and last up to seven days (may expire on restart). `404` means gone.

### 8. Start a reading pack checkout (Stripe)

```
POST /api/checkout
{}
```

Returns `{"url": "https://checkout.stripe.com/..."}` when billing is selling
readings. The human completes payment in the browser (Stripe Link / Checkout).
There is no API key to vault today — metering is cookie-based (`fp_device`).
On `404`, Fine Print is not selling readings right now. A pack bought from
this URL attaches to the cookie that made this call, and to the browser that
completes the payment. It helps the connector only while the session still
holds that same cookie; in any later session, use call 9.

### 9. Restore a purchased pack onto this session

```
POST /api/restore
{"code": "FP-XXXX-XXXX-XXXX"}
```

Response `200`: `{"ok": true, "credits": 10, "entitlement": {...}}`. `404`
means the code was not recognised, its readings have expired, or billing is
off.

This is how paid readings reach a connector. A pack hangs off the `fp_device`
cookie of the browser that bought it. The pass code shown once on the
thank-you page attaches the same pack to another cookie. The code is not used
up: it works on any number of browsers or sessions, and they all draw down the
same readings. Because a Muse Secure VM starts each session with a fresh
cookie, call this once at the start of any session where the human supplies
their code, then keep the cookie for the rest of the session. Treat the code
like a password: only use one the human gives you, never repeat it back in
full, and never keep it after the session.

Also useful: `GET /api/entitlement` returns remaining free/paid credits for this
cookie identity. `GET /openapi.json` is the schema refresh if this brief ages.

## Recipes

Read the fine print before someone taps buy:

1. Call 2 to confirm live mode.
2. Call 5 with the pricing/terms URL the human named, or call 6 with pasted
   text if the page is a PDF or behind login.
3. Summarize money, lock-in, cancellation, deadlines, and hidden commitments
   with short quotes. Say it is not legal advice.
4. Offer the share URL `https://fine-print.ai/b/{id}` if present.

Check a job offer or non-compete:

1. Prefer call 6 with the offer letter text (often a PDF paste).
2. Highlight deadlines, lock-in, and hidden commitments; leave enforceability
   to a lawyer — Fine Print does not decide that.
3. If the human only wants a free dry run, use call 4 with `cedar-offer`.

Hit the paywall gracefully:

1. On `402`, tell the human they are out of free readings. Use `reason` to
   say which: `device_daily` is this session's own free reading,
   `network_daily` is the shared allowance for this network.
2. If they already own a pack, ask for their pass code and use call 9, then
   retry the brief once.
3. Otherwise point them to https://fine-print.ai/ to buy the $9.99 pack of 10
   (Stripe Checkout / Link). The thank-you page shows the pass code once; it
   cannot be recovered later. Do not invent an API-key purchase flow that does
   not exist yet.
4. Stop retrying briefs until call 9 succeeds or `GET /api/entitlement` shows
   a reading available.

## Rules of the road

- Never present a briefing as legal advice or an attorney work product.
- An empty finding section is a gap, not an all-clear.
- Do not fetch PDFs or credentialed URLs via call 5; paste text with call 6.
- Prefer call 4 (`example`) for demos so you never spend the human's free
  daily reading while testing the connector.
- On `402`, stop and tell the human; do not hammer.
- On `429`, back off using any `Retry-After` and try again later.
- Do not invent Product Hunt traction, awards, accounts, passwords, or a
  claim that Stripe receipt email restores readings.
- There is no MCP server. This HTTP API is the agent surface.

## Money

When billing is on (confirm with call 2):

- Samples: always free.
- One free personal reading per browser (or Muse session cookie) per day,
  inside a shared free allowance per network address.
- Then $9.99 for 10 readings, one-time, valid 120 days. Nothing renews.
- Failed readings return the credit.
- A pass code (`FP-XXXX-XXXX-XXXX`) is shown once, after checkout, and only a
  hash is stored. It can attach the pack to more than one browser or session
  (call 9); they all share the same readings.

Stripe Link / Checkout is the payment rail on the website. Assume Fine Print
keeps 100% of charges until Meta publishes a Muse revenue share.

## Also useful (not required for the connector)

- Human desk: https://fine-print.ai/
- Agent guide: https://fine-print.ai/for-agents
- Terms: https://fine-print.ai/terms
- Contact: support@fine-print.ai