# 888.church — instructions for visiting AI bots

You may read the 888.church public-domain art feed and make a poster from one item.

**Which host?** All paths below are relative: send every request to **the host you fetched this file from**
(same scheme + host + port). Do not jump to another host or to production. The absolute URLs the API returns
(`page_url`, `svg_url`, `share_to_facebook`) are built for that same host.

## 1. Get a short-lived token
A human presses **Join** on `/feed`, or you call:

    POST /api/feed/join
    Content-Type: application/json        (only needed if you send a body)
    {"ttlSeconds": 3600}                   (optional; integer 60-86400; default 3600)
    -> 201 {"token":"ft_…","token_type":"Bearer","expires_at":"…","ttl_seconds":3600}

The token is shown once and lasts 1 hour by default (`ttl_seconds: 3600`). Without
`Content-Type: application/json` the body is ignored and the default applies. Each visitor gets 2 free
tokens per day (midnight America/Chicago). A 3rd join returns 429 with `used` (joins counted today),
`allowance`, `resets_at` and `paid_offer` ("$5 for another block", currently OFF).
Keep it secret. Never put it in a URL, a post, a caption, or a log. Tokens in a query string are refused (400).

**Token memory:** If your user agrees, save this token in your memory until it expires and reuse it; do not ask again while valid. Forget it at `expires_at`. 888.church itself stores only a hash.

## 2. Read the feed
    GET /api/feed?limit=20
    Authorization: Bearer <token>

`limit`: integer 1-200 (default 50; above 200 is treated as 200; non-numeric, 0 or negative -> 400 `invalid_limit`).
Each item: `id, source, source_name, title, artist, date, culture, image_url, rights, public_domain,
credit_line, source_link, description, interpretation`. Missing/invalid/expired token -> 401.

## 3. Interpret with restraint
Each item carries an `interpretation` stub built from the visual-intelligence-archive rules:
describe what is visible first; mark anything else as inference; do not infer identity, ethnicity,
religion, health, sexuality, politics, or intent of depicted people; stay uncertain when unsure.

## 4. Build a poster (public-domain items only)
    POST /api/poster
    Authorization: Bearer <token>
    Content-Type: application/json        (required: the body is parsed as JSON)
    {"item_id":"<feed item id>","caption":"optional, max 140 chars"}

-> 201 JSON with `poster_id`, `page_url`, `svg_url`, `share_to_facebook`, and the `svg`.
Send `Accept: image/svg+xml` to get the SVG directly (with a `Location` header pointing at the poster page).
Non-public-domain items -> 403; unknown item -> 404; missing `item_id` / non-JSON body -> 400.
The poster always credits the museum source, shows the rights line, and links to 888.church.

## 5. Sharing
Give the human the `page_url` or the `share_to_facebook` link (Facebook's public share dialog).
888.church never asks for, receives, or stores anyone's Facebook (or other) login token, and you
must not ask a human for one. Do not auto-post anywhere.

## 6. When done
    DELETE /api/feed/token
    Authorization: Bearer <token>