The Hoody Notes: Databases API provides endpoints for managing individual records within a notebook database. Use these endpoints to list, retrieve, search, create, update, and delete database records, and to filter and sort records by custom field values.

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
filters	query	string	No	JSON-encoded filter expression applied to records
sorts	query	string	No	JSON-encoded sort expression
page	query	integer	No	Page number (default: 1)
count	query	integer	No	Records per page (default: 50)
notebookId	path	string	Yes	ID of the parent notebook
databaseId	path	string	Yes	ID of the target database

cURL

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

SDK

const iterator = await client.notes.databases.listIterator({
  notebookId: "nb_5f8e7d6c5b4a39281706f5e4",
  databaseId: "db_1a2b3c4d5e6f7890abcdef12",
  filters: '[{"field":"status","op":"eq","value":"active"}]',
  sorts: '[{"field":"createdAt","dir":"desc"}]',
  page: 1,
  count: 50,
});

for await (const record of iterator) {
  console.log(record);
}

200

{
  "records": [
    {
      "id": "rec_a1b2c3d4e5f6789012345678",
      "name": "Acme Corp",
      "avatar": null,
      "fields": {
        "status": { "type": "string", "value": "active" },
        "owner": { "type": "string", "value": "Jane Cooper" }
      },
      "createdAt": "2025-01-15T10:32:00.000Z",
      "updatedAt": "2025-03-04T08:15:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "count": 50
}

400

{
  "message": "Invalid JSON in filters parameter.",
  "code": "bad_request"
}

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 target database
recordId	path	string	Yes	ID of the record to retrieve

cURL

curl "https://api.hoody.com/api/v1/notes/notebooks/nb_5f8e7d6c5b4a39281706f5e4/databases/db_1a2b3c4d5e6f7890abcdef12/records/rec_a1b2c3d4e5f6789012345678" \
  -H "Authorization: Bearer <token>"

SDK

const record = await client.notes.databases.get({
  notebookId: "nb_5f8e7d6c5b4a39281706f5e4",
  databaseId: "db_1a2b3c4d5e6f7890abcdef12",
  recordId: "rec_a1b2c3d4e5f6789012345678",
});

200

{
  "id": "rec_a1b2c3d4e5f6789012345678",
  "name": "Acme Corp",
  "avatar": "https://cdn.hoody.com/avatars/acme.png",
  "fields": {
    "status": { "type": "string", "value": "active" },
    "priority": { "type": "number", "value": 3 },
    "tags": { "type": "string_array", "value": ["enterprise", "q1"] }
  },
  "createdAt": "2025-01-15T10:32:00.000Z",
  "updatedAt": "2025-03-04T08:15:00.000Z"
}

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
q	query	string	No	Name query string (default: "")
exclude	query	string	No	JSON array of record IDs to exclude from results
notebookId	path	string	Yes	ID of the parent notebook
databaseId	path	string	Yes	ID of the target database

cURL

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

SDK

const results = await client.notes.databases.search({
  notebookId: "nb_5f8e7d6c5b4a39281706f5e4",
  databaseId: "db_1a2b3c4d5e6f7890abcdef12",
  q: "Acme",
  exclude: '["rec_a1b2c3d4e5f6789012345678"]',
});

200

{
  "records": [
    {
      "id": "rec_9876543210abcdef12345678",
      "name": "Acme Industries",
      "avatar": null,
      "fields": {
        "status": { "type": "string", "value": "prospect" }
      },
      "createdAt": "2025-02-20T14:05:00.000Z",
      "updatedAt": "2025-03-01T09:42:00.000Z"
    }
  ],
  "total": 1
}

400

{
  "message": "Invalid JSON in exclude parameter.",
  "code": "bad_request"
}

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 target database

Request Body

Field	Type	Required	Description
id	string	No	Optional client-supplied record ID
name	string	No	Record name (default: "Untitled")
avatar	string | null	No	Avatar URL or null
fields	object	No	Map of custom field names to values (default: {})

cURL

curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/nb_5f8e7d6c5b4a39281706f5e4/databases/db_1a2b3c4d5e6f7890abcdef12/records" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Vendor",
    "avatar": null,
    "fields": {
      "status": "prospect",
      "tags": ["q1", "outbound"]
    }
  }'

SDK

const record = await client.notes.databases.create({
  notebookId: "nb_5f8e7d6c5b4a39281706f5e4",
  databaseId: "db_1a2b3c4d5e6f7890abcdef12",
  data: {
    name: "New Vendor",
    avatar: null,
    fields: {
      status: "prospect",
      tags: ["q1", "outbound"],
    },
  },
});

201

{
  "id": "rec_abcdef1234567890fedcba98",
  "name": "New Vendor",
  "avatar": null,
  "fields": {
    "status": "prospect",
    "tags": ["q1", "outbound"]
  },
  "createdAt": "2025-04-10T16:20:00.000Z",
  "updatedAt": "2025-04-10T16:20:00.000Z"
}

400

{
  "message": "Invalid request body.",
  "code": "bad_request",
  "details": [
    { "path": "name", "message": "Expected string" }
  ]
}

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
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 target database
recordId	path	string	Yes	ID of the record to update

Request Body

Field	Type	Required	Description
name	string	No	New record name
avatar	string | null	No	New avatar URL or null
fields	object	No	Map of field names to typed { type, value } objects to merge into the existing record

Each entry in fields must specify a type and a matching value. Supported type values are boolean, string, string_array, number, and text.

cURL

curl -X PATCH "https://api.hoody.com/api/v1/notes/notebooks/nb_5f8e7d6c5b4a39281706f5e4/databases/db_1a2b3c4d5e6f7890abcdef12/records/rec_a1b2c3d4e5f6789012345678" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp - Enterprise",
    "fields": {
      "status": { "type": "string", "value": "closed-won" },
      "priority": { "type": "number", "value": 1 }
    }
  }'

SDK

const record = await client.notes.databases.update({
  notebookId: "nb_5f8e7d6c5b4a39281706f5e4",
  databaseId: "db_1a2b3c4d5e6f7890abcdef12",
  recordId: "rec_a1b2c3d4e5f6789012345678",
  data: {
    name: "Acme Corp - Enterprise",
    fields: {
      status: { type: "string", value: "closed-won" },
      priority: { type: "number", value: 1 },
    },
  },
});

200

{
  "id": "rec_a1b2c3d4e5f6789012345678",
  "name": "Acme Corp - Enterprise",
  "avatar": "https://cdn.hoody.com/avatars/acme.png",
  "fields": {
    "status": { "type": "string", "value": "closed-won" },
    "priority": { "type": "number", "value": 1 },
    "owner": { "type": "string", "value": "Jane Cooper" }
  },
  "createdAt": "2025-01-15T10:32:00.000Z",
  "updatedAt": "2025-04-12T11:08:00.000Z"
}

400

{
  "message": "Invalid field type.",
  "code": "bad_request",
  "details": [
    { "path": "fields.priority", "message": "Type must be one of: boolean, string, string_array, number, text" }
  ]
}

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

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 target database
recordId	path	string	Yes	ID of the record to delete

cURL

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

SDK

const result = await client.notes.databases.delete({
  notebookId: "nb_5f8e7d6c5b4a39281706f5e4",
  databaseId: "db_1a2b3c4d5e6f7890abcdef12",
  recordId: "rec_a1b2c3d4e5f6789012345678",
});

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