# Reading neverlogoff from an app or an agent

A read-only API for other apps and for people's own AI. It can read; it cannot post, save, follow or change anything. [Preview]

Full description: [/api/v1/openapi.json](/api/v1/openapi.json) (OpenAPI 3.1, JSON). Tool list for agents: [tools-lenses.json](/agents/tools-lenses.json), and the `discover_*` tools in `agents/tools.json`. Where to look for what: [Finding things](/agents/discover.md).

## What you can read

| Ask | Address |
|---|---|
| Search posts | `GET /api/v1/items?q=ramen manchester` |
| One post, with its signed record | `GET /api/v1/items/post:p_…` |
| Find lenses | `GET /api/v1/lenses?q=food` |
| One lens | `GET /api/v1/lenses/l_…` |
| What a lens shows | `GET /api/v1/lenses/l_…/items` |
| A person's public profile | `GET /api/v1/people/<public id>/public` |
| Topics and places | `GET /api/v1/vocab?q=nood` · `GET /api/v1/vocab?id=topic:noodles` |
| What is trending | `GET /api/v1/trending?tags=topic:esports` |
| Your own search, as JSON (a lens spec) | `GET /api/v1/search?spec=…` · built-in: `GET /api/v1/search?named=new` |
| The spec format | `GET /api/v1/specs` |
| Words to tags | `GET /api/v1/normalise?tags=Ramen,foodie` |

## Two ways in

- **No token:** you see what a signed-out stranger sees. Public things only.
- **A person's read token:** the person makes it at `/lens` (or `POST /api/lens?op=token` while signed in). It lasts 60 minutes and can be limited to `items`, `lenses` or `people`. With it, the API answers as that person: their followers-only and approved posts appear if they may see them, decided item by item by the same check the site uses. It never sees more than they can.

Send it as `Authorization: Bearer <token>`. A wrong or expired token gets 401. It is never quietly treated as "no token".

## Rules you must follow

- **18+.** neverlogoff is for people 18 and over. Every answer says `audience: "18+"`. Show that to your readers before you show anything. Explicit adult content is banned here.
- **Say where things came from.** Every item has `source.label` (neverlogoff, Bluesky, YouTube). Show it.
- **Link out, do not copy.** Items from Bluesky or YouTube come with text and a link. Do not copy or re-host their pictures or videos.
- **Show how it is sorted.** Lists come with `ranking.line` ("Sorted by: newest") and `ranking.how`. Show the line.
- **Respect deletion.** Do not keep copies for longer than you need. A post deleted at its source leaves our lists within about 11 minutes; your copy should too.
- **Slow down when asked.** 120 requests a minute without a token, 600 with one. On 429, wait `Retry-After` seconds.

## Sorting

Every recipe is small, public and does the same thing every time. None of them uses view counts, watch time, or anything private.

| Recipe | In plain words |
|---|---|
| `newest` | The most recent first. |
| `nearest` | Closest to a place you pick (`&place=<place id>`). Not your location. |
| `saved_by_people_i_follow` | Things more people you follow saved in public come first. Private saves never count. |
| `random_daily` | A fixed shuffle that changes once a day. |
| `verified_first` | Signed things from creators with a verified account first. |
| `vouched` | Creators more people you follow vouched for come first. |
| `trending` | Things more different people saved in public in the last 7 days first; one count per person. |

Add `&recipe=<name>` to any list to re-sort it for your reader.

## Feeds you fetch yourself

A lens can name RSS or Mastodon feeds. We never fetch those. `GET /api/v1/lenses/l_…/items` lists them under `client_side`; fetch them from your reader's device if you want them.

## Checking a signature

Items from our pile carry `signed.envelope`: an Ed25519 signature over a hash of the post's content. The keys are at `/.well-known/nlo-pass-keys.json` (entries with `nlo_use: "item"`). `/verify` shows how to check one by hand.