REST API
Create, list, and update pages via HTTP endpoints.
The Blanc REST API lives at https://blanc.dev/api/v1/. Authentication is optional — the free tier works without an API key (50 pages/month).
For authenticated access, pass your API key as a Bearer token:
Authorization: Bearer <api_key>Create a page
POST /api/v1/specs
Content-Type: application/json
{
"spec": {
"root": "page",
"elements": {
"page": {
"type": "Stack",
"props": { "gap": "lg" },
"children": ["heading", "text"]
},
"heading": {
"type": "Heading",
"props": { "text": "Hello from Blanc" },
"children": []
},
"text": {
"type": "Text",
"props": { "text": "This page was created via the API." },
"children": []
}
}
},
"title": "My First Page"
}Response 201:
{
"id": "cf6e9f5a-418e-4b79-bd05-f3d3459c8036",
"url": "https://blanc.dev/d/Ab3x9_Kw",
"created_at": "2026-03-28T12:00:00Z"
}| Field | Type | Required | Description |
|---|---|---|---|
spec | object | Yes | A json-render spec describing the page |
title | string | No | Title shown in the browser tab and OG metadata |
Get a page
GET /api/v1/specs/:idResponse 200:
{
"id": "cf6e9f5a-418e-4b79-bd05-f3d3459c8036",
"spec": { ... },
"title": "My First Page",
"public": true,
"created_at": "2026-03-28T12:00:00Z"
}The :id parameter accepts both the UUID and the short ID from the page URL.
List pages
List pages you have created. Requires authentication (API key or free tier identity).
GET /api/v1/specs?limit=20&offset=0Response 200:
{
"pages": [
{
"id": "cf6e9f5a-418e-4b79-bd05-f3d3459c8036",
"url": "https://blanc.dev/d/Ab3x9_Kw",
"title": "My First Page",
"public": true,
"created_at": "2026-03-28T12:00:00Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Max pages to return (max 100) |
offset | number | 0 | Number of pages to skip |
Update a page
Update a page's spec, title, or visibility. You must be the owner.
PATCH /api/v1/specs/:id
Content-Type: application/json
{
"spec": { ... },
"title": "Updated Title",
"public": false
}Response 200:
{
"id": "cf6e9f5a-418e-4b79-bd05-f3d3459c8036",
"spec": { ... },
"title": "Updated Title",
"public": false,
"created_at": "2026-03-28T12:00:00Z"
}| Field | Type | Required | Description |
|---|---|---|---|
spec | object | No | Updated json-render spec |
title | string | No | Updated page title |
public | boolean | No | Set to true for public, false for private |
Provide at least one field.
Form submissions
Pages with submitForm actions collect form data. Retrieve submissions for a page:
GET /api/v1/specs/:id/submissionsResponse 200:
{
"submissions": [
{
"id": "sub_abc123",
"data": { "name": "Jane Smith", "email": "jane@example.com" },
"created_at": "2026-03-28T12:05:00Z"
}
]
}Error codes
| Status | Meaning |
|---|---|
400 | Invalid request body or missing fields |
401 | Invalid or missing API key |
403 | Not authorized (you don't own this page) |
404 | Page not found |
429 | Free tier limit reached (50 pages/month) |
500 | Server error |