Create Database View

Use Case

Use this endpoint to add another view to a database (for example another board or calendar). The view type is determined at creation and cannot be changed afterwards; create another view to switch types.

Endpoint

Permissions

Requires databases.write and write access to the database.

Parameters

All property references should use the exact property id returned by the database or view API, otherwise the request fails with 400. For backward compatibility, only property_layout[].property_id additionally accepts the literal title; when the schema has no exact title key, the API resolves it to the sole title property and stores its exact id. For select and multi_select filters, use the option id returned by Retrieve a database. A unique option name is also accepted for backward compatibility and normalized to its id; unknown or ambiguous names return 400.

Request Example

curl -X POST https://api.buildin.ai/v2/databases/66666666-6666-4666-8666-666666666666/views \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Status board",
    "type": "board",
    "group_by": { "property_id": "88888888-8888-4888-8888-888888888888", "hide_empty_groups": false },
    "config": { "card_size": "medium" }
  }'

Behavior

• The view record and the database block's views array are written in one transaction.
• Initial manual order: when the database holds at most 500 records, the current record order is copied; otherwise the order starts empty (queries fall back to the natural record order, and the web client self-heals it).
• Filter limits: at most 100 conditions and nesting depth 2; unknown or ambiguous select options are rejected; formula/rollup properties are not allowed in conditions (including isEmpty/isNotEmpty, because the server-side evaluator cannot evaluate them and such a condition would be silently dropped at query time).
• mode is rejected on write: the server-side evaluator always applies any semantics, so accepting it would silently mislead callers.
• Width limit: property_layout.width is an integer between 80 and 800.
• created_time / last_edited_time in the response come from the persisted row, so the weak ETag on the response headers can be used directly as If-Match on a later PATCH.

Type-specific defaults

Filled from the existing schema, matching how the product creates views:

Unlike the web client, this endpoint does not create the missing property for you; it rejects the request instead of leaving behind a view the product cannot render.

Errors