Notes: Databases

Use these endpoints to manage records inside notebook databases. Databases are typed nodes within a notebook that store structured records, each with a name and a set of custom field values. The endpoints cover listing, retrieving, searching, creating, updating, and deleting records.

All requests target the Notes container scoped to the project, container, and server hosting the notebook.

List database records

GET /api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records

Returns a paginated list of records in a database. Supports JSON-encoded filters and sorts query parameters for narrowing results.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The ID of the notebook containing the database
databaseId	path	string	Yes	The ID of the database to list records from
filters	query	string	No	JSON-encoded filter expression applied to the records
sorts	query	string	No	JSON-encoded sort expression applied to the records
page	query	integer	No	Page number to return. Default: 1
count	query	integer	No	Number of records per page. Default: 50

Response

200

{
  "records": [
    {
      "id": "rec_01HXY8K2N3M4P5Q6R7S8T9V0W1",
      "name": "Acme Corp",
      "avatar": null,
      "fields": {
        "status": { "type": "string", "value": "Active" },
        "priority": { "type": "number", "value": 1 },
        "tags": { "type": "string_array", "value": ["lead", "enterprise"] }
      }
    },
    {
      "id": "rec_01HXY8K2N3M4P5Q6R7S8T9V0W2",
      "name": "Globex Inc.",
      "avatar": null,
      "fields": {
        "status": { "type": "string", "value": "Pending" },
        "priority": { "type": "number", "value": 2 },
        "tags": { "type": "string_array", "value": ["lead"] }
      }
    }
  ],
  "total": 2,
  "page": 1,
  "count": 50
}

400

{
  "message": "Invalid JSON in filters parameter.",
  "code": "bad_request",
  "details": [
    {
      "path": "filters",
      "message": "Unexpected token at position 12"
    }
  ]
}

Error Code	Title	Description	Resolution
bad_request	Invalid filter or sort parameters	The filters or sorts query parameter contains invalid JSON	Verify the JSON structure of filter and sort parameters

403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "notebookId",
      "message": "Caller is not a collaborator on the notebook"
    }
  ]
}

Error Code	Title	Description	Resolution
forbidden	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

404

{
  "message": "Database not found.",
  "code": "not_found",
  "details": [
    {
      "path": "databaseId",
      "message": "No database node with the provided ID"
    }
  ]
}

Error Code	Title	Description	Resolution
not_found	Database not found	No database node exists with the provided ID	Verify database ID using listNodes

SDK usage

cURL

curl -X GET "https://prj_abc123-cnt_xyz789-notes-1.us-east.containers.hoody.icu/api/v1/notes/notebooks/nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1/databases/dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1/records?page=1&count=50" \
  -H "Authorization: Bearer <token>"

SDK

await client.notes.databases.listIterator(
  "nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  { page: 1, count: 50 }
);

Get a database record

GET /api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/{recordId}

Returns a single record by ID from a database.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The ID of the notebook containing the database
databaseId	path	string	Yes	The ID of the database containing the record
recordId	path	string	Yes	The ID of the record to retrieve

Response

200

{
  "id": "rec_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "name": "Acme Corp",
  "avatar": null,
  "fields": {
    "status": { "type": "string", "value": "Active" },
    "priority": { "type": "number", "value": 1 },
    "tags": { "type": "string_array", "value": ["lead", "enterprise"] }
  }
}

403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "notebookId",
      "message": "Caller is not a collaborator on the notebook"
    }
  ]
}

Error Code	Title	Description	Resolution
forbidden	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

404

{
  "message": "Record not found.",
  "code": "not_found",
  "details": [
    {
      "path": "recordId",
      "message": "No record with the given ID exists in the database"
    }
  ]
}

Error Code	Title	Description	Resolution
not_found	Record not found	No record with the given ID exists in the database	Verify record ID using listRecords or searchRecords

SDK usage

cURL

curl -X GET "https://prj_abc123-cnt_xyz789-notes-1.us-east.containers.hoody.icu/api/v1/notes/notebooks/nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1/databases/dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1/records/rec_01HXY8K2N3M4P5Q6R7S8T9V0W1" \
  -H "Authorization: Bearer <token>"

SDK

