Update Page

Use Case

Use this endpoint to update page title, properties, icon, cover, or trash state. It supports optional optimistic concurrency with If-Match.

Endpoint

Permissions

Requires pages.write and access to the page.

Headers

Parameters

Request Example

{
  "properties": {
    "title": {
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Quarterly Plan Updated"
          }
        }
      ]
    }
  },
  "icon": null,
  "cover": {
    "type": "external",
    "external": {
      "url": "https://example.com/cover.png"
    }
  },
  "in_trash": false
}

Response Example

{
  "object": "page",
  "id": "11111111-1111-4111-8111-111111111111",
  "page_type": "page",
  "created_time": "2026-04-09T08:00:00.000Z",
  "last_edited_time": "2026-04-09T09:30:00.000Z",
  "created_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "last_edited_by": {
    "object": "user",
    "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  },
  "parent": {
    "type": "page_id",
    "page_id": "55555555-5555-4555-8555-555555555555"
  },
  "in_trash": false,
  "icon": null,
  "cover": null,
  "properties": {
    "title": {
      "id": "title",
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Quarterly Plan Updated",
            "link": null
          },
          "plain_text": "Quarterly Plan Updated",
          "href": null
        }
      ]
    }
  },
  "url": "https://buildin.ai/docs/11111111-1111-4111-8111-111111111111"
}

Behavior

• This is a partial update endpoint.
• properties only updates the submitted properties.
• icon and cover remove the value when set to null.
• in_trash toggles page trash state.
• A mismatched If-Match header rejects the write with 409 conflict.

Errors

• 401 unauthorized: invalid or expired token.
• 403 forbidden: missing pages.write or no access.
• 404 not_found: page does not exist.
• 409 conflict: If-Match does not match the current page version.

Related Docs

Prerequisites

• Get Page

Next Steps

• Delete Page

References

• Conventions
• Error Codes