API & MCP reference

Authentication

Create an API key in Settings → API & MCP. Keys look like ak_live_... and are shown once at creation. Pass them as a Bearer token on every request:

Authorization: Bearer ak_live_your_key_here

MCP server (recommended for AI assistants)

The hosted MCP server lives at https://www.aceframe.ai/api/mcp (Streamable HTTP). Connect it to Claude Code in one command:

claude mcp add --transport http aceframe \
  https://www.aceframe.ai/api/mcp \
  --header "Authorization: Bearer ak_live_your_key_here"

On claude.ai, add it as a custom connector with the same URL and header. Once connected, the assistant can call three tools:

• create_demo - title + ordered steps (screenshot, click position, annotation) → live share URL
• upload_screenshot - base64 image → hosted imageUrl for use in steps
• list_demos - your demos with share URLs and view counts

A typical agent flow: capture screenshots of a click-through (1440x900 works well), measure each click position as fractions of the viewport, upload each screenshot, then create the demo. The share URL is live immediately.

REST API

Two endpoints cover demo creation. Upload screenshots first (one per request), then create the demo referencing the returned URLs:

POST https://www.aceframe.ai/api/v1/uploads
Content-Type: application/json
Authorization: Bearer ak_live_...

{ "screenshot": "data:image/png;base64,iVBORw0..." }

→ { "imageUrl": "https://.../step-0.avif" }

POST https://www.aceframe.ai/api/v1/demos
Content-Type: application/json
Authorization: Bearer ak_live_...

{
  "title": "How to create a blog post",
  "steps": [
    {
      "imageUrl": "https://.../step-0.avif",
      "click": { "x": 0.42, "y": 0.05 },
      "annotation": "Click 'New post' to open the editor",
      "zoomLevel": 1.5,
      "pageUrl": "https://app.example.com/posts"
    }
  ]
}

→ { "id": "...", "shareUrl": "https://aceframe.ai/share/...", "editUrl": "..." }

GET /api/v1/demos lists your demos. Small demos can inline base64 screenshots directly in steps[].screenshot instead of pre-uploading.

Click coordinates

click.x and click.y are fractions (0-1) of the screenshot's width and height. Measure them - for example, element center via getBoundingClientRect() divided by viewport size at capture time. Estimated coordinates put the pointer on the wrong element.

Limits

Demos created through the API count toward your plan limits (Free: 15 demos; Pro and up: unlimited). Up to 50 steps per demo, screenshots up to roughly 4 MB per request, up to 10 active keys per account. Revoke keys anytime in Settings.