> ## Documentation Index
> Fetch the complete documentation index at: https://docs.posy.page/llms.txt
> Use this file to discover all available pages before exploring further.

# The page file

> One small JSON file describes a whole Posy page. Any chat can write it.

A Posy page can be one small JSON file. Any chat (ChatGPT, Claude, Gemini, a local model) can write it, and anyone can load it
at [`/new`](https://posy.page/new), in the editor (Import), or through the API. No connector or account is needed to preview it.

## The easy way

1. Open [`/new`](https://posy.page/new) and press **Copy a prompt for your chat**.
2. Paste the prompt into your chat and answer its questions (name, bio, links, vibe).
3. Paste the JSON it returns back into the box on `/new`. Check the preview, then **Make it mine**.

## The one-link way

An agent that can only write text can hand over a normal link. No JSON, no encoding:

```
/new?name=Mira%20Sol&bio=Illustrator&links=https://github.com/mira,hi@mira.so,mira/atlas
```

It opens a live preview, and one button makes the page yours. Fields: `name`, `bio`, `links` (comma-separated URLs, emails or `owner/repo`), `username`, `look`, `theme`, `layout`, `location`, `avatar`, `photos`, `font`, `backdrop`.

## The brief

```json theme={"theme":{"light":"rose-pine-dawn","dark":"rose-pine-moon"}}
{
  "posy": 1,
  "username": "mira",
  "name": "Mira Sol",
  "bio": "Illustrator making small, soft things",
  "location": "Lisbon",
  "look": "washi",
  "theme": "kinari",
  "photos": "mono",
  "links": [
    { "heading": "Find me" },
    "https://github.com/mira",
    "hi@mira.so",
    { "heading": "Work" },
    { "url": "https://mira.so/portfolio", "title": "Portfolio", "size": "w" },
    "mira/atlas",
    { "text": "Open for commissions" },
    { "stamp": "Say hello" },
    { "image": "/samples/tea.jpg", "focus": { "x": 40, "y": 30 }, "zoom": 1.5 }
  ]
}
```

| field | meaning |
| - | - |
| `name` | Required. Display name. |
| `links` | Required. In order. A string is a URL, an email, `owner/repo` or a short note: Posy picks the right tile (GitHub repo, YouTube, Spotify, social profile, link). |
| `username` | Optional. The address, `/<username>`. 3–30 letters, numbers, `-` or `_`. You can choose it when you load the file. |
| `bio`, `location`, `avatar` | Optional. `avatar` is an image URL. |
| `look` | Optional. The look of the page: `painted`, `cozy` (Desk), `washi`, `lofi`, `cobalt` or `night`. Default `painted`. On posy.page, Painted, Desk and Cobalt are free and the others are Pro. |
| `theme` | Optional. Colours. Each look has four palettes, listed in `/schema/brief.schema.json`. The first is the default (`washi`: `kinari`, `sakura`, `yomogi`, `sumi`). |
| `layout` | Optional. `bento` (Grid, the default: the look's own arrangement), `list` (one column, the phone arrangement on every screen) or `canvas` (free placement). Every look follows it. |
| `photos` | Optional. How photos are printed: `natural`, `mono`, `dither` or `ascii`. |
| `font` | Optional. A typeface id (the allowed values are in `/schema/brief.schema.json`). |
| `backdrop` | Optional. `solid`, `dots`, `grid`, or an image URL or `/path`. |

A link can also be an object: `{"heading": "…"}` starts a section, `{"text": "…"}` is a note, and `{"url": "…", "title": "…", "description": "…", "size": "w", "color": "…"}` overrides how one tile looks. Give each object exactly one of `url`, `email`, `repo`, `heading`, `text`, `stamp` or `image`.

* `{"stamp": "Say hello"}` is a short round badge (a note with `look: "stamp"`).
* `{"image": "https://…/me.jpg", "caption": "…", "url": "https://…"}` is a picture; `url` (optional) makes it clickable. A bare image address in `links` (`"/samples/tea.jpg"`, `"http://localhost:3000/a.png"`, anything ending in jpg, png, webp, gif, avif or svg) becomes a picture too.
* `focus` (`{"x": 0–100, "y": 0–100}`, the point to keep in view) and `zoom` (1–3) crop a picture. They work on `image` and on links, videos and music with a preview image. `size` is `s` (small), `w` (wide), `t` (tall) or `l` (large).

Posy is forgiving. It accepts the JSON wrapped in prose or a code fence, smart quotes and trailing commas. Unknown fields and small mistakes become
warnings, not errors. If something is really wrong, the message says what to ask your chat to fix.

## The full page file

The JSON that Posy exports (Settings → Export) works too: it is the complete page (profile, theme, every tile with its id, size and position).
Its format is [`/schema/page.schema.json`](https://posy.page/schema/page.schema.json). Use the brief when a chat writes the page, and the full file to move a page between Posy sites.

## For agents and scripts

* Schema: [`/schema/brief.schema.json`](https://posy.page/schema/brief.schema.json)
* REST: `POST /api/v1/page/import` with `{ "file": <brief or text>, "username": "mira", "replace": false }`. Creates the page, or with `replace: true` overwrites the draft.
* MCP: the `import_page` tool takes the same arguments.
* Theme only: `PATCH /api/v1/page/theme` (see [ai-agents](/agents/guide#rest-and-public-json)).
* A link that opens a ready-made preview: `/new#p=<base64url of the brief>`. Handing a user this link means they never need to copy anything.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.