Create a page in a space

Embed

<a href="https://forumulate.com/reference/forumulate-api-collection-createpage"><img src="https://forumulate.com/reference/_api/public/orgs/046a9bc0-d530-43ae-9bae-af7945008cda/spaces/8042f004-e3d9-445f-b7a4-b6c1f86836e6/pages/66b70169-d48a-43bf-9e63-0be731ad52e7/social-card.svg?v=3e7ae33eec8b" alt="Create a page in a space" width="600" height="315"></a>

POSThttps://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages

Creates a page directly inside one collection, which is the usual authoring door: it saves you creating a page and then moving it, and the slug is derived from the title unless you name one.

Requires token scope: write (the coarse method gate) for Atlas key (ak_), Personal Access Token (cft_) or OAuth (cfo_) auth — in addition to any catalog scope (GET /pats/scopes) the route’s capability needs. Session/cookie auth is governed by RBAC capabilities instead.

A taken slug is reported, not hidden. With onSlugTaken: "suffix" a page whose slug already exists is created at slug-2, and the response says so: slugChanged: { asked, used } plus a sentence in warnings[] and on the X-Field-Warnings header. onSlugTaken: "fail" gives a 409 page.slug_taken instead. Unset, it is versioned: suffix for a caller stating a Forumulate-Version before 2026-12-01 (or none), fail from 2026-12-01 — the safe default, and the blog's. PATCH …/pages/{pageId} takes the same option with the SAME default, so one rule covers both doors. See Slugs.

Send ONE body field. content (block JSON) is exclusive with body and sections (Markdown); sending content alongside either is a 422 naming both. It used to accept them together and silently discard the block document. body and sections together remain legal — that is the designed authoring path (slots first, then trailing prose).

A parentId must exist here. A page id that is not a live page in this space is a 404, and one in another collection is a 422. A nil uuid used to be stored, producing a row that never appeared in the tree.

A sections key must be a slot this space type declares. An unknown key is a 422 listing the slots that exist; it used to create one that nothing renders.

Parameters

orgIdstringpathrequired

spaceIdstringpathrequired

collectionIdstringpathrequired

forumulate-versionstringheader

API version negotiation. Send forumulate-version: 2026-12-01 on every request from a new integration; it is optional only so that integrations written before versioning keep working. Each version includes everything before it:

Idempotency-Keystringheader

Makes this write safe to retry. Optional — send any unique string (a UUID is ideal) and the first request runs while its response is remembered under that key for 24 hours; an identical retry replays that same status and body instead of acting twice, so a timeout or a 5xx from the edge can be retried without creating a second row. A retry sent while the first request is still in flight is refused with 409. The key is scoped to the method and path, so the same key on a different endpoint is a different request. Error responses of 5xx are never cached — those retries re-run. A key is bound to the BODY it was first used with: reusing it with a different body is a 409 idempotency.key_reused, not a replay, because replaying would tell you a write landed that never ran. Generate one key per request, never per process or per session.

Request body application/json

Example

{
  "title": "Getting started",
  "slug": "getting-started",
  "body": "# Getting started\n\nInstall the SDK, then create your first page."
}

{
  "title": "Getting started",
  "slug": "getting-started",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": {
          "level": 1
        },
        "content": [
          {
            "type": "text",
            "text": "Getting started"
          }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Install the SDK, then create your first page."
          }
        ]
      },
      {
        "type": "codeBlock",
        "attrs": {
          "language": "bash"
        },
        "content": [
          {
            "type": "text",
            "text": "npm i @forumulate/sdk"
          }
        ]
      }
    ]
  }
}

Schema

presetstring

titlestringrequired

slugstringrequired

parentIdstring

contentobject

The page body as a block document: { "type": "doc", "content": [ …block nodes… ] } (TipTap/ProseMirror JSON — the same shape GET /pages/{id}/markdown round-trips from). Use ONE of content (block JSON), body (Markdown), or sections (Markdown per slot).

Show child parameters

typestringrequired

contentBlockNode[]required

The top-level block nodes.

Show child parameters

typestringrequired

The node kind, e.g. paragraph, heading, codeBlock, text. The full list is at GET /docs/block-schema.

attrsobject

Node-specific attributes, e.g. { "level": 2 } for a heading.

contentBlockNode[]

Child nodes, for container blocks.

textstring

The literal text, for a text node.

marksobject[]

