The Posy 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

  1. Open /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

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