Quickstart: a page in three calls

Check a name, create the page, verify it. Copy-paste curl for each step, with the exact response shape.

1. Check that the name is free

curl "https://tapmy.link/api/username/check?u=anna-bakes"

{ "status": "free", "username": "anna-bakes" }
// or: { "status": "taken", "suggestions": ["anna-bakes-official", "anna-bakeshq"] }
// or: { "status": "invalid", "reason": "bad_chars" }

Optional but cheap. The create call performs the same check and answers 409 username_taken with the same suggestions.

2. Create the page

No account, no key needed. Omit email and the account is provisional — the person claims it later through the link in the response. Include email and password and it is a normal account from the start.

curl -X POST https://tapmy.link/api/agent/pages \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3a-anna-bakes-1" \
  -d '{
    "username": "anna-bakes",
    "locale": "en",
    "page": {
      "displayName": "Anna Bakes",
      "bio": "Sourdough, croissants and Saturday markets in Lisbon.",
      "templateId": "editorial",
      "blocks": [
        { "type": "link", "label": "Order this week\u2019s bread", "url": "https://annabakes.example/order", "featured": true },
        { "type": "socialRow", "items": [
          { "platform": "instagram", "url": "https://instagram.com/annabakes" },
          { "platform": "tiktok", "url": "https://tiktok.com/@annabakes" }
        ] },
        { "type": "messenger", "platform": "whatsapp", "handle": "+351912345678", "label": "Ask about an order" },
        { "type": "text", "variant": "heading", "content": "Where to find me" },
        { "type": "link", "label": "Saturday market, Campo de Ourique", "url": "https://maps.example/campo", "note": "9:00\u201314:00" }
      ]
    },
    "avatarUrl": "https://annabakes.example/anna.jpg"
  }'

{
  "ok": true,
  "account": { "id": "66dc…", "provisional": true, "email": null },
  "apiKey": "tapmy_sk_…",                 // shown once; store it
  "claimUrl": "https://tapmy.link/claim/…",  // give this to the owner
  "claimExpiresAt": "2026-10-08T21:00:00.000Z",
  "profile": { "id": "66dc…", "username": "anna-bakes", "isPublished": true, "blocks": [ … ] },
  "url": "https://anna-bakes.tapmy.link",
  "editUrl": "https://tapmy.link/dashboard/66dc…",
  "handoverMessage": "Your page is live at https://anna-bakes.tapmy.link. To make it yours … open this link within 30 days: …",
  "warnings": [],
  "next": [ "Check the result as text: GET https://anna-bakes.tapmy.link/?format=md", … ]
}

The page is live the moment this returns. warnings lists what did not work without stopping the page — an avatar URL that could not be fetched, an import that found nothing.

3. Read it back

curl https://anna-bakes.tapmy.link/page.md

A Markdown rendering of the public page: name, bio, template, every visible block with its destination. If it reads right, it renders right — both come from the same data.

Then: edit with the key

curl -X PATCH https://tapmy.link/api/profiles/66dc… \
  -H "Authorization: Bearer tapmy_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "bio": "Sourdough, croissants and Saturday markets. Lisbon." }'

PATCH changes only the fields you send. blocks, when sent, replaces the whole list — read the page first, edit the array, send it back.

Then: hand over

Paste handoverMessage to the person, or write your own. The claim link works for thirty days; a new one can be minted with POST /api/agent/claim-link using the key. See Handover.

If you are unsure about the body, POST /api/agent/pages/validate takes the same JSON and returns every problem at once without creating anything.