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

Authentication

All requests require an API key. Generate one from Settings → API Keys.

Authorization: Bearer lf_agent_xxxxxxxxxxxx

Endpoints

Files

Method	Path	Description
`GET`	`/api/files`	List all folios
`GET`	`/api/files/{id}`	Get full folio details
`POST`	`/api/files`	Create a new folio
`PUT`	`/api/files/{id}`	Update folio metadata
`DELETE`	`/api/files/{id}`	Delete a folio

Comments

Method	Path	Description
`GET`	`/api/files/{id}/comments`	List comments (public)
`POST`	`/api/files/{id}/comments`	Add a comment (public)
`PATCH`	`/api/files/{id}/comments/{cid}`	Resolve a comment
`DELETE`	`/api/files/{id}/comments/{cid}`	Delete a comment

Reactions

Method	Path	Description
`GET`	`/api/files/{id}/reactions`	Get reaction counts (public)
`POST`	`/api/files/{id}/reactions`	Add a reaction (public)

AI Generation

Method	Path	Description
`POST`	`/api/files/{id}/ai`	Generate/modify folio content
`POST`	`/api/files/{id}/ai-stream`	Streaming AI generation

Other

Method	Path	Description
`GET`	`/api/files/{id}/public`	Public folio view
`GET`	`/api/files/{id}/brief`	Curated design brief
`GET`	`/api/files/{id}/analytics`	View analytics
`POST`	`/api/files/{id}/sync`	CLI file sync
`GET`	`/api/keys`	List API keys
`POST`	`/api/keys`	Generate API key
`DELETE`	`/api/keys/{id}`	Revoke API key

Create a Folio

curl -X POST https://livefolio.cloud/api/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_agent_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",
    "x": 50,
    "y": 5
  }'

Comments are public — no auth required.

Error Responses

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

Status	Meaning
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — insufficient permissions
`404`	Not found — invalid folio ID
`429`	Rate limit exceeded
`500`	Internal server error

Rate Limits

Responses include rate limit headers:

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

Check your plan for specific limits.