Inline marks (bold, italic, link, …) on a text node.

sectionsobject

Markdown per named slot for a multi-slot page type, e.g. { "summary": "…md…", "steps": "…md…" }. An undeclared slot name is a 422 naming the slots that exist.

bodystring

The whole page as a single Markdown string — the simplest way to author. Converted to blocks on write. Blocks beyond plain Markdown (callouts, tabs, cards, steppers, columns, buttons, …) are written as :::name{attrs} directives — every directive, its attributes and how it closes: GET /docs/markdown-dialect. Up to 2,000,000 characters of Markdown — the same ceiling the importer, the create and the update doors all use, so an imported page can always be written back.

paramsobject

versionKeystring

localestring

onSlugTakenstring

What to do when the space already has a page at that slug: suffix lands at the next free name — getting-started-2 — and REPORTS it in warnings and slugChanged; fail answers 409 and writes nothing, which is what a pipeline that must stay idempotent wants. Unset, the default depends on the Forumulate-Version you state: suffix before 2026-12-01 (and with no header), fail from 2026-12-01 — the same 409 a blog post gives.

suffix | fail

Code samples

cURL

curl -X POST "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages" \
  -H "forumulate-version: <value>" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/json" \
  -d '{"preset":"string","title":"string","slug":"string","parentId":"string","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Getting started"}]},{"type":"paragraph","content":[{"type":"text","text":"Install the SDK, then create your first page."}]},{"type":"codeBlock","attrs":{"language":"bash"},"content":[{"type":"text","text":"npm i @forumulate/sdk"}]}]},"sections":{},"body":"string","params":{},"versionKey":"string","locale":"string","onSlugTaken":"suffix"}'

TypeScript

