PolderAPI

Docs API

Pages

Create, read and update pages and database rows, and read a single property.

Base URLhttps://docs.polder.work

The page object

{
  "object": "page",
  "id": "01k8x2m4t7q9b3n5v6c8d0f2gh",
  "created_time": "2026-10-02T09:30:00.000Z",
  "last_edited_time": "2026-10-02T09:45:00.000Z",
  "created_by": { "object": "user", "id": "3" },
  "last_edited_by": { "object": "user", "id": "3" },
  "cover": null,
  "icon": { "type": "emoji", "emoji": "🚀" },
  "parent": { "type": "page_id", "page_id": "01k8x2k…" },
  "archived": false,
  "in_trash": false,
  "properties": { "title": { "id": "title", "type": "title", "title": [ { "plain_text": "Launch plan" } ] } },
  "url": "https://docs.polder.work/pages/01k8x2m4t7q9b3n5v6c8d0f2gh",
  "public_url": null
}

parent is one of {"type": "workspace", "workspace": true}, {"type": "page_id", …}, {"type": "database_id", …} (a row) or {"type": "block_id", …} (a page inside a toggle or column). archived and in_trash are always equal.

A page that is not a database row has a single title property. A row has every property of its database, keyed by name. Each value has id (the property's key), type and a value under that type's name:

Type Value
title, rich_text rich text array
number number or null
select, status {id, name, color} or null
multi_select [{id, name, color}]
date {start, end, time_zone: null} or null
people [{object: "user", id}]
files [{name, type: "external", external: {url}}]; uploads have type: "file" and file: {url, expiry_time: null}
checkbox boolean
url, email, phone_number string or null
relation [{id}]
created_time, last_edited_time ISO time
created_by, last_edited_by {object: "user", id}
unique_id {prefix, number}
place (Polder only) the stored place value
formula, rollup, verification null: these are calculated in the browser

Create a page

POST/api/v1/pagescapability insert_content

Creates a page under a page the integration is connected to, or a row in a database. The response is the new page object.

Body

Field Type Required Description
parent object yes {"page_id": …}, or for a row {"database_id": …} or {"data_source_id": …}. The page id of a full-page database also adds a row.
properties object no For a plain page, only title. For a row, values keyed by property name or id
children array no Blocks to put in the page; see Blocks for the types. At most 100 blocks in total, nested at most two levels deep
icon object no {"type": "emoji", "emoji": "🚀"} or {"type": "external", "external": {"url": "…"}}
cover object no {"type": "external", "external": {"url": "https://…"}}
  • An integration cannot create pages at the top of the workspace: a workspace parent returns 400 validation_error.
  • The parent page must not be locked.
  • The title is taken from the title property, whatever the title property of the database is called: {"title": [ {"text": {"content": "…"}} ]} or {"title": {"title": […]}}. Without one, the title is empty.
  • For a row, the shapes are those of the table above. The wrapper is optional: "Points": 3 works as well as "Points": {"number": 3}. Options are matched by name or id. A select or multi_select option that does not exist yet is created, as in Notion; status options must exist. people take user ids. Computed properties (formula, rollup, created/edited time and by, unique id) cannot be set.
curl https://docs.polder.work/api/v1/pages \
  -H "Authorization: Bearer $POLDER_DOCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": { "page_id": "01k8x2k5r1m3a7z9w2e4t6y8ui" },
    "icon": { "type": "emoji", "emoji": "🚀" },
    "properties": { "title": { "title": [ { "text": { "content": "Launch plan" } } ] } },
    "children": [
      { "type": "heading_2", "heading_2": { "rich_text": [ { "text": { "content": "Goals" } } ] } },
      { "type": "to_do", "to_do": { "rich_text": [ { "text": { "content": "Ship it" } } ], "checked": false } }
    ]
  }'

Retrieve a page

GET/api/v1/pages/{id}capability read_content

Returns the page object. A database's id returns 400 validation_error ("is a database, not a page"): use /databases/{id}. A page in the trash, or one the integration cannot reach, is a 404.

curl https://docs.polder.work/api/v1/pages/01k8x2m4t7q9b3n5v6c8d0f2gh \
  -H "Authorization: Bearer $POLDER_DOCS_KEY"

Update a page

PATCH/api/v1/pages/{id}capability update_content

Changes properties, icon, cover or lock, or moves the page to the trash and back. Returns the page. Send only what changes.

Body

Field Type Description
properties object For a database row, any of its properties. For any other page, title only (another name returns 400)
icon object or null A new icon, or null to remove it
cover object or null A new cover, or null to remove it
is_locked boolean Lock or unlock the page. Without it, a change to a locked page returns 400 validation_error
in_trash boolean true moves the page and everything in it to the trash; false brings it back. archived works the same

A page in the trash accepts only {"in_trash": false}; restoring and editing in one request is allowed. Restoring needs delete permission on the page.

curl -X PATCH https://docs.polder.work/api/v1/pages/01k8x2m4t7q9b3n5v6c8d0f2gh \
  -H "Authorization: Bearer $POLDER_DOCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"status": {"name": "Done"}}, "Points": {"number": 8}}}'

Retrieve a page property

GET/api/v1/pages/{id}/properties/{property}capability read_content

Returns one property's value as a property_item. {property} is the property's id (key) or its name, URL-encoded. On a page that is not a row, only title exists.

title, rich_text, people and relation return a paginated list of property_item objects, one per text segment, person or page (start_cursor and page_size as query parameters). Every other type returns a single property_item:

{ "object": "property_item", "id": "p0x2bb", "type": "number", "number": 8 }

An unknown property is 404 object_not_found.

curl "https://docs.polder.work/api/v1/pages/01k8x2m4t7q9b3n5v6c8d0f2gh/properties/Points" \
  -H "Authorization: Bearer $POLDER_DOCS_KEY"