await client.notes.databases.get(
  "nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "rec_01HXY8K2N3M4P5Q6R7S8T9V0W1"
);

Search database records

GET /api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/search

Searches records in a database by name. Supports excluding specific record IDs via a JSON-encoded array.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The ID of the notebook containing the database
databaseId	path	string	Yes	The ID of the database to search within
q	query	string	No	Name fragment to match. Default: ""
exclude	query	string	No	JSON-encoded array of record IDs to omit from results

Response

200

{
  "records": [
    {
      "id": "rec_01HXY8K2N3M4P5Q6R7S8T9V0W1",
      "name": "Acme Corp",
      "avatar": null,
      "fields": {
        "status": { "type": "string", "value": "Active" }
      }
    }
  ],
  "total": 1
}

400

{
  "message": "Invalid JSON in exclude parameter.",
  "code": "bad_request",
  "details": [
    {
      "path": "exclude",
      "message": "Expected a JSON array of record IDs"
    }
  ]
}

Error Code	Title	Description	Resolution
bad_request	Invalid exclude parameter	The exclude query parameter contains invalid JSON	Provide a valid JSON array of record IDs to exclude

403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "notebookId",
      "message": "Caller is not a collaborator on the notebook"
    }
  ]
}

Error Code	Title	Description	Resolution
forbidden	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

404

{
  "message": "Database not found.",
  "code": "not_found",
  "details": [
    {
      "path": "databaseId",
      "message": "No database node with the provided ID"
    }
  ]
}

Error Code	Title	Description	Resolution
not_found	Database not found	No database node exists with the provided ID	Verify database ID using listNodes

SDK usage

cURL

curl -X GET "https://prj_abc123-cnt_xyz789-notes-1.us-east.containers.hoody.icu/api/v1/notes/notebooks/nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1/databases/dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1/records/search?q=Acme&exclude=%5B%22rec_01HXY8K2N3M4P5Q6R7S8T9V0W2%22%5D" \
  -H "Authorization: Bearer <token>"

SDK

await client.notes.databases.search(
  "nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  { q: "Acme", exclude: '["rec_01HXY8K2N3M4P5Q6R7S8T9V0W2"]' }
);

Create a database record

POST /api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records

Creates a new record in a database with a name and custom field values.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The ID of the notebook containing the database
databaseId	path	string	Yes	The ID of the database to create the record in

Request Body

Name	Type	Required	Description
id	string	No	Optional client-provided record ID
name	string	No	Display name for the record. Default: "Untitled"
avatar	string | null	No	Avatar reference for the record
fields	object	No	Map of field name to typed value. Default: {}

Response

201

{
  "id": "rec_01HXY8K2N3M4P5Q6R7S8T9V0W3",
  "name": "Initech",
  "avatar": null,
  "fields": {
    "status": { "type": "string", "value": "New" },
    "priority": { "type": "number", "value": 3 }
  }
}

400

{
  "message": "Invalid request body.",
  "code": "bad_request",
  "details": [
    {
      "path": "fields.status",
      "message": "Field value does not match the database schema"
    }
  ]
}

403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "notebookId",
      "message": "Caller is not a collaborator on the notebook"
    }
  ]
}

Error Code	Title	Description	Resolution
forbidden	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin
forbidden	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

404

{
  "message": "Database not found.",
  "code": "not_found",
  "details": [
    {
      "path": "databaseId",
      "message": "No database node with the provided ID"
    }
  ]
}

Error Code	Title	Description	Resolution
not_found	Database not found	No database node exists with the provided ID	Verify database ID using listNodes

409

{
  "message": "Idempotency key conflict.",
  "code": "bad_request",
  "details": [
    {
      "path": "id",
      "message": "A different request was already made with the same idempotency key"
    }
  ]
}

Error Code	Title	Description	Resolution
bad_request	Idempotency conflict	A different request was already made with the same idempotency key	Use a new idempotency key for a different request

500

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": [
    {
      "path": "",
      "message": "Internal server error while persisting record"
    }
  ]
}

Error Code	Title	Description	Resolution
unknown	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

cURL

