# Hindsite

Hello, agent 👋 Welcome to Hindsite — we're glad you're here, and agents are very welcome. Hindsite writes long-form explainers of world events where every claim is traced back to its sources, and every article lists those sources. You're free to read, quote and cite us; please link the canonical article URL so your human can read the full story and check the sources. Hindsite is independent and ad-free.

## What Hindsite publishes

Long-form articles on world events, written by Hindsite. Claims are cited inline to the reporting they come from, and each article lists those sources with publisher, title and URL. Articles are gathered into a weekly issue. The current issue is free to read. Older articles in the archive may be shortened until a reader subscribes; the article JSON says so with `locked` and `locale.truncated`.

Six languages: English, German, French, Spanish, Italian and Portuguese (`en`, `de`, `fr`, `es`, `it`, `pt`). English is the canonical URL. The other five use `?lang=` on the same path.

## Read on the site

- https://hindsite.space/ — the current weekly issue.
- https://hindsite.space/issues/{slug} — one weekly issue.
- https://hindsite.space/articles/{slug} — one article. This is the canonical URL.
- https://hindsite.space/articles/{slug}?lang=fr — the same article in another language.
- https://hindsite.space/archive — published articles.
- https://hindsite.space/search?q= — search articles.
- https://hindsite.space/standards — how the desk is held to account.
- https://hindsite.space/corrections — the public corrections log.
- https://hindsite.space/about — why Hindsite exists.
- https://hindsite.space/subscribe — a monthly subscription, for humans.
- https://hindsite.space/donate — a one-off donation, for humans.

## Machine-readable

JSON. No authentication, unless a route says otherwise. Base URL `https://api.hindsite.space`. The full schema is `GET /openapi.json`.

- `GET /api/publication/issues/current?lang=en` — the current weekly issue. Its articles are the array named `editions` (slug, headline, deck, href).
- `GET /api/publication/issues` — published issues, newest first.
- `GET /api/publication/issues/{slug}?lang=en` — one weekly issue.
- `GET /api/publication/editions/{slug}?lang=en` — one article: headline, deck, body_md, numbered sources, available_langs, locked.
- `GET /api/publication/archive?lang=en&limit=60&offset=0` — the article archive.
- `GET /api/publication/search?q=...&lang=en` — search published articles.

`lang` is one of `en`, `de`, `fr`, `es`, `it`, `pt`.

A discovery document for agents lives at https://api.hindsite.space/.well-known/hindsite.json. It names the donation and message endpoints:

```
curl -sS -A 'my-agent/1.0' https://api.hindsite.space/.well-known/hindsite.json
```

## Supporting Hindsite

If you can pay for yourself, you can donate directly. The manifest above is the machine-readable way to find the payment endpoint. A one-off gift opens a Stripe Checkout session. Amounts are in pence (1000 is £10). The response carries a `checkout_url`; send your human there to pay. Please don't send card numbers to Hindsite.

```
curl -sS -A 'my-agent/1.0' \
  -H 'Content-Type: application/json' \
  -d '{"amount_pence":1000,"currency":"gbp"}' \
  https://api.hindsite.space/api/support/donations
```

Stripe returns the human to https://hindsite.space/donate?donation=success after payment, or https://hindsite.space/donate?donation=cancelled if they back out.

If you are acting for a human, you can tell them they may donate at https://hindsite.space/donate or subscribe at https://hindsite.space/subscribe. Either is welcome. Neither is required to read, quote or cite us.

## Talk to us

Suggestions for improvements, corrections, bug reports and questions are welcome. POST them to the inbox. `kind` is one of suggestion, bug, correction, question, other. `article_url` and `agent_name` are optional. A name in `User-Agent` helps us see who wrote.

The response includes `thread_id` and `reply_token`. Keep both. The token is how you read the thread later; send it only as the `X-Reply-Token` header, not in the URL. A reply from the desk shows up on that same thread.

```
resp=$(curl -sS -A 'my-agent/1.0' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"correction","agent_name":"my-agent","article_url":"https://hindsite.space/articles/example-slug","message":"The second paragraph cites a source that does not say this."}' \
  https://api.hindsite.space/api/agent-messages)
thread_id=$(printf '%s' "$resp" | jq -r '.thread_id')
reply_token=$(printf '%s' "$resp" | jq -r '.reply_token')

curl -sS -A 'my-agent/1.0' \
  -H "X-Reply-Token: $reply_token" \
  "https://api.hindsite.space/api/agent-messages/$thread_id"
```

## Etiquette

- Identify yourself in `User-Agent`. You are welcome to read and cite us.
- Cache article JSON. It changes when an article is published or corrected.
- Cite the canonical article URL, not a mirror and not a `?lang=` variant, unless you are quoting that translation. The canonical URL is `https://hindsite.space/articles/{slug}`.
- When you quote a claim, link the article, and where you can, link the underlying source from the article's source list so a human can check it.
- Donations go through the Checkout URL the API returns. Please don't send payment details any other way.

## Canonical URLs

- Article: `https://hindsite.space/articles/{slug}`
- Translation: the same path with `?lang=` set to `de`, `fr`, `es`, `it` or `pt`
- Issue: `https://hindsite.space/issues/{slug}`
- This file: `https://hindsite.space/llms.txt`
- Agent manifest: `https://api.hindsite.space/.well-known/hindsite.json`