Update Database

Use Case

Use this endpoint to change database title, description, icon, cover, trash state, or property schema.

Endpoint

Permissions

Requires databases.write and write access to the database.

Parameters

Request Example

{
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Task Board V2"
      }
    }
  ],
  "description": [
    {
      "type": "text",
      "text": {
        "content": "Tracks release work and task status"
      }
    }
  ],
  "properties": {
    "Priority": {
      "name": "Priority",
      "type": "select",
      "select": {
        "options": [
          {
            "name": "P0",
            "color": "red"
          },
          {
            "name": "P1",
            "color": "orange"
          }
        ]
      }
    },
    "Status": null
  },
  "in_trash": false
}

Response Example

{
  "object": "database",
  "id": "66666666-6666-4666-8666-666666666666",
  "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"
  },
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Task Board V2",
        "link": null
      },
      "plain_text": "Task Board V2",
      "href": null
    }
  ],
  "description": [],
  "icon": null,
  "cover": null,
  "parent": {
    "type": "page_id",
    "page_id": "55555555-5555-4555-8555-555555555555"
  },
  "properties": {
    "Name": {
      "id": "title",
      "type": "title",
      "name": "Name"
    },
    "Status": {
      "id": "16161616-1616-4616-8616-161616161616",
      "type": "select",
      "name": "Status"
    }
  },
  "in_trash": false,
  "is_inline": false,
  "url": "https://buildin.ai/database/66666666-6666-4666-8666-666666666666"
}

Behavior

• This is a partial update endpoint.
• Passing null for a property schema deletes that property from the database.
• New property schemas are matched or added by property name.
• title, description, icon, cover, and in_trash can be updated independently.

Errors

• 400 validation_error: invalid schema update.
• 401 unauthorized: invalid or expired token.
• 403 forbidden: missing databases.write or no access.
• 404 not_found: database does not exist.

Related Docs

Prerequisites

• Get Database

Next Steps

• Delete Database
• Query Database

References

• Page Property Models
• Error Codes