---
title: "Create a page"
method: POST
path: "/api/pages"
tags: ["pages"]
---

# Create a page

`POST /api/pages`

## Request

- Base URL: `https://telawiki.com`
- URL: `https://telawiki.com/api/pages`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `tela_session`

`editor+` on the target space. Two server-side transforms to know about: leading YAML frontmatter in `body` is lifted into `props` (except on deck and sheet pages, whose bodies are stored verbatim), and a leading `# Heading` identical to `title` is stripped.

## Request body

- object
  - `space_id` integer, required
  - `parent_id` integer, nullable: Omit or null for a top-level page. Must live in the same space.
  - `title` string, required
  - `body` string: Markdown.
  - `props` PageProps: Free-form page properties. Reserved keys are dropped. Two are load-bearing: `deck: true` makes the body a Slidev presentation, `sheet: true` makes it a spreadsheet — both are then stored verbatim, frontmatter included.
  - `status` 'draft' | 'published': A `draft` is labelled in the app and never served on public spaces or share links until published. Defaults to `published`.

## Response `201`

The page.

- object
  - `page` Page, required
    - `id` integer, required
    - `space_id` integer, required
    - `parent_id` integer, nullable, required
    - `title` string, required
    - `body` string, required: Canonical markdown. This is the whole document — tela has no block model.
    - `position` integer, required: Sort order among siblings.
    - `props` PageProps: Free-form page properties. Reserved keys are dropped. Two are load-bearing: `deck: true` makes the body a Slidev presentation, `sheet: true` makes it a spreadsheet — both are then stored verbatim, frontmatter included.
    - `created_at` string, required: `YYYY-MM-DD HH:MM:SS` in UTC.
    - `updated_at` string, required: `YYYY-MM-DD HH:MM:SS` in UTC.
    - `version` integer: Advances on every title/body/props change. Send it back as `base_version` on update to refuse overwriting an edit you haven't seen.
    - `status` 'draft' | 'published': A `draft` is labelled in the app and never served on public spaces or share links until published.

## Other responses

- `400`: `invalid_json`, `invalid_title`, `invalid_space_id`, `invalid_parent_id`, `space_not_found`, `parent_not_found`, or `parent_space_mismatch`.
- `402`: `quota_exceeded` — a plan limit (pages, storage) was reached.
- `403`: `forbidden` (no access, or the role is too low), `viewer_no_write`, `api_key_scope` (the token's scope forbids this method), or `api_key_space_scope` (the token is pinned to another space).
- `500`: `internal` — server error.

---

[API](https://skmtc.dev/telawiki/apis/tela-rest-api.md) · [All operations](https://skmtc.dev/telawiki/apis/tela-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telawiki/apis/tela-rest-api/revisions/f316f31f6fcb?raw)