Update Database

Use Case

Use this endpoint to change database title, description, icon, cover, 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
  }
}

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.
• When a property schema contains an existing property id, that stable ID is used for the update and supports renaming. Unknown IDs are rejected.
• Use Mutate Database Atomically when the same request also creates or updates records, so schema and record writes cannot partially succeed.
• title, description, icon, and cover 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

• Mutate Database Atomically
• Query Database

References

• Page Property Models
• Error Codes