Database Records
Discover databases and write text, selection, reference, and file values through the public REST API.
Use database-specific operations when a workspace has more than one database. REST and GraphQL support the same database discovery operations. Choose either transport; see GraphQL database records for the equivalent queries.
Discover records and fields
| Resource | Request |
|---|---|
| Databases | GET /v1/databases?workspaceId=WORKSPACE_ID |
| Records | GET /v1/databases/DATABASE_ID/records?workspaceId=WORKSPACE_ID |
| Visible fields and options | GET /v1/databases/DATABASE_ID/fields?workspaceId=WORKSPACE_ID&forView=true |
Send your normal authentication headers. Use https://rest.blue.app, or /v1 on your API deployment host. Database-record lists return nextCursor; pass it as cursor for the next page. first controls the page size, up to 200. See List Database Records.
Write a field
Send POST /v1/set-database-field-value:
{
"workspaceId": "workspace-id",
"databaseId": "database-id",
"recordId": "record-id",
"fieldId": "field-id",
"kind": "text",
"value": { "text": "Updated value" },
"clientMutationId": "field-change-001",
"entitySequence": 1
}Choose the kind and value for your field:
| Field | kind | value |
|---|---|---|
| TEXT | text | {"text":"Example"} |
| SELECT_SINGLE | select | ["option-id"] |
| REFERENCE | reference | ["record-id"] |
| FILE | file | ["file-id"] |
Array values replace the full set; [] clears it. FILE values use File.id, not the upload UID. Complete the file upload flow before linking a file.
For each later write to the same record and field, use a new mutation ID and a sequence greater than all previous sequences. On retry, preserve the original ID, sequence, and payload. Check the response outcome: ACCEPTED and REPLAYED mean success; do not treat CONFLICT or REJECTED as a successful save. See Set Database Field Value for other kinds and atomic add/remove operations.
The public GraphQL equivalent, setRecordFieldValue, owns its sequencing internally and does not accept these REST retry parameters. See GraphQL database records for singleton reads, file attachment by UID, color, delete, restore, and TABLE examples.
Create records
Use Create Database Record with explicit workspaceId and databaseId. Optional groupOptionId selects a live option on a mounted single-select field. The generic create-record operation retains the workspace/list creation contract.
Legacy native-field and bulk operations are not interchangeable with database field writes. Use actual field IDs for native database fields; separate calls are not an atomic bulk transaction.