const res = await fetch('https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages', {
  method: 'POST',
  headers: {
    'forumulate-version': '<value>',
    'Idempotency-Key': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"preset":"string","title":"string","slug":"string","parentId":"string","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Getting started"}]},{"type":"paragraph","content":[{"type":"text","text":"Install the SDK, then create your first page."}]},{"type":"codeBlock","attrs":{"language":"bash"},"content":[{"type":"text","text":"npm i @forumulate/sdk"}]}]},"sections":{},"body":"string","params":{},"versionKey":"string","locale":"string","onSlugTaken":"suffix"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages",
    headers={
    "forumulate-version": "<value>",
    "Idempotency-Key": "<value>",
    "Content-Type": "application/json",
    },
    json={"preset": "string", "title": "string", "slug": "string", "parentId": "string", "content": {"type": "doc", "content": [{"type": "heading", "attrs": {"level": 1}, "content": [{"type": "text", "text": "Getting started"}]}, {"type": "paragraph", "content": [{"type": "text", "text": "Install the SDK, then create your first page."}]}, {"type": "codeBlock", "attrs": {"language": "bash"}, "content": [{"type": "text", "text": "npm i @forumulate/sdk"}]}]}, "sections": {}, "body": "string", "params": {}, "versionKey": "string", "locale": "string", "onSlugTaken": "suffix"},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages", strings.NewReader(`{"preset":"string","title":"string","slug":"string","parentId":"string","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Getting started"}]},{"type":"paragraph","content":[{"type":"text","text":"Install the SDK, then create your first page."}]},{"type":"codeBlock","attrs":{"language":"bash"},"content":[{"type":"text","text":"npm i @forumulate/sdk"}]}]},"sections":{},"body":"string","params":{},"versionKey":"string","locale":"string","onSlugTaken":"suffix"}`))
	req.Header.Set("forumulate-version", "<value>")
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['forumulate-version: <value>', 'Idempotency-Key: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"preset":"string","title":"string","slug":"string","parentId":"string","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Getting started"}]},{"type":"paragraph","content":[{"type":"text","text":"Install the SDK, then create your first page."}]},{"type":"codeBlock","attrs":{"language":"bash"},"content":[{"type":"text","text":"npm i @forumulate/sdk"}]}]},"sections":{},"body":"string","params":{},"versionKey":"string","locale":"string","onSlugTaken":"suffix"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages')
req = Net::HTTP::Post.new(uri)
req['forumulate-version'] = '<value>'
req['Idempotency-Key'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"preset":"string","title":"string","slug":"string","parentId":"string","content":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"Getting started"}]},{"type":"paragraph","content":[{"type":"text","text":"Install the SDK, then create your first page."}]},{"type":"codeBlock","attrs":{"language":"bash"},"content":[{"type":"text","text":"npm i @forumulate/sdk"}]}]},"sections":{},"body":"string","params":{},"versionKey":"string","locale":"string","onSlugTaken":"suffix"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/collections/{collectionId}/pages"))
    .header("forumulate-version", "<value>")
    .header("Idempotency-Key", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"preset\":\"string\",\"title\":\"string\",\"slug\":\"string\",\"parentId\":\"string\",\"content\":{\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"level\":1},\"content\":[{\"type\":\"text\",\"text\":\"Getting started\"}]},{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Install the SDK, then create your first page.\"}]},{\"type\":\"codeBlock\",\"attrs\":{\"language\":\"bash\"},\"content\":[{\"type\":\"text\",\"text\":\"npm i @forumulate/sdk\"}]}]},\"sections\":{},\"body\":\"string\",\"params\":{},\"versionKey\":\"string\",\"locale\":\"string\",\"onSlugTaken\":\"suffix\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

201 Created — the new page id, slug and title.

Example

{
  "page": {
    "id": "string",
    "slug": "string",
    "title": "string"
  },
  "slugChanged": {
    "asked": "string",
    "used": "string"
  },
  "warnings": [
    "string"
  ],
  "data": {
    "id": "string",
    "slug": "string",
    "title": "string"
  }
}

Schema

pageobjectrequired

Show child parameters

idstringrequired

slugstringrequired

titlestringrequired

slugChangedobject

Show child parameters

askedstringrequired

usedstringrequired

warningsstring[]

dataobject

The created resource again, under a key that is the same on every create — so a generic client needs one parser rather than one per endpoint. It is the SAME object as the key named after the resource (page, article, topic, …), which remains the canonical name.

Show child parameters

idstringrequired

slugstringrequired

titlestringrequired

400 The request could not be understood — a malformed header, path or query value (request.malformed). A value that was understood but is not acceptable is a 422 validation.failed.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

Where the vocabulary or format this error is about is published — an absolute URL, or an API route such as GET /space-types/{type}/presets. Present on errors over a controlled list, so the answer to "what am I allowed to send?" is in the error itself.

reasonstring

Why a credential was refused, as one stable word, where one status has several causes — e.g. an external_jwt redeem answers iat_too_old, iat_in_future, bad_signature, bad_issuer, bad_audience, expired and more. Branch on this, not on message.

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

The field operations since your If-Match that touch a path your own operations touch. Empty: none did — retry the batch unchanged under etag. null: the history no longer reaches your tag — re-read the entry first.

requestIdstring

The id of this request — the same value as the x-request-id and x-forumulate-request-id response headers. Quote it in a bug report: it is the only thing that finds your exact request in our logs. It is in the body because that is the part that survives — an SDK that throws the parsed body, a serverless log that keeps the body and drops the headers, a ticket with the JSON pasted in.

401 No credential, or one that is expired or revoked (auth.required). Send a Bearer token or the session cookie.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

reasonstring

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

requestIdstring

403 Authenticated, and not allowed — always rbac.forbidden, whether what is missing is the capability, the token scope, or a resource the token is pinned away from. The message names the capability and, for a scope refusal, the scopes that would grant it. A refusal because of the PLAN is a 402 with quota.exceeded, not this.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

reasonstring

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

requestIdstring

404 parentId is not a live page in this space (or collectionId does not exist here).

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

reasonstring

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

requestIdstring

409 The slug is taken and onSlugTaken: "fail" was sent.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

reasonstring

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

requestIdstring

422 The body was understood and a value is unacceptable (validation.failed). error.details names the field paths.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

reasonstring

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

requestIdstring

429 Rate limited — see the RateLimit-* headers.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

reasonstring

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

requestIdstring

default Error — the stable { error: { code, message } } envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        null
      ]
    }
  },
  "requestId": "string"
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

Stable, machine-readable error code, e.g. rbac.forbidden.

messagestringrequired

Human-readable explanation.

detailsobject

Field-level validation problems, keyed by field path (422 only).

docsstring

reasonstring

slugsstring[]

The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.

conflictobject

On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.

Show child parameters

etagstringrequired

The entry's current fields etag.

opsarrayrequired

requestIdstring

The Forumulate teamUpdated Oct 17, 2026

Was this page helpful?