CMS Data API

Manage creator-owned content collections for pages with CMS enabled. Only the page owner writes; visitors read.

Only the page owner can create, update, and delete records. All visitors can read free content. Paid content can be gated behind membership plans. Collection names must be lowercase alphanumeric with underscores (e.g., posts, products).

CMS vs Social Data: CmsData is creator-managed (only the page owner writes), while SocialData is community-managed (any authenticated user writes). Use CMS for blogs, product catalogs, FAQs, and other content managed by a single creator.

Images for CMS content: Use POST /api/pages/:id/assets/generate to create AI-generated images and store the returned publicUrl in your CMS records (e.g., as a featuredImage field). See Page Assets > Generate Image and the CMS Blog Example for the full workflow.

Setup

Enable CMS on a page by setting page_api_cms_enabled to true:

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

Endpoints

GET /api/pages/:id/cms-data/:collection

List records in a collection. Free records (planId: null) are returned to everyone. Paid records are only returned to the page owner or users with an active subscription to the associated plan. No authentication required for free content.

Query Parameters

Example

curl "https://visimade.com/api/pages/123/cms-data/posts?limit=10&order=desc"

Response

{
  "records": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "collection": "posts",
      "data": { "title": "Hello World", "content": "<p>My first blog post</p>", "category": "news" },
      "planId": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 25, "limit": 10, "offset": 0, "hasMore": true
}

# Get the 20 most recent articles
curl "https://visimade.com/api/pages/123/cms-data/posts?limit=20"

# Load older articles (use the smallest ID from previous results)
curl "https://visimade.com/api/pages/123/cms-data/posts?limit=20&before=456"

# Poll for new articles since your last fetch
curl "https://visimade.com/api/pages/123/cms-data/posts?after=500&order=asc"

POST /api/pages/:id/cms-data/:collection

Create a new record. Only the page owner can create CMS records. Requires cms-data:write scope. Optionally attach a planId to gate the record behind a membership plan.

Example (free content)

curl -X POST \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"title": "New post", "content": "Hello world!"}}' \
  https://visimade.com/api/pages/123/cms-data/posts

Example (paid content)

curl -X POST \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"title": "Premium guide"}, "planId": 42}' \
  https://visimade.com/api/pages/123/cms-data/posts

PATCH /api/pages/:id/cms-data/:collection/:recordId

Update an existing record. Data is merged (not replaced). Only the page owner can update. Requires cms-data:write scope. You can also change the planId to gate or ungate content.

Example

curl -X PATCH \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"title": "Updated title"}}' \
  https://visimade.com/api/pages/123/cms-data/posts/550e8400-e29b-41d4-a716-446655440000

DELETE /api/pages/:id/cms-data/:collection/:recordId

Delete a record. Only the page owner can delete. Requires cms-data:write scope. Returns 204 on success, 404 if not found.

curl -X DELETE \
  -H "Authorization: Bearer vm_your_token_here" \
  https://visimade.com/api/pages/123/cms-data/posts/550e8400-e29b-41d4-a716-446655440000

Batch Operations

Execute up to 100 create, update, and delete operations in a single request. The entire batch runs in one database transaction (all-or-nothing) and counts as a single rate limit hit. Only the page owner can perform batch operations.

Request Body

{
  "operations": [
    { "op": "create", "data": { "title": "New post" }, "planId": null },
    { "op": "update", "id": "uuid-1", "data": { "title": "Updated" } },
    { "op": "delete", "id": "uuid-2" }
  ]
}

Response

{
  "results": [
    { "op": "create", "success": true, "id": "uuid-new", "data": { "title": "New post" }, "planId": null },
    { "op": "update", "success": true, "id": "uuid-1" },
    { "op": "delete", "success": true, "id": "uuid-2" }
  ]
}