The Notes: Databases API lets you manage the individual records stored inside database nodes within a notebook. Use these endpoints to list, retrieve, search, create, update, and delete records — including the custom field values defined by the database schema.

List database records

Returns a paginated list of records in a database. Supports JSON-encoded filters and sorts.

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

Parameters

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

cURL

curl -G "https://api.hoody.com/api/v1/notes/notebooks/nb_8f3c1a2b/databases/db_4e9d6f0a/records" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode 'filters=[{"field":"status","op":"eq","value":"active"}]' \
  --data-urlencode 'sorts=[{"field":"name","dir":"asc"}]' \
  --data-urlencode 'page=1' \
  --data-urlencode 'count=50'

SDK

const page = await client.notes.databases.listIterator({
  notebookId: "nb_8f3c1a2b",
  databaseId: "db_4e9d6f0a",
  filters: '[{"field":"status","op":"eq","value":"active"}]',
  sorts: '[{"field":"name","dir":"asc"}]',
  page: 1,
  count: 50,
});

200

{
  "records": [
    {
      "id": "rec_01HQ2XK9A1B2C3D4E5F6G7H8J9",
      "name": "Acme Corp",
      "fields": {
        "status": { "type": "string", "value": "active" },
        "owner": { "type": "string", "value": "user_abc123" }
      }
    },
    {
      "id": "rec_01HQ2XK9B2C3D4E5F6G7H8J9K0",
      "name": "Globex",
      "fields": {
        "status": { "type": "string", "value": "active" },
        "owner": { "type": "string", "value": "user_def456" }
      }
    }
  ],
  "total": 142,
  "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"
}

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"
}

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

Get a database record

Returns a single record by ID from a database.

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

Parameters

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

cURL

curl "https://api.hoody.com/api/v1/notes/notebooks/nb_8f3c1a2b/databases/db_4e9d6f0a/records/rec_01HQ2XK9A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer <token>"

SDK

const record = await client.notes.databases.get({
  notebookId: "nb_8f3c1a2b",
  databaseId: "db_4e9d6f0a",
  recordId: "rec_01HQ2XK9A1B2C3D4E5F6G7H8J9",
});

200

{
  "id": "rec_01HQ2XK9A1B2C3D4E5F6G7H8J9",
  "name": "Acme Corp",
  "avatar": "https://cdn.hoody.com/avatars/acme.png",
  "fields": {
    "status": { "type": "string", "value": "active" },
    "renewal": { "type": "number", "value": 365 },
    "tags": { "type": "string_array", "value": ["enterprise", "us-east"] },
    "notes": { "type": "text", "value": "Renewal in Q4." }
  }
}

403

{
  "message": "You do not have access to this node.",
  "code": "forbidden"
}

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"
}

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

Search database records

Searches records in a database by name. Supports excluding specific record IDs.

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	ID of the parent notebook
databaseId	path	string	Yes	ID of the database node
q	query	string	No	Name query string. Default: ""
exclude	query	string	No	JSON-encoded array of record IDs to exclude from results

cURL

curl -G "https://api.hoody.com/api/v1/notes/notebooks/nb_8f3c1a2b/databases/db_4e9d6f0a/records/search" \
  -H "Authorization: Bearer <token>" \
  --data-urlencode 'q=Acme' \
  --data-urlencode 'exclude=["rec_01HQ2XK9A1B2C3D4E5F6G7H8J9"]'

SDK

const result = await client.notes.databases.search({
  notebookId: "nb_8f3c1a2b",
  databaseId: "db_4e9d6f0a",
  q: "Acme",
  exclude: '["rec_01HQ2XK9A1B2C3D4E5F6G7H8J9"]',
});

200

{
  "records": [
    {
      "id": "rec_01HQ2XK9B2C3D4E5F6G7H8J9K0",
      "name": "Acme Industries",
      "fields": {
        "status": { "type": "string", "value": "active" }
      }
    }
  ],
  "total": 1
}

400

