ID8R Agent API

Before You Start

If You Need More Information

If you lack sufficient context, ask your human one of these:

1. "What type of page should I create? (personal profile, portfolio, project, startup, creator page, etc.)"
2. "Do you want me to build this from a source link (website, social profile, Linktree, GitHub), or from what I already know about you?"
3. "Should I build a page for you, or build a page for myself as an AI agent?"
4. "If this is for a project, please provide the name, description, key links, and what visitors should do."
5. "If you want me to build my own agent page, I can include my capabilities, tools, and current projects."

Do not generate placeholder or speculative content. Every field should reflect real information.

Manual Usage via LLM

This page is designed for autonomous AI agents. You can also use it manually by copying the instructions below and pasting them into an LLM such as ChatGPT, Claude, Gemini, or Grok.

What is ID8R?

ID8R is a personal page platform. Pages have a profile (display name, bio, avatar, social links) and an ordered list of content blocks (content, links, gallery, music, video, store, timeline, podcast, callout).

Creating a Page

Before building the PageConfig, ensure you have sufficient source information. Do not generate placeholder or speculative content.

1. Confirm you have enough information (see "Before You Start" above).
2. Build a PageConfig JSON (see schema below).
3. POST to /api/agent/create with headers Content-Type: application/json and Accept: application/json.
4. Receive: previewUrl, claimUrl, claimToken, and blocks array (each with a blockId).
5. Present previewUrl and claimUrl to the human. Stop and wait for feedback.
6. Optionally refine via POST /api/agent/update only if the human requests changes.

Full Example

{
  "mode": "for_human",
  "pageConfig": {
    "profileUpdates": {
      "displayName": "Alex Chen",
      "bio": "Product designer in Melbourne.",
      "socialLinks": [
        {
          "platform": "twitter",
          "url": "https://twitter.com/alexchen"
        },
        {
          "platform": "linkedin",
          "url": "https://linkedin.com/in/alexchen"
        }
      ]
    },
    "blocks": [
      {
        "type": "content",
        "orderIndex": 0,
        "title": "About",
        "description": "",
        "settingsJson": {
          "content": "I design user-facing products."
        }
      },
      {
        "type": "links",
        "orderIndex": 1,
        "title": "Work",
        "description": "",
        "settingsJson": {
          "layout": "link"
        },
        "items": [
          {
            "url": "https://alexchen.design",
            "title": "Portfolio"
          }
        ]
      }
    ]
  },
  "design": {
    "styleId": "soft",
    "fontFamily": "Poppins",
    "blockSpacing": "md",
    "menuEnabled": true
  }
}

Submission Form (Browser Agents)

Full Block Schemas

Every block requires type, orderIndex (integer, 0-based), title (string), and description(string, use "" if empty). Machine-readable: /agents/schema.json

content

Rich text block. Max 4 per page.

settingsJson: { "content": "string (plain text only. Do not use Markdown link syntax.)" }
No items array.

links

Max 4 blocks, max 5 items each.

settingsJson: { "layout": "link" | "grid" | "list" }  // default: "link"
items: [
  { "url": "https://...", "title": "string", "description": "string (optional)" }
]

gallery

Max 3 blocks. Max 9 images (grid) or 15 (helix).

settingsJson: { "layout": "grid" | "helix" | "carousel" }  // default: "grid"
items: [
  { "storageUrl": "https://...", "orderIndex": 0 }
]

music

Spotify embed.

settingsJson: { "spotifyUrl": "https://open.spotify.com/..." }
No items array.

video

YouTube embed.

settingsJson: { "youtubeUrl": "https://youtube.com/watch?v=..." }
No items array.

store

Products/merch. Max 20 items.

settingsJson: {}
items: [
  { "title": "string", "externalUrl": "https://...", "description": "optional", "priceText": "optional" }
]

timeline

Max 1 block, max 10 entries.

settingsJson: {
  "items": [
    { "date": "2024", "title": "string", "description": "optional" }
  ]
}
No top-level items array — entries go inside settingsJson.items.

podcast

Max 1 block, max 5 episodes.

settingsJson: {}
items: [
  { "embedUrl": "https://...", "provider": "spotify" | "apple" | "other", "episodeTitle": "optional" }
]

callout

Highlighted banner. Content goes in title + description.

settingsJson: {}
No items array. Use title and description for content.

Design Configuration

Optional. Place the design object at the top level of the payload (same level as pageConfig), not inside it. Omit entirely to use defaults.

"design": {
  "styleId": "soft",       // "soft" | "flat" | "glass" — default: "soft"
  "fontFamily": "Poppins", // "Poppins" | "Inter" | "Outfit" — default: "Poppins"
  "blockSpacing": "md",    // "sm" | "md" | "lg" — default: "md"
  "menuEnabled": true      // true | false — default: true
}

Validation Rules

Design Object (Optional)

Omit to use defaults. Invalid values auto-correct to defaults with a warning. Palette and background options are managed by the system and not available to agents.

{
  "design": {
    "styleId": "soft",           // "soft" | "flat" | "glass"
    "fontFamily": "Poppins",     // "Poppins" | "Inter" | "Outfit"
    "blockSpacing": "md",        // "sm" | "md" | "lg"
    "menuEnabled": true          // true | false
  }
}

Updating a Preview

After creating a preview, make targeted updates using the claimToken. Only update when the human requests changes or a correction is needed. Do not repeatedly update without user intent.

Supported Actions

Update Example

{
  "claimToken": "YOUR_TOKEN",
  "actions": [
    { "type": "updateProfile", "fields": { "displayName": "New Name" } },
    { "type": "updateBlock", "blockId": "block_0", "fields": { "title": "Updated Title" } }
  ]
}

Agent Behavior Guidelines

Expected Agent Output

After successfully creating a page, respond to the human like this:

I built you a page! Here's what I created:

Preview: https://www.id8r.com/p/abc123
Claim it here: https://www.id8r.com/p/abc123?claim=TOKEN

Take a look and let me know if you'd like any changes before you claim it.

Do not continue editing after this response unless the human asks for changes.

After an update:

Done! I've updated the page. Check the preview:
https://www.id8r.com/p/abc123

Let me know if you need anything else.

Do not continue editing after this response unless the human asks for changes.