# Your posts

A post is one thing you share: a photo, a few photos, a video, some text or a link. You write it once, and people see it in whichever view they like. [Preview]

## Photos, video and text [Preview]

- **Text:** up to 5,000 characters. **Link:** any web address.
- **Photo:** one picture. **Carousel:** 2 to 10 pictures.
- **Video:** up to 60 seconds, made ready on your own device (our server never re-encodes it), or a YouTube or TikTok link.
- Hidden details, including the exact place a photo was taken, are removed before it is stored.
- A new post is **only you** until you choose otherwise.

<!-- diagram: post-views -->

## Tags: places and topics [Preview]

Tags are real places and topics from a fixed list, and each knows what it sits inside. So a ramen photo tagged **Manchester** is found by a search for **food England**: ramen is a kind of food, and Manchester is in England. Every result says why it matched. There is no "for you" feed: results are newest first.

Your AI, or our free helper, can **suggest** tags; a suggestion becomes a tag only when you say yes.

## Translation [Preview]

Your words are kept exactly as you wrote them. A reader's own AI or browser may translate them when they read, labelled "Translated · show original"; we never save a translation.

## Who sees each post [Preview]

| Setting | Who sees it |
|---|---|
| Only me | just you (the default) |
| Approved | people you approve, one by one |
| Followers | people who follow you (anyone can follow, without your yes) |
| Public | everyone |

When a public post stops being public, its public copies are deleted; a copy can stay in a network cache for a while.

## What can go wrong

- **The upload is refused:** photos and video files need a linked wallet, at [Your wallet](/me/wallet). Text, links and video links do not.
- **A tag is not found:** tags come from a fixed list. Try the place or topic it sits inside.
- **Followers-only is not private:** anyone can follow you. Use Approved for people you choose.
- **A post was seen before you changed it:** copies can stay in caches and screenshots. Think before making something public.

<!-- agent -->

## For agents

Start with [the quickstart](/agents/quickstart.md). You cannot create a post: `create` needs the person's sign-in cookie, which only their browser holds. You may look up tags (`vocab`, `resolve`), search, and fill in tag suggestions (they stay pending until the person accepts them). Ask **before** anything that is not `only_me`, before accepting suggestions (`decide`), approving a viewer or following someone.

Files go up with a **post pass**: `POST /api/posts?op=draft` → `POST /api/posts?op=pass-nonce` with `{post_id}` → the person signs in their wallet → `POST /api/posts?op=pass` with `{nonce, signature}`. It lasts **15 minutes**, for **one post**; then `PUT /api/posts?op=upload&path=<file>` with `Authorization: Bearer <pass>`.

## Endpoints

The operation goes in `?op=`.

| Method | Path | Auth | Does |
|---|---|---|---|
| GET | `/api/posts?op=search&q=food%20england` | optional | search; filters `format`, `place`, `topic`, `name`, `from`, `to`, `followed=1`, `lang`, `limit` |
| GET | `/api/posts?op=get&id=<post id>` | optional | one post (404 if missing **or** private) |
| GET | `/api/posts?op=vocab&q=manch` | none | tag autocomplete |
| GET | `/api/posts?op=resolve&q=ramen%20in%20manchester` | none | words → tag ids |
| POST | `/api/posts?op=create` | cookie | publish the post (ask first) |
| POST | `/api/posts?op=edit` | cookie | change text, tags or audience |
| GET | `/api/posts?op=byoa-request&id=<post id>` | cookie | the tag request for your AI |
| POST | `/api/posts?op=byoa-submit` | cookie | your answer → pending suggestions |
| POST | `/api/posts?op=decide` | cookie | accept or reject suggestions |
| POST | `/api/posts?op=report` | none | report a post |

Create a text post, only visible to the owner:

<!-- example: nlo-posts-v0#create -->
```json
{ "format": "text", "text": "Best tonkotsu ramen in Manchester so far", "tags": { "places": ["gn:2643123"], "topics": ["topic:ramen"] }, "visibility": "only_me" }
```

Change who can see it (ask first):

<!-- example: nlo-posts-v0#edit -->
```json
{ "id": "p_0123456789abcdef0123", "patch": { "visibility": "public" } }
```

Accept and reject suggestions (ask first):

<!-- example: nlo-posts-v0#decide -->
```json
{ "id": "p_0123456789abcdef0123", "accept": ["topic:ramen"], "reject": ["topic:soup"] }
```

Tag suggestions follow the contract `nlo.posts.tag-suggest.v0` (at most 20 kept; labels in words are looked up for you):

<!-- example: nlo-posts-v0#tagSuggestResponse -->
```json
{ "contract": "nlo.posts.tag-suggest.v0", "suggestions": [ { "id": "topic:ramen", "confidence": 0.9, "reason": "caption says tonkotsu ramen" }, { "label": "Manchester", "kind": "place", "confidence": 0.8, "reason": "caption names the city" } ] }
```

## Errors

| Code | Means |
|---|---|
| `not_found` | missing, or not yours to see (the same answer on purpose) |
| `bad_format` | format must be video, photo, carousel, text or link |
| `bad_visibility` | must be only_me, approved, followers or public |
| `text_too_long` | over 5,000 characters |
| `unknown_tag` | not a tag id from the list |
| `embed_not_allowed` | only YouTube and TikTok links can be embedded |
| `photo_needs_one_image` | a photo post needs exactly one picture |
| `carousel_needs_2_to_10_images` | a carousel needs 2 to 10 pictures |