Site Builder

Base URL: /v1

All endpoints under /sitebuilder/* require authentication via Bearer token unless marked Public.

Projects

List Projects

GET /v1/sitebuilder/projects

Returns all projects owned by the authenticated user, ordered by updated_at descending.

Response 200

{
  "projects": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "name": "My Website",
      "description": "Portfolio site",
      "settings": {},
      "is_published": false,
      "published_slug": null,
      "updated_at": "2026-03-30T12:00:00Z",
      "created_at": "2026-03-28T08:00:00Z"
    }
  ]
}

Field	Type	Description
`id`	string	Unique project identifier (UUID)
`user_id`	string	Owner user ID
`name`	string	Project name
`description`	string	Project description
`settings`	object	Project-level settings
`is_published`	boolean	Whether the project is currently live
`published_slug`	string	URL slug of the published site, or null
`updated_at`	string	ISO 8601 timestamp of last update
`created_at`	string	ISO 8601 timestamp of creation

Create Project

POST /v1/sitebuilder/projects

Creates a new project. Automatically creates a “Home” page with slug index. If template_id is provided, all pages from the template project are copied into the new project.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Project name
`description`	string	No	Project description
`template_id`	string	No	UUID of an existing project to clone pages from

{
  "name": "My Portfolio",
  "description": "Personal portfolio site",
  "template_id": "d4f8a1b2-..."
}

Response 201

{
  "project": {
    "id": "a1b2c3d4-...",
    "user_id": "uuid",
    "name": "My Portfolio",
    "description": "Personal portfolio site",
    "settings": {},
    "is_published": false,
    "published_slug": null,
    "updated_at": "2026-03-30T12:00:00Z",
    "created_at": "2026-03-30T12:00:00Z"
  }
}

Get Project

GET /v1/sitebuilder/projects/{id}

Returns the project and all its pages. Returns 404 if the project does not exist or is not owned by the authenticated user.

Path Parameters

Parameter	Type	Description
`id`	string	Project UUID

Response 200

{
  "project": {
    "id": "a1b2c3d4-...",
    "user_id": "uuid",
    "name": "My Portfolio",
    "description": "Personal portfolio site",
    "settings": {},
    "is_published": true,
    "published_slug": "my-portfolio",
    "updated_at": "2026-03-30T12:00:00Z",
    "created_at": "2026-03-28T08:00:00Z",
    "pages": [
      {
        "id": "page-uuid",
        "name": "Home",
        "slug": "index",
        "html": "<h1>Hello</h1>",
        "css": "h1 { color: blue; }",
        "js": "",
        "metadata": {},
        "created_at": "2026-03-28T08:00:00Z"
      }
    ]
  }
}

Error Responses

Status	Description
`404`	Project not found or not owned by user

Update Project

PATCH /v1/sitebuilder/projects/{id}

Updates allowed fields on the project. Automatically sets updated_at to the current timestamp.

Path Parameters

Parameter	Type	Description
`id`	string	Project UUID

Request Body

Field	Type	Required	Description
`name`	string	No	New project name
`description`	string	No	New description
`settings`	object	No	Updated settings

{
  "name": "Updated Name",
  "settings": { "theme": "dark" }
}

Response 200

Returns the updated project object.

Delete Project

DELETE /v1/sitebuilder/projects/{id}

Permanently deletes the project. Cascading delete — all associated pages and form submissions are also removed.

Path Parameters

Parameter	Type	Description
`id`	string	Project UUID

Response 200

{
  "message": "Project deleted"
}

Clone Project

POST /v1/sitebuilder/projects/{id}/clone

Creates a new project by copying all pages, metadata, description, and settings from the source project.

Path Parameters

Parameter	Type	Description
`id`	string	Source project UUID

Request Body

Field	Type	Required	Description
`name`	string	Yes	Name for the cloned project

{
  "name": "Portfolio v2"
}

Response 201

Returns the newly created project object with all cloned pages.

Error Responses

Status	Description
`404`	Source project not found

Pages

Create Page

POST /v1/sitebuilder/projects/{id}/pages

Creates a new page within a project. If slug is not provided, it is auto-generated from the page name: lowercased, non-alphanumeric characters replaced with hyphens. Updates the parent project’s updated_at timestamp.

Path Parameters

Parameter	Type	Description
`id`	string	Project UUID

Request Body

Field	Type	Required	Default	Description
`name`	string	Yes	—	Page name
`slug`	string	No	auto	URL slug (auto-generated from name if omitted)
`html`	string	No	`""`	Page HTML content
`css`	string	No	`""`	Page CSS styles
`js`	string	No	`""`	Page JavaScript

{
  "name": "About Us",
  "html": "<h1>About</h1><p>We build things.</p>",
  "css": "h1 { font-size: 2rem; }"
}

Auto-generated slug for the above: about-us

Response 201

{
  "page": {
    "id": "page-uuid",
    "name": "About Us",
    "slug": "about-us",
    "html": "<h1>About</h1><p>We build things.</p>",
    "css": "h1 { font-size: 2rem; }",
    "js": "",
    "metadata": {},
    "created_at": "2026-03-30T12:00:00Z"
  }
}

Update Page

PATCH /v1/sitebuilder/pages/{id}

Updates fields on an existing page. Also updates the parent project’s updated_at timestamp.

Path Parameters

Parameter	Type	Description
`id`	string	Page UUID

Request Body

Field	Type	Required	Description
`name`	string	No	Page name
`slug`	string	No	URL slug
`html`	string	No	Page HTML content
`css`	string	No	Page CSS styles
`js`	string	No	Page JavaScript
`metadata`	object	No	Page metadata

{
  "html": "<h1>Updated About</h1>",
  "css": "h1 { color: red; }",
  "metadata": { "seo_title": "About Us" }
}

Response 200

Returns the updated page object.

Delete Page

DELETE /v1/sitebuilder/pages/{id}

Deletes a page. Updates the parent project’s updated_at timestamp.

Path Parameters

Parameter	Type	Description
`id`	string	Page UUID

Response 200

{
  "message": "Page deleted"
}

Publishing

Publish Site

POST /v1/sitebuilder/projects/{id}/publish

Publishes the project as a live site. If the project has already been published, the existing publication is updated (upsert on project_id). Sets is_published to true and assigns the published_slug.

Path Parameters

Parameter	Type	Description
`id`	string	Project UUID

Request Body

Field	Type	Required	Description
`slug`	string	No	Custom slug for the published URL (auto-generated from project name if omitted)

{
  "slug": "my-portfolio"
}

Response 200

{
  "published": {
    "id": "pub-uuid",
    "project_id": "a1b2c3d4-...",
    "user_id": "uuid",
    "slug": "my-portfolio",
    "published_at": "2026-03-30T12:00:00Z"
  },
  "site_url": "/v1/sites/my-portfolio"
}

View Published Site - Index

GET /v1/sites/{slug}

Serves the index page of the published site as a full HTML document.

Path Parameters

Parameter	Type	Description
`slug`	string	Published site slug

Response 200

Returns text/html — the rendered index page with embedded CSS and JS.

Error Responses

Status	Description
`404`	Published site not found

View Published Site - Page

GET /v1/sites/{slug}/{pageName}

Serves a specific page of the published site as a full HTML document.

Path Parameters

Parameter	Type	Description
`slug`	string	Published site slug
`pageName`	string	Page slug

Response 200

Returns text/html — the rendered page with embedded CSS and JS.

Error Responses

Status	Description
`404`	Site or page not found

AI Features

Generate Text

POST /v1/sitebuilder/ai/generate-text

Generates text content using GPT-4o-mini. Subject to a monthly limit of 100,000 tokens per user.

Request Body

Field	Type	Required	Default	Description
`prompt`	string	Yes	—	The text generation prompt
`max_tokens`	integer	No	`500`	Maximum tokens to generate

{
  "prompt": "Write a short hero section tagline for a freelance designer portfolio.",
  "max_tokens": 100
}

Response 200

{
  "text": "Crafting digital experiences that leave a lasting impression.",
  "tokens_used": 12
}

Error Responses

Status	Description
`429`	Monthly token limit exceeded (100,000 tokens/month)

Modify Text

POST /v1/sitebuilder/ai/modify-text

Modifies existing text using AI. Maximum 1,000 tokens per request. Subject to a monthly limit of 100,000 tokens per user.

Request Body

Field	Type	Required	Description
`text`	string	Yes	The text to modify
`operation`	string	Yes	One of the allowed operations (see below)
`target_language`	string	If `translate`	Target language (e.g. `"Spanish"`, `"French"`)
`tone`	string	If `change_tone`	Desired tone (e.g. `"professional"`, `"casual"`)

Allowed Operations

Operation	Description
`simplify`	Simplify the text for easier reading
`shorten`	Make the text more concise
`lengthen`	Expand the text with more detail
`fix_spelling`	Correct spelling and grammar errors
`change_tone`	Rewrite in a different tone (requires `tone`)
`translate`	Translate to another language (requires `target_language`)

{
  "text": "Our synergistic approach leverages cross-functional paradigms.",
  "operation": "simplify"
}

{
  "text": "Welcome to our website.",
  "operation": "translate",
  "target_language": "Spanish"
}

{
  "text": "Hey dude, check out our stuff.",
  "operation": "change_tone",
  "tone": "professional"
}

Response 200

{
  "text": "Bienvenido a nuestro sitio web.",
  "tokens_used": 8
}

Error Responses

Status	Description
`400`	Invalid operation or missing required field (`target_language` or `tone`)
`429`	Monthly token limit exceeded

Generate Image

POST /v1/sitebuilder/ai/generate-image

Generates an image using DALL-E-3. Subject to a monthly limit of 50 images per user.

Request Body

Field	Type	Required	Default	Description
`prompt`	string	Yes	—	Image generation prompt
`size`	string	No	`1024x1024`	Output image dimensions

Allowed Sizes

Value	Dimensions
`1024x1024`	Square (default)
`1024x1792`	Portrait
`1792x1024`	Landscape

{
  "prompt": "A minimalist hero image of a mountain landscape at sunset",
  "size": "1792x1024"
}

Response 200

{
  "image_url": "https://oaidalleapiprodscus.blob.core.windows.net/..."
}

Error Responses

Status	Description
`429`	Monthly image limit exceeded (50 images/month)

Export

Download as ZIP

POST /v1/sitebuilder/projects/{id}/export/download

Creates a ZIP archive containing all project pages as standalone HTML files. The ZIP is uploaded to Supabase storage and a signed download URL is returned. The URL expires after 1 hour.

Path Parameters

Parameter	Type	Description
`id`	string	Project UUID

Response 200

{
  "download_url": "https://your-supabase-url.supabase.co/storage/v1/object/sign/exports/..."
}

Error Responses

Status	Description
`404`	Project not found

Export via FTP

POST /v1/sitebuilder/projects/{id}/export/ftp

Exports all project pages as HTML files to a remote FTP server.

Path Parameters

Parameter	Type	Description
`id`	string	Project UUID

Request Body

Field	Type	Required	Default	Description
`host`	string	Yes	—	FTP server hostname
`port`	integer	No	`21`	FTP server port
`username`	string	Yes	—	FTP username
`password`	string	Yes	—	FTP password
`remote_path`	string	No	`"/"`	Remote directory to upload into

{
  "host": "ftp.example.com",
  "port": 21,
  "username": "deploy",
  "password": "s3cur3p@ss",
  "remote_path": "/public_html"
}

Response 200

{
  "message": "FTP export complete",
  "files_uploaded": 5
}

Error Responses

Status	Description
`400`	Missing required fields (host, username, or password)
`404`	Project not found

Forms

Submit Form

POST /v1/sitebuilder/forms

Handles form submissions from published sites. Any visitor can submit data to a project’s form.

Request Body

Field	Type	Required	Description
`project_id`	string	Yes	UUID of the project the form belongs to
`form_id`	string	Yes	Identifier for the specific form
`data`	object	Yes	Key-value pairs of form field submissions

{
  "project_id": "a1b2c3d4-...",
  "form_id": "contact-form",
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "message": "I'd like to discuss a project."
  }
}

Response 201

{
  "submission": {
    "id": "sub-uuid",
    "project_id": "a1b2c3d4-...",
    "form_id": "contact-form",
    "data": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "message": "I'd like to discuss a project."
    },
    "created_at": "2026-03-30T12:30:00Z"
  }
}