Pages API

Create, read, update, and delete pages. Access and modify pages that you own or are a team member on.

Endpoints

POST

/api/pages

Create a new page with HTML content

GET

/api/pages/lookup?slug=:slug

Get page ID from slug

GET

/api/pages/:id

Get page details and content

PATCH

/api/pages/:id

Update page content or metadata

DELETE

/api/pages/:id

Delete a page

POST

/api/pages/:id/generate-preview-image

Generate an AI preview image for a page (owner only)

POST /api/pages

Create a new page with HTML content. This is the primary endpoint for AI agents to create pages programmatically. Requires pages:write scope.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Page title (used to generate slug)
`html_content`	string	Yes	Complete HTML document including DOCTYPE
`description`	string	No	Page description (max 500 characters)
`storage_mode`	string	No	Data storage mode: `page`, `solo_app`, `team_app`, or `social_app` (default: `page`). You must set this to enable data APIs — the default `page` mode does not inject any client-side SDK (TeamData, SoloData, etc.)
`page_api_ai_enabled`	boolean	No	Enable AI Chat API for visitors (default: false)
`page_api_image_gen_enabled`	boolean	No	Enable AI Image Generation for visitors (default: false)
`page_api_image_search_enabled`	boolean	No	Enable Image Search for visitors (default: false)
`page_api_image_recognition_enabled`	boolean	No	Enable AI Image Recognition for visitors (default: false)
`is_published`	boolean	No	Publish the page immediately (default: true)

Example Request

curl -X POST \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Sprint Board",
    "html_content": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"UTF-8\"><title>Sprint Board</title></head><body data-page-id=\"{{PAGE_ID}}\"><h1>Sprint Board</h1><div id=\"app\"></div><script>/* Your app code */</script></body></html>",
    "storage_mode": "team_app",
    "description": "Kanban board for sprint planning"
  }' \
  https://visimade.com/api/pages

Response

{
  "page": {
    "id": 123,
    "name": "Team Sprint Board",
    "slug": "team-sprint-board",
    "url": "https://visimade.com/p/team-sprint-board",
    "is_published": true,
    "storage_mode": "team_app",
    "page_api_ai_enabled": false,
    "page_api_image_gen_enabled": false,
    "page_api_image_search_enabled": false,
    "page_api_image_recognition_enabled": false
  }
}

Note: The {{PAGE_ID}} placeholder in your HTML will be automatically replaced with the actual page ID when the page is served. Use it in body attributes, JavaScript code, or anywhere you need the page ID.

Important for AI Agents: The html_content field must be properly JSON-encoded. HTML contains characters like </ that can break JSON parsing if not escaped correctly. Always use a proper JSON encoder (e.g., json.dumps() in Python, JSON.stringify() in JavaScript) rather than manually constructing the JSON string.

# Python example - correct way to send HTML content
import json
import urllib.request

html = """<!DOCTYPE html>
<html><head><title>My Page</title></head>
<body><h1>Hello World</h1></body></html>"""

data = json.dumps({
    "name": "My Page",
    "html_content": html
}).encode('utf-8')

req = urllib.request.Request(
    "https://visimade.com/api/pages",
    data=data,
    headers={
        "Authorization": "Bearer vm_your_token",
        "Content-Type": "application/json"
    }
)
response = urllib.request.urlopen(req)

GET /api/pages/lookup

Look up a page ID from its slug. This is useful when you only have the page URL (e.g., /p/my-page-slug) and need to find the page ID for other API calls. Requires pages:read scope.

Query Parameters

Parameter	Type	Description
`slug`	string	The page slug from the URL (required)

Request

curl -H "Authorization: Bearer vm_your_token_here" \
  "https://visimade.com/api/pages/lookup?slug=my-page-slug"

Response

{
  "id": 123,
  "name": "My Page",
  "slug": "my-page-slug",
  "isPublished": true,
  "updatedAt": "2024-01-15T10:30:00Z"
}

GET /api/pages/:id

Retrieve details and content for a specific page. Requires pages:read scope.

Request

curl -H "Authorization: Bearer vm_your_token_here" \
  https://visimade.com/api/pages/123

Response

