API Reference

LiveFolio REST API — use for CI/CD pipelines, custom integrations, and debugging. For AI agent workflows, use MCP instead.

When to Use the REST API

Use case	Recommended approach
AI agent publishing folios	MCP — higher-level, agent-native
CI/CD pipeline	REST API — simple HTTP calls, no handshake
Custom integration (non-AI)	REST API — direct JSON requests
Debugging MCP issues	REST API — curl examples for testing
Local file sync	CLI — `livefolio-init sync`

Base URL

https://livefolio.cloud

For OSS self-hosted instances, use your own domain or tunnel URL.

Authentication

All authenticated endpoints require an API key. Generate one from Settings → API Keys in the dashboard.

Authorization: Bearer lf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

See the Authentication page for details on API keys, OAuth, and rate limits.

Endpoint Index

Core Resources

Section	Endpoints	Auth
Files	`GET/POST /api/files`, `GET/PUT/DELETE /api/files/{id}`	Required
Uploading	`POST /api/files/{id}/upload`, `POST /api/files/{id}/upload-batch`	Required
Comments	`GET/POST/PUT/DELETE /api/files/{id}/comments`	Public (write)
Reactions	`GET/POST /api/files/{id}/reactions`	Public
Analytics	`POST /api/files/{id}/analytics`	None
Sharing	`GET/POST /api/files/{id}/public`, `GET/POST /api/tunnel`	Varies
AI Generation	`POST /api/files/{id}/ai`, `POST /api/files/{id}/ai-stream`, `POST /api/files/ai-create`	Required

Other Endpoints

Endpoint	Description	Auth
`GET /api/files/{id}/brief`	Curated design brief from feedback pins	Required
`POST /api/files/{id}/sync`	CLI watcher file sync	Bearer token
`GET /api/keys`	List API keys	Required
`POST /api/keys`	Generate new API key	Required (Owner/Admin)
`DELETE /api/keys/{id}`	Revoke API key	Required (Owner/Admin)
`GET /api/openapi`	OpenAPI 3.0 spec	Public
`GET /api/design-systems`	List available design systems	Required

Quick Examples

Create a Folio

curl -X POST https://livefolio.cloud/api/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx" \
  -d '{
    "title": "My Folio",
    "initialHtml": "<!DOCTYPE html><html>...</html>",
    "projectMode": "document"
  }'

Add a Comment

curl -X POST https://livefolio.cloud/api/files/my-folio/comments \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The header needs more contrast",
    "versionId": "v1",
    "filename": "index.html",
    "x": 50,
    "y": 5
  }'

Comments are public — no auth required.

Error Responses

All errors follow a consistent format:

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

Some errors include additional fields:

{
  "error": "STORAGE_EXCEEDED",
  "message": "You have exceeded your storage limit. Upgrade your plan to continue creating folios."
}

Status	Meaning
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid API key
`402`	Payment required — quota or storage exceeded
`403`	Forbidden — insufficient permissions or endpoint not available
`404`	Not found — invalid folio ID
`413`	Content too large — request body exceeds limit
`429`	Rate limit exceeded
`500`	Internal server error

Rate Limits

Authenticated endpoints include rate limit headers in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1718400000

Limits vary by plan. Check your workspace plan for specific quotas.

OpenAPI Spec

A machine-readable OpenAPI 3.0 spec is available at GET /api/openapi. Use it to generate client SDKs or import into tools like Postman.