# CanvasBuilder Agent API

Build, refine, publish, and download real websites on behalf of a CanvasBuilder
user. You connect once via a QR/device-link consent flow, get a scoped token,
then drive the same engine the CanvasBuilder app uses.

Base URL: https://canvasbuilder.co/api/v1/agents
OpenAPI:  https://canvasbuilder.co/agents-openapi.yml

## 1. Link to a user (one time)

POST /link/start
  body: { "agentName": "Your Agent", "scopes": ["sites:build","sites:publish"] }
  -> { code, linkUrl, qrUrl, scopes, expiresAt }

Show the user the QR code (qrUrl) or the linkUrl. They open it, sign in, and
approve the exact scopes you requested. Then:

POST /link/poll
  body: { "code": "WXYZ-1234" }
  -> { "status": "pending" }                 (keep polling)
  -> { "status": "approved", "accessToken": "cb_agent_...", "scopes": [...], "expiresAt": "..." }

The token is shown ONCE. Store it securely. Send it as:
  Authorization: Bearer cb_agent_...

Tokens expire after 90 days. The user can revoke anytime from their account.

## 2. Build a site

POST /sites
  body: { "description": "A landing page for a coffee subscription startup.",
          "title": "Acme Coffee" }
  -> 202 { "siteId": "...", "status": "building" }

Builds run asynchronously. Poll:

GET /sites/{siteId}
  -> { status: "building" | "complete" | "error", title, liveUrl?, previewHtml?, updatedAt }

When status is "complete", previewHtml holds the rendered HTML.

## 3. Refine

POST /sites/{siteId}/changes
  body: { "description": "Make the hero darker and add a pricing section." }
  -> 202 { "siteId", "status": "building" }   (poll GET /sites/{siteId})

## 4. Publish

POST /sites/{siteId}/publish     (requires scope sites:publish)
  body: { "subdomain": "acme-coffee" }
  -> { url: "https://acme-coffee.cnvs.site", subdomain, publishedSiteId, pages }

## 5. Custom domain (paid plans)

POST /sites/{siteId}/domain      (requires scope sites:domain; publish first)
  body: { "hostname": "shop.acme.com" }
  -> { domain, instructions, message }   (add the A record; SSL is automatic)

## 6. Download

GET /sites/{siteId}/download     -> application/zip (the full static site)
  ?minify=0 for unminified output.

## Scopes

- sites:build    build + refine + download + read status (default)
- sites:publish  publish to *.cnvs.site
- sites:domain   attach custom domains

Request only what you need at link time. Publish/domain are opt-in.

## Credits & limits

Builds consume the linked user's credits, scaled to the size and complexity of
what you build. If the balance is too low you get HTTP 402. Rate limits apply
per token (builds are limited per hour). All actions are audit-logged.

## Identity check

GET /me  ->  { userId, scopes, creditBalance, tokenName, expiresAt }