{
  "page": {
    "id": 123,
    "name": "My Page",
    "slug": "my-page",
    "html_content": "<!DOCTYPE html>...",
    "is_published": true,
    "is_unlisted": false,
    "views": 1250,
    "updated_at": "2024-01-15T10:30:00Z",
    "description": "A description of my page",
    "page_api_ai_enabled": true,
    "page_api_image_gen_enabled": false,
    "page_api_image_search_enabled": false,
    "page_api_image_recognition_enabled": false,
    "page_api_spawn_enabled": false
  },
  "conversationId": 456,
  "messages": [...],
  "versionCount": 5,
  "storageMode": "solo_app"
}

PATCH /api/pages/:id

Update page content or metadata. Requires pages:write scope. Updating HTML content automatically creates a new version.

Request Body

Field	Type	Description
`html_content`	string	Full HTML content of the page
`name`	string	Page title/name
`description`	string	Page description (max 500 chars)
`page_api_ai_enabled`	boolean	Enable AI Chat API for visitors
`page_api_image_gen_enabled`	boolean	Enable AI Image Generation API for visitors
`page_api_image_search_enabled`	boolean	Enable Image Search API for visitors
`page_api_image_recognition_enabled`	boolean	Enable AI Image Recognition API for visitors
`page_api_spawn_enabled`	boolean	Enable Page Spawn API for visitors
`slug`	string	Change the page's URL slug. Auto-formatted to lowercase with hyphens. Must be 2+ characters, start/end with a letter or number, and be unique across all pages. Returns `409` if already taken.

Example: Update HTML Content

curl -X PATCH \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"html_content": "<!DOCTYPE html><html>...</html>"}' \
  https://visimade.com/api/pages/123

Response

{
  "success": true,
  "message": "Page updated successfully"
}

Example: Enable Page API Features

Enable AI Chat and Image Generation for a page so visitors can use these features:

curl -X PATCH \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"page_api_ai_enabled": true, "page_api_image_gen_enabled": true}' \
  https://visimade.com/api/pages/123

Page API features require the page HTML to include data-page-id="{{PAGE_ID}}" in the body tag and appropriate JavaScript to call the APIs. See the Page API Features section.

Example: Change Page Slug

Change a page's URL from /p/old-slug to /p/new-slug. The slug is auto-formatted (lowercased, special characters removed, spaces converted to hyphens).

curl -X PATCH \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-new-slug"}' \
  https://visimade.com/api/pages/123

Response:

{
  "success": true,
  "slug": "my-new-slug",
  "message": "Page slug updated to: my-new-slug"
}

Returns 409 Conflict if the slug is already taken by another page. Returns 400 Bad Request if the slug is too short or contains only special characters.

DELETE /api/pages/:id

Delete a page and all associated data. Requires pages:write scope. This action cannot be undone.

curl -X DELETE \
  -H "Authorization: Bearer vm_your_token_here" \
  https://visimade.com/api/pages/123

POST /api/pages/:id/generate-preview-image

Generate an AI preview image for a page. The image is generated based on the page's name and content, uploaded to cloud storage, and saved to the page record. Only the page owner can generate preview images. Accepts Bearer token or session authentication.

Request Body (optional)

Field	Type	Description
`html`	string?	HTML content to base the image on. If omitted, uses the page name only.
`customInstructions`	string?	Additional instructions for the image generation (e.g., "use blue tones", "minimalist style")

Example

# Generate preview image (minimal — uses page name automatically)
curl -X POST \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://visimade.com/api/pages/123/generate-preview-image

# With custom instructions
curl -X POST \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"customInstructions": "Use a clean, modern SaaS style with blue tones"}' \
  https://visimade.com/api/pages/123/generate-preview-image

Response

{
  "success": true,
  "imageUrl": "https://pub-abc123.r2.dev/preview-images/page-123-a1b2c3d4.png",
  "message": "Preview image generated successfully"
}

Tip: Call this endpoint after creating or updating a page to generate a fresh preview image. The image is stored permanently and used as the page's social/card preview.

On this page

Endpoints
POST /api/pages
GET /api/pages/lookup
GET /api/pages/:id
PATCH /api/pages/:id
DELETE /api/pages/:id
POST - Preview Image