V2
Page Property Models
Distinguish database property schema, page property values, and paginated property_item responses.
Page Property Models
V2 uses three related property shapes: database property schema, page property values, and property_item responses.
Schema vs Values
| Shape | Where it appears | Purpose |
|---|---|---|
| Database property schema | database.properties and database create/update requests |
Defines field names, types, options, and configuration. |
| Page property value | page.properties and page create/update requests |
Stores the value for a page or database record. |
property_item |
GET /v2/pages/:page_id/properties/:property_id |
Returns one property value or a paginated set of value items. |
Property Value Types
| Type | Value field | Notes |
|---|---|---|
title |
title |
rich_text array used as the page title. |
rich_text |
rich_text |
rich_text array for text content. |
number |
number |
Number or null. |
select |
select |
One option or null. |
multi_select |
multi_select |
Array of options. |
date |
date |
Start, optional end, and optional time zone. |
people |
people |
Array of user references. |
files |
files |
Array of file objects. |
checkbox |
checkbox |
Boolean. |
url |
url |
URL string or null. |
email |
email |
Email string or null. |
phone_number |
phone_number |
Phone string or null. |
formula |
formula |
Computed value; read-only. |
relation |
relation |
Array of related page references. |
rollup |
rollup |
Computed rollup value; read-only. |
created_time |
created_time |
Read-only timestamp. |
created_by |
created_by |
Read-only user reference. |
last_edited_time |
last_edited_time |
Read-only timestamp. |
last_edited_by |
last_edited_by |
Read-only user reference. |
Example Page Property Value
{
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Launch Plan",
"link": null
},
"plain_text": "Launch Plan",
"href": null
}
]
}
Paginated property_item Response
{
"object": "list",
"results": [
{
"object": "property_item",
"id": "people",
"type": "people",
"people": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
}
}
],
"next_cursor": null,
"has_more": false
}
Notes
- Schema fields describe what values are allowed; value fields carry data for one page.
- Some computed property types are read-only and cannot be set through page write endpoints.
- Large relation, people, rollup, or file values may be paginated by the property item endpoint.
- When writing properties by name, match the database schema exactly.