V2
Mutate Database Atomically
Rename properties by stable ID and create or update records in one transaction.
Mutate Database Atomically
Use Case
Use this endpoint when one operation must change both a database schema and its records. For example, rename the title property to Name and create a record titled Ada Lovelace. Every change runs in one transaction, so a validation or permission failure leaves no partial writes.
Endpoint
| Item | Value |
|---|---|
| Method | POST |
| Path | /v2/databases/:database_id/mutations |
| Returns | database_mutation |
| Scope | databases.write, pages.write |
Request
Headers
| Header | Type | Required | Description |
|---|---|---|---|
Authorization |
string | Yes | Bearer <token>. |
Idempotency-Key |
string | No | A stable value is recommended for safely retrying the whole mutation. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
properties |
object | No | Add properties, or update an existing property by including its stable id. |
create_records |
array | No | Records to create. title is written to the database's current title property. |
update_records |
array | No | Existing records to update. Each item must include an explicit record_id. |
Read the database first to obtain the real property ID, then submit the mutation:
{
"properties": {
"Name": {
"id": "title",
"name": "Name",
"type": "title",
"title": {}
}
},
"create_records": [
{
"title": "Ada Lovelace"
}
]
}
Response
{
"object": "database_mutation",
"database_id": "66666666-6666-4666-8666-666666666666",
"updated_properties": [
{
"id": "title",
"name": "Name",
"type": "title",
"created": false
}
],
"created_records": [
{
"id": "77777777-7777-4777-8777-777777777777",
"title": "Ada Lovelace"
}
],
"updated_records": []
}
Behavior
- Rename an existing property by passing the stable property
idreturned by the database API. Do not simulate a rename by creating another text property with the same display name. - Use
create_recordsfor new records. This endpoint never overwrites existing records implicitly. - Every
update_recordsitem requires an explicitrecord_id. The caller needs write access to the database and every target record. - One request may contain at most 20 property changes and 100 record changes.
- Schema and record changes share one database transaction.
Errors
400 validation_error: unknown property ID, duplicate property name, record outside the target database, or empty request.401 unauthorized: invalid or expired token.403 forbidden: missing scope or no write access to the database or any target record.404 not_found: database does not exist.409 conflict: the same idempotency key was reused with a different request body.