curl -X POST "https://prj_abc123-cnt_xyz789-notes-1.us-east.containers.hoody.icu/api/v1/notes/notebooks/nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1/databases/dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1/records" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Initech",
    "fields": {
      "status": { "type": "string", "value": "New" },
      "priority": { "type": "number", "value": 3 }
    }
  }'

SDK

await client.notes.databases.create(
  "nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  {
    name: "Initech",
    fields: {
      status: { type: "string", value: "New" },
      priority: { type: "number", value: 3 }
    }
  }
);

Update a database record

PATCH /api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/{recordId}

Updates a record’s name, avatar, or field values. Fields provided in the request are merged with the existing values; fields not present in the body are left unchanged.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The ID of the notebook containing the database
databaseId	path	string	Yes	The ID of the database containing the record
recordId	path	string	Yes	The ID of the record to update

Request Body

Name	Type	Required	Description
name	string	No	New display name for the record
avatar	string | null	No	New avatar reference for the record
fields	object	No	Map of field name to typed value; merged into existing fields

Each value in fields must include a type discriminator. Supported types are boolean, string, string_array, number, and text.

Response

200

{
  "id": "rec_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "name": "Acme Corp (Updated)",
  "avatar": null,
  "fields": {
    "status": { "type": "string", "value": "Closed" },
    "priority": { "type": "number", "value": 1 },
    "tags": { "type": "string_array", "value": ["lead", "enterprise", "closed"] }
  }
}

400

{
  "message": "Invalid request body.",
  "code": "bad_request",
  "details": [
    {
      "path": "fields.priority",
      "message": "Field value does not match the declared type"
    }
  ]
}

403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "notebookId",
      "message": "Caller is not a collaborator on the notebook"
    }
  ]
}

Error Code	Title	Description	Resolution
forbidden	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin
forbidden	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

404

{
  "message": "Record not found.",
  "code": "not_found",
  "details": [
    {
      "path": "recordId",
      "message": "No record with the given ID exists in the database"
    }
  ]
}

Error Code	Title	Description	Resolution
not_found	Record not found	No record with the given ID exists in the database	Verify record ID using listRecords or searchRecords

500

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": [
    {
      "path": "",
      "message": "Internal server error while updating record"
    }
  ]
}

Error Code	Title	Description	Resolution
unknown	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

cURL

curl -X PATCH "https://prj_abc123-cnt_xyz789-notes-1.us-east.containers.hoody.icu/api/v1/notes/notebooks/nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1/databases/dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1/records/rec_01HXY8K2N3M4P5Q6R7S8T9V0W1" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp (Updated)",
    "fields": {
      "status": { "type": "string", "value": "Closed" }
    }
  }'

SDK

await client.notes.databases.update(
  "nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "rec_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  {
    name: "Acme Corp (Updated)",
    fields: {
      status: { type: "string", value: "Closed" }
    }
  }
);

Delete a database record

DELETE /api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/{recordId}

Permanently deletes a record from a database.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The ID of the notebook containing the database
databaseId	path	string	Yes	The ID of the database containing the record
recordId	path	string	Yes	The ID of the record to delete

Response

200

{
  "success": true
}

403

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "details": [
    {
      "path": "recordId",
      "message": "Caller role cannot delete records in this database"
    }
  ]
}

Error Code	Title	Description	Resolution
forbidden	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

404

{
  "message": "Record not found.",
  "code": "not_found",
  "details": [
    {
      "path": "recordId",
      "message": "No record with the given ID exists in the database"
    }
  ]
}

Error Code	Title	Description	Resolution
not_found	Record not found	No record with the given ID exists in the database	Verify record ID using listRecords or searchRecords

500

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": [
    {
      "path": "",
      "message": "Internal server error while deleting record"
    }
  ]
}

Error Code	Title	Description	Resolution
unknown	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

cURL

curl -X DELETE "https://prj_abc123-cnt_xyz789-notes-1.us-east.containers.hoody.icu/api/v1/notes/notebooks/nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1/databases/dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1/records/rec_01HXY8K2N3M4P5Q6R7S8T9V0W1" \
  -H "Authorization: Bearer <token>"

SDK

await client.notes.databases.delete(
  "nbk_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "dbs_01HXY8K2N3M4P5Q6R7S8T9V0W1",
  "rec_01HXY8K2N3M4P5Q6R7S8T9V0W1"
);