{
  "message": "Invalid JSON in exclude parameter.",
  "code": "bad_request",
  "details": [
    { "path": "exclude", "message": "Expected an 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"
}

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"
}

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

Create a database record

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

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	ID of the parent notebook
databaseId	path	string	Yes	ID of the database node

Request Body

Name	Type	Required	Description
id	string	No	Optional client-supplied record ID
name	string	No	Record name. Default: "Untitled"
avatar	string | null	No	Avatar image URL for the record, or null to clear
fields	object	No	Key-value map of field names to field values. Default: {}

cURL

curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/nb_8f3c1a2b/databases/db_4e9d6f0a/records" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Initech",
    "fields": {
      "status": { "type": "string", "value": "prospect" },
      "tags": { "type": "string_array", "value": ["smb", "emea"] }
    }
  }'

SDK

const record = await client.notes.databases.create({
  notebookId: "nb_8f3c1a2b",
  databaseId: "db_4e9d6f0a",
  data: {
    name: "Initech",
    fields: {
      status: { type: "string", value: "prospect" },
      tags: { type: "string_array", value: ["smb", "emea"] },
    },
  },
});

201

{
  "id": "rec_01HQ2XL1C3D4E5F6G7H8J9K0L1",
  "name": "Initech",
  "avatar": null,
  "fields": {
    "status": { "type": "string", "value": "prospect" },
    "tags": { "type": "string_array", value: ["smb", "emea"] }
  }
}

400

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

403

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden"
}

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"
}

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"
}

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"
}

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

Update a database record

Updates a record name, avatar, or field values. Fields are merged with existing values.

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

Parameters

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

Request Body

Name	Type	Required	Description
name	string	No	New record name
avatar	string | null	No	New avatar image URL, or null to clear the existing avatar
fields	object	No	Partial map of field names to field values. Each value is an object with a type and a typed value (boolean, string, string_array, number, or text). Provided fields are merged with existing values

cURL

curl -X PATCH "https://api.hoody.com/api/v1/notes/notebooks/nb_8f3c1a2b/databases/db_4e9d6f0a/records/rec_01HQ2XK9A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp (Renewed)",
    "fields": {
      "status": { "type": "string", "value": "renewed" },
      "renewal": { "type": "number", "value": 730 }
    }
  }'

SDK

const record = await client.notes.databases.update({
  notebookId: "nb_8f3c1a2b",
  databaseId: "db_4e9d6f0a",
  recordId: "rec_01HQ2XK9A1B2C3D4E5F6G7H8J9",
  data: {
    name: "Acme Corp (Renewed)",
    fields: {
      status: { type: "string", value: "renewed" },
      renewal: { type: "number", value: 730 },
    },
  },
});

200

{
  "id": "rec_01HQ2XK9A1B2C3D4E5F6G7H8J9",
  "name": "Acme Corp (Renewed)",
  "avatar": "https://cdn.hoody.com/avatars/acme.png",
  "fields": {
    "status": { "type": "string", "value": "renewed" },
    "renewal": { "type": "number", "value": 730 },
    "owner": { "type": "string", "value": "user_abc123" }
  }
}

400

{
  "message": "Invalid field value type.",
  "code": "bad_request",
  "details": [
    { "path": "fields.renewal", "message": "Expected type \"number\"" }
  ]
}

403

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden"
}

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"
}

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"
}

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

Note

Field values supplied on update are typed. Each value object must include a type field that matches the value’s runtime type: boolean, string, string_array, number, or text. Mismatched types return a 400.

Delete a database record

Permanently deletes a record from a database.

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

Parameters

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

cURL

curl -X DELETE "https://api.hoody.com/api/v1/notes/notebooks/nb_8f3c1a2b/databases/db_4e9d6f0a/records/rec_01HQ2XK9A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer <token>"

SDK

await client.notes.databases.delete({
  notebookId: "nb_8f3c1a2b",
  databaseId: "db_4e9d6f0a",
  recordId: "rec_01HQ2XK9A1B2C3D4E5F6G7H8J9",
});

200

{
  "success": true
}

403

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden"
}

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"
}

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"
}

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

Caution

Deletion is permanent. The record and all of its field values are removed immediately and cannot be recovered.