The page file

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, in the editor (Import), or through the API. No connector or account is needed to preview it.

The easy way

Open /new and press Copy a prompt for your chat.
Paste the prompt into your chat and answer its questions (name, bio, links, vibe).
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

{
  "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. 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
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).
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.

Connect

Reference

The page file

The easy way

The one-link way

The brief

The full page file

For agents and scripts

​The easy way

​The one-link way

​The brief

​The full page file

​For agents and scripts

The easy way

The one-link way

The brief

The full page file

For agents and scripts