Design REST API

{
  "error": "Human-readable error message"
}

// Request
POST /api/v1/design/sessions
Content-Type: application/json

{
  "label": "Landing page design"
}

// Response
{
  "sessionId": "abc-123-def",
  "designUrl": "https://efecto.app/design?session=abc-123-def",
  "expiresAt": "2026-03-01T12:00:00Z"
}

// Response
{
  "session": {
    "id": "abc-123-def",
    "browserConnected": true,
    "label": "Landing page design",
    "createdAt": 1709280000000,
    "lastActivity": 1709280060000,
    "expiresAt": 1709283600000
  },
  "pendingCalls": 0,
  "completedCalls": 12
}

// Request
POST /api/v1/design/sessions/abc-123-def/execute?wait=true
Content-Type: application/json

{
  "tool": "efecto_create_artboard",
  "input": {
    "name": "Desktop",
    "width": 1440,
    "height": 900,
    "className": "flex flex-col",
    "backgroundColor": "#ffffff"
  }
}

// Response (wait=true)
{
  "callId": "call-xyz",
  "status": "completed",
  "result": {
    "success": true,
    "message": "Artboard created",
    "data": { "artboardId": "artboard-1" }
  }
}

// Response (wait=false, default)
{
  "callId": "call-xyz",
  "status": "pending"
}

// Response (still processing)
{
  "callId": "call-xyz",
  "status": "pending",
  "result": null
}

// Response (completed)
{
  "callId": "call-xyz",
  "status": "success",
  "result": { "success": true, "message": "Artboard created", "data": {...} }
}

// Response (failed)
{
  "callId": "call-xyz",
  "status": "error",
  "result": { "error": "Node not found" }
}

// Response
{
  "total": 44,
  "tools": [
    {
      "name": "efecto_create_artboard",
      "description": "Creates a new artboard...",
      "input_schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "width": { "type": "number" },
          ...
        }
      }
    },
    ...
  ]
}

// Connect
GET /api/v1/design/sessions/abc-123-def/stream
Accept: text/event-stream

// Events (unnamed — use onmessage, not addEventListener)
data: {"type":"connected","sessionId":"abc-123-def"}

data: {"type":"tool_call","callId":"call-xyz","tool":"efecto_create_artboard","input":{...}}

data: {"type":"heartbeat","timestamp":1709280060000}

data: {"type":"session_closed","reason":"Session expired"}

// Option 1: Upload file (from browser)
const form = new FormData()
form.append("file", fileBlob)
const res = await fetch("/api/v1/design/upload-image", {
  method: "POST",
  credentials: "include",
  body: form,
})

// Option 2: Fetch from URL (from browser)
const res = await fetch("/api/v1/design/upload-image", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/photo.jpg" }),
})

// Response (201)
{ "url": "https://abc123.public.blob.vercel-storage.com/hero-xyz.png" }

// Request
GET /api/v1/design/icons/search?q=arrow&library=phosphor&limit=10

// Response
{
  "query": "arrow",
  "library": "phosphor",
  "count": 10,
  "results": ["arrow-right", "arrow-left", "arrow-up", ...],
  "libraries": [
    {
      "id": "phosphor",
      "name": "Phosphor",
      "iconCount": 7000,
      "variants": ["thin", "light", "regular", "bold", "fill", "duotone"]
    },
    {
      "id": "lucide",
      "name": "Lucide",
      "iconCount": 1500,
      "variants": ["regular"]
    },
    {
      "id": "heroicons",
      "name": "Heroicons",
      "iconCount": 600,
      "variants": ["outline", "solid", "mini"]
    },
    {
      "id": "radix",
      "name": "Radix",
      "iconCount": 300,
      "variants": ["regular"]
    }
  ]
}

// Request
GET /api/v1/design/icons/svg?library=phosphor&name=arrow-right&variant=bold&size=32

// Response (Content-Type: image/svg+xml)
<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="currentColor" viewBox="0 0 256 256">...</svg>

GET /api/v1/design/image-proxy?url=https%3A%2F%2Fexample.com%2Fphoto.jpg

// Returns raw image bytes with Content-Type header

// Request
POST /api/v1/design/publish
Content-Type: application/json

{
  "siteName": "my-landing-page",
  "files": [
    {
      "file": "index.html",
      "data": "<!DOCTYPE html><html>...</html>",
      "encoding": "utf-8"
    }
  ],
  "projectId": "prj_abc123"  // optional: update existing site
}

// Response
{
  "url": "my-landing-page.efecto.app",
  "vercelUrl": "efecto-my-landing-page.vercel.app",
  "projectId": "prj_abc123",
  "projectName": "efecto-my-landing-page",
  "deploymentId": "dpl_xyz789",
  "status": "QUEUED"
}

// Response
{
  "url": "efecto-my-landing-page-abc123.vercel.app",
  "status": "READY",        // QUEUED | BUILDING | READY | ERROR
  "createdAt": "2024-01-15T10:30:00Z"
}

// Email invite
POST /api/v1/design/shares
{
  "documentId": "doc-uuid",
  "email": "collaborator@example.com",
  "role": "editor"     // "viewer" or "editor"
}

// Generate share link
POST /api/v1/design/shares
{
  "documentId": "doc-uuid",
  "role": "viewer",
  "type": "link"
}

// Response (201)
{
  "share": {
    "id": "share-uuid",
    "document_id": "doc-uuid",
    "role": "viewer",
    "share_token": "abc-def-123",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

// Response
{
  "shares": [
    {
      "id": "share-uuid",
      "document_id": "doc-uuid",
      "shared_with": "user-uuid",
      "email": "collaborator@example.com",
      "role": "editor",
      "share_token": "abc-def-123",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

// Request
PATCH /api/v1/design/shares
{ "shareId": "share-uuid", "role": "viewer" }

// Response
{ "success": true }

// Response
{
  "role": "owner"    // "owner" | "editor" | "viewer" | null
}

// Request
POST /api/v1/design/ai/chat
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "Make the heading bigger and bolder" }
  ],
  "documentState": "<artboard data-id=\"ab-1\" ...>...</artboard>",
  "selectedIds": ["node-abc"],
  "selectedSubtrees": "<h1 data-id=\"node-abc\">Hello</h1>",
  "artboards": [
    { "id": "ab-1", "name": "Desktop", "width": 1440, "height": 900 }
  ],
  "activeArtboardId": "ab-1"
}

// Response: Server-Sent Events
data: {"type":"route","model":"sonnet","intent":"modify","reason":"Simple style change"}

data: {"type":"text_delta","text":"I'll make the heading"}

data: {"type":"tool_start","id":"call-1","name":"efecto_update_node"}

data: {"type":"tool_call","id":"call-1","name":"efecto_update_node","input":{"nodeId":"node-abc","className":"text-6xl font-black"}}

data: {"type":"tool_calls_pending","toolCalls":[{"id":"call-1","name":"efecto_update_node","input":{...}}]}

data: {"type":"usage","used":5,"limit":100,"remaining":95,"bonusCredits":0,"totalRemaining":95}

data: {"type":"done","reason":"complete"}

// Follow-up request with tool results
POST /api/v1/design/ai/chat
{
  "messages": [
    { "role": "user", "content": "Make the heading bigger and bolder" }
  ],
  "documentState": "<artboard ...>...updated state...</artboard>",
  "selectedIds": [],
  "artboards": [...],
  "pendingAssistantText": "I'll make the heading",
  "pendingToolCalls": [
    { "id": "call-1", "name": "efecto_update_node", "input": { "nodeId": "node-abc", "className": "text-6xl font-black" } }
  ],
  "pendingToolResults": [
    { "tool_use_id": "call-1", "result": "{\"success\":true,\"message\":\"Node updated\"}" }
  ]
}

// Response
{
  "used": 12,
  "limit": 100,
  "remaining": 88,
  "bonusCredits": 0,
  "totalRemaining": 88,
  "unlimited": false    // true for admin users
}

# 1. Create session
curl -X POST https://efecto.app/api/v1/design/sessions \
  -H "Content-Type: application/json" \
  -d '{"label":"My landing page"}'

# 2. Create artboard (after user opens the URL)
curl -X POST https://efecto.app/api/v1/design/sessions/SESSION_ID/execute?wait=true \
  -H "Content-Type: application/json" \
  -d '{"tool":"efecto_create_artboard","input":{"name":"Desktop","width":1440,"height":900,"className":"flex flex-col"}}'

# 3. Add hero section
curl -X POST https://efecto.app/api/v1/design/sessions/SESSION_ID/execute?wait=true \
  -H "Content-Type: application/json" \
  -d '{"tool":"efecto_add_section","input":{"parentId":"ARTBOARD_ID","jsx":"<section className=\"flex flex-col items-center justify-center py-24 px-8\"><h1 className=\"text-6xl font-bold\">Hello World</h1></section>"}}'

# 4. Close session
curl -X DELETE https://efecto.app/api/v1/design/sessions/SESSION_ID