Databases

The database object#

{
  "object": "database",
  "id": "01k8x2p3q5r7s9t1v3w5x7y9za",
  "title": [ { "plain_text": "Tasks" } ],
  "description": [],
  "icon": null,
  "cover": null,
  "parent": { "type": "page_id", "page_id": "01k8x2k…" },
  "url": "https://docs.polder.work/pages/01k8x2k…",
  "public_url": null,
  "is_inline": false,
  "archived": false,
  "in_trash": false,
  "properties": {
    "Name": { "id": "title", "name": "Name", "type": "title", "description": "", "title": {} },
    "Status": { "id": "k3f9a1", "name": "Status", "type": "status", "description": "", "status": { "options": [ { "id": "…", "name": "In progress", "color": "blue" } ], "groups": [ … ] } },
    "Points": { "id": "p0x2bb", "name": "Points", "type": "number", "description": "", "number": { "format": "number" } }
  },
  "data_sources": [ { "id": "01k8x2p3q5r7s9t1v3w5x7y9za", "name": "Tasks", "kind": "default" } ],
  "created_time": "…", "last_edited_time": "…", "created_by": { "object": "user", "id": "3" }, "last_edited_by": { "object": "user", "id": "3" }
}

A database's id is the id of its database block: the child_database block on a page, which is also the database_id in its rows' parent. For a full-page database, the id of its page works wherever a database id is expected.

A database can hold several data sources, each with its own rows and properties. data_sources lists the ones the integration can reach (kind is Polder only). A data source is the same shape as a database with object: "data_source"; a database with one source is its own data source.

properties is keyed by name. Property types are the ones in the page object, plus formula, rollup and the like, which can be read here but not created.

Create a database#

Creates a database on a page the integration is connected to, and returns it.

Body

• There is exactly one title property (a second returns 400). If you send none, it is called "Name".
• The types you can create are rich_text, number (with format), select, multi_select, status, date, people, files, checkbox, url, email, phone_number, created_time, created_by, last_edited_time, last_edited_by and unique_id (with prefix). Formulas, relations and rollups have to be set up in the app; asking for them returns 400 validation_error.
• description on a property is kept.

curl https://docs.polder.work/api/v1/databases \
  -H "Authorization: Bearer $POLDER_DOCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": { "type": "page_id", "page_id": "01k8x2k5r1m3a7z9w2e4t6y8ui" },
    "title": [ { "text": { "content": "Bugs" } } ],
    "properties": {
      "Bug": { "title": {} },
      "Severity": { "select": { "options": [ { "name": "High", "color": "red" }, { "name": "Low" } ] } },
      "Estimate": { "number": { "format": "number_with_commas" } },
      "Reported": { "date": {} }
    }
  }'

Retrieve a database#

Returns the database object.

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

Update a database#

Changes the title, icon and properties, or moves the database to the trash. Returns the database.

{
  "title": [ { "text": { "content": "Team tasks" } } ],
  "properties": {
    "Points": { "name": "Estimate" },
    "Urgent": null,
    "Status": { "select": { "options": [ { "name": "Blocked", "color": "red" } ] } },
    "Owner": { "people": {} }
  }
}

• A property name that does not exist yet adds a property, from its type.
• {"name": "…"} renames a property; description sets its description.
• null removes a property. The title property cannot be removed, and a name that does not exist returns 400.
• Options in a select, multi_select or status config are added when they are new. Existing options are never removed through the API (Notion replaces the list). New status options go in the "to-do" group.
• Changing a property's type returns 400.
• icon changes the icon of a full-page database.
• in_trash: true (or archived) moves the whole database to the trash.

Query a database#

Returns the rows of a database as a list of page objects (type: "page_or_database"). Templates are not included, nor are rows the integration's admin may not see.

Body

curl https://docs.polder.work/api/v1/databases/01k8x2p3q5r7s9t1v3w5x7y9za/query \
  -H "Authorization: Bearer $POLDER_DOCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "or": [
      { "property": "Status", "status": { "equals": "In progress" } },
      { "and": [
        { "property": "Points", "number": { "greater_than": 3 } },
        { "property": "Due", "date": { "next_week": {} } }
      ] }
    ] },
    "sorts": [
      { "property": "Due", "direction": "ascending" },
      { "timestamp": "created_time", "direction": "descending" }
    ],
    "page_size": 50
  }'

Filters#

A condition names a property (by name or id) and puts exactly one operator under the property type's name: {"property": "Points", "number": {"greater_than": 3}}. and / or groups can nest two levels deep. A filter that does not fit returns 400 validation_error.

{"timestamp": "created_time", "created_time": {"after": "2026-10-01"}} filters on a row's creation or last edit time (last_edited_time).

Filters are evaluated by the same code that applies a view's filters in the app, so the API and a view with the same filter show the same rows. Filtering on a formula, rollup or verification property returns 400.

Sorts#

Each sort is {"property": "Due", "direction": "ascending"} or {"timestamp": "created_time" | "last_edited_time", "direction": …}. direction defaults to ascending. The first sort decides, the next ones break ties. Select and status options sort in their option order. Empty values come last in either direction. Without sorts, rows come in the database's own order.

Retrieve a data source#

Returns one data source of a database: the same fields as the database object, with object: "data_source". {id} is the id from the database's data_sources list.

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

Query a data source#

Queries the rows of one data source. The body, filters, sorts and response are those of querying a database.

curl https://docs.polder.work/api/v1/data_sources/01k8x2p3q5r7s9t1v3w5x7y9za/query \
  -H "Authorization: Bearer $POLDER_DOCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"property": "Name", "title": {"contains": "launch"}}}'