AI Generation

Overview

LiveFolio provides three AI endpoints for different generation workflows:

Endpoint	Use case
POST /api/files/ai-create	Create a brand-new folio from a natural language prompt
POST /api/files/{id}/ai	Co-author an existing folio with AI (conversation + tool use)
POST /api/files/{id}/ai-stream	Streaming AI co-authoring with real-time text output

All AI endpoints require authentication. In Cloud mode, they count against your workspace's monthly message quota and are subject to storage limits.

AI Create (New Folio)

POST /api/files/ai-create
Authorization: Bearer lf_live_xxxxxxxxxxxx
Content-Type: application/json

Creates a complete folio from a natural language description. The AI classifies the project mode, generates a title, and produces a production-ready index.html.

Availability: Cloud mode only. OSS users should use the MCP server for AI folio creation.

Request Body:

Field	Type	Required	Description
prompt	string	Yes	Natural language description of the desired folio
model	string	No	Override the managed AI model (OSS only)
apiKey	string	No	Bring your own API key (OSS only)
designPreferences	object	No	Theme, typography, palette, libraries
title	string	No	Override the AI-generated title
isPrivate	boolean	No	Require access key
accessKey	string	No	Password for private folios
allowComments	boolean	No	Enable comments (default: true)
presentationModeOnly	boolean	No	Fullscreen mode only
referenceFiles	array	No	Reference documents for AI context
status	string	No	draft or published

Example Request:

curl -X POST https://livefolio.cloud/api/files/ai-create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx" \
  -d '{
    "prompt": "Create a startup pitch deck for an AI-powered gardening app called GrowSync. Include problem slide, solution, market size, traction, and team.",
    "designPreferences": {
      "theme": "Premium SaaS Deck",
      "palette": "Sage Forest"
    }
  }'

Response (201):

{
  "project": {
    "id": "a1b2c3d",
    "title": "GrowSync Pitch Deck",
    "description": "Startup pitch deck for AI-powered gardening app",
    "projectMode": "deck",
    "createdAt": "2025-06-20T14:22:00.000Z"
  }
}

The folio is created with index.html containing the generated content and an AI-generated title/description.

Error Responses:

Status	Error	Description
400	A non-empty prompt is required.	Missing or empty prompt
400	No AI model configured.	No provider available
401	Unauthorized	No valid auth context
402	STORAGE_EXCEEDED	Over storage quota
403	Endpoint not available in OSS	OSS mode restriction
500	AI failed to generate HTML content.	Generation produced no output
500	AI is not configured for this workspace.	No API keys configured

AI Co-Author (Existing Folio)

POST /api/files/{id}/ai
Authorization: Bearer lf_live_xxxxxxxxxxxx
Content-Type: application/json

The primary AI interaction endpoint. Supports multiple actions:

• Conversational generation — chat with AI about your folio
• Commit proposals — apply AI-suggested file changes as new versions
• Tool execution — web search, web fetch, element editing, page management
• Clear chat — reset conversation history

Action: Conversational Generation (default)

Send a user prompt and receive AI analysis, suggestions, or code changes.

Fields:

Field	Type	Required	Description
userPrompt	string	Yes	The user's message or instruction
chatHistory	array	No	Previous messages for context
pageContext	string	No	"Whole Project" or "Current Screen" (default: Whole Project)
activeFilename	string	No	Active file when pageContext is "Current Screen"
targetVersionId	string	No	Version to base changes on (default: latest)
designSystem	object	No	Override design preferences for this request
selectedModel	string	No	AI model to use
apiKey	string	No	Bring your own API key
ollamaHost	string	No	Ollama host URL (for local models)
targetedElement	object	No	Element to surgically edit ({selector, tagName, outerHTML})
attachedFiles	array	No	Reference files for this prompt
executeImmediately	boolean	No	Auto-commit changes as a new version
simulatedAuthor	string	No	Author name for auto-committed versions

Example — Chat with AI:

curl -X POST https://livefolio.cloud/api/files/a1b2c3d/ai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx" \
  -d '{
    "userPrompt": "Make the hero section more impactful with a gradient background"
  }'

Response (planning mode — no auto-commit):

{
  "success": true,
  "explanation": "I will update the hero section with a gradient background that transitions from deep indigo to teal...",
  "isProposal": true,
  "proposedFiles": {
    "index.html": "<!DOCTYPE html>...updated..."
  }
}

Response (with tool calls — Cloud mode):

When the AI uses tools (web search, web fetch, etc.), the response includes tool call metadata:

{
  "success": true,
  "explanation": "I found the latest stats and updated the market size slide...",
  "toolCalls": [
    {
      "id": "call_abc123",
      "name": "web_search",
      "arguments": { "query": "AI gardening market size 2025" },
      "status": "done"
    }
  ]
}

Action: Commit Proposal

Apply AI-proposed file changes as a new version.

curl -X POST https://livefolio.cloud/api/files/a1b2c3d/ai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx" \
  -d '{
    "action": "commit-proposal",
    "proposedFiles": {
      "index.html": "<!DOCTYPE html>...updated..."
    },
    "proposedExplanation": "Updated hero section with gradient",
    "simulatedAuthor": "AI Co-pilot"
  }'

Response:

{
  "success": true,
  "newVersionId": "v5",
  "project": { ... }
}

Action: Clear Chat

Reset the conversation history for a folio.

curl -X POST https://livefolio.cloud/api/files/a1b2c3d/ai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx" \
  -d '{"action": "clear-chat"}'

Response:

{
  "success": true,
  "project": { ... }
}

Action: Tool Response

Feed tool execution results back to the AI for follow-up. Used by the client when tool calls require client-side execution.

Error Responses

Status	Error	Description
400	Various validation errors	Missing required fields or invalid input
401	Unauthorized	No valid auth context
402	QUOTA_EXCEEDED	Monthly AI prompt limit reached
402	STORAGE_EXCEEDED	Over storage quota
404	Project not found	Folio does not exist

AI Stream (Real-Time)

POST /api/files/{id}/ai-stream
Authorization: Bearer lf_live_xxxxxxxxxxxx
Content-Type: application/json

Streaming variant of the AI co-author endpoint. Returns Server-Sent Events (SSE) with real-time text chunks as the AI generates.

Request Body: Same as the conversational generation action of /api/files/{id}/ai.

Response: SSE stream (text/event-stream).

SSE Event Types:

Type	Description
status	Progress update (e.g., "Synthesizing design strategy...")
chunk	Text tokens streaming in real-time
done	Generation complete with full result
error	Error during generation

Example — Consume the stream:

const response = await fetch('https://livefolio.cloud/api/files/a1b2c3d/ai-stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer lf_live_xxxxxxxxxxxx'
  },
  body: JSON.stringify({
    userPrompt: 'Add a pricing table with three tiers',
    executeImmediately: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  const lines = text.split('\n');
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      switch (event.type) {
        case 'chunk':
          process.stdout.write(event.text); // Stream text to console
          break;
        case 'done':
          console.log('\nComplete!', event.explanation);
          break;
        case 'error':
          console.error('Error:', event.message);
          break;
      }
    }
  }
}

Note: The streaming endpoint is Gemini-only and uses a two-stage pipeline (planning + generation) for higher quality output.