Notes: Databases

The Notes Databases API lets you read, search, create, update, and delete individual records inside a database notebook node. Use these endpoints to enumerate pages of records with JSON-encoded filters and sorts, fetch a single record by ID, search records by name, create new records with typed field values, merge updates into an existing record, or permanently remove a record.

All requests target the Notes service running inside a container. The base URL is https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com, where {projectId} and {containerId} are 24-character hexadecimal identifiers and {server} is the cluster node label such as node-us.

Note

All identifiers referenced in this API (notebookId, databaseId, recordId) are 24-character hexadecimal strings. Replace the placeholder tokens with real IDs in your requests.

Records

List 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.

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 applied to records.
page	query	integer	No	Page number to retrieve. Default: 1.
count	query	integer	No	Number of records per page. Default: 50.
notebookId	path	string	Yes	Identifier of the parent notebook.
databaseId	path	string	Yes	Identifier of the database node.

This endpoint takes no request body.

Response

cURL

curl -X GET "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records?page=1&count=50" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.databases.listIterator('67e89abc123def456789abcd', '890abcdef12345678901cdef', { page: 1, count: 50 });

200

{
  "records": [
    {
      "id": "456789abcd67e89abc123def",
      "name": "Acme Corp",
      "avatar": null,
      "fields": {
        "status": { "type": "string", "value": "active" },
        "priority": { "type": "number", "value": 3 }
      }
    },
    {
      "id": "56789abcd67e89abc123def0",
      "name": "Globex Industries",
      "avatar": null,
      "fields": {
        "status": { "type": "string", "value": "pending" },
        "tags": { "type": "string_array", "value": ["q1", "review"] }
      }
    }
  ],
  "total": 124,
  "page": 1,
  "count": 50
}

400

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

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 the 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 the 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 the database ID using listNodes

Get a 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	Identifier of the parent notebook.
databaseId	path	string	Yes	Identifier of the database node.
recordId	path	string	Yes	Identifier of the record.

This endpoint takes no request body.

Response

cURL

curl -X GET "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/{recordId}" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.databases.get('67e89abc123def456789abcd', '890abcdef12345678901cdef', '456789abcd67e89abc123def');

200

{
  "id": "456789abcd67e89abc123def",
  "name": "Acme Corp",
  "avatar": null,
  "fields": {
    "status": { "type": "string", "value": "active" },
    "priority": { "type": "number", "value": 3 },
    "notes": { "type": "text", "value": "Key enterprise account." }
  }
}

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 the 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 the record ID using listRecords or searchRecords

Search records

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

Searches records in a database by name. Supports excluding specific record IDs from the result set.

Parameters

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

This endpoint takes no request body.

Response

cURL

curl -X GET "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/search?q=acme" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.databases.search('67e89abc123def456789abcd', '890abcdef12345678901cdef', { q: 'acme' });

200

{
  "records": [
    {
      "id": "456789abcd67e89abc123def",
      "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 JSON array of strings."
    }
  ]
}

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 the 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 the database ID using listNodes

Create a 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	Identifier of the parent notebook.
databaseId	path	string	Yes	Identifier of the database node.

Request Body

Field	Type	Required	Description
id	string	No	Optional client-supplied record ID.
name	string	No	Display name of the record. Default: "Untitled".
avatar	string | null	No	Optional avatar identifier or URL.
fields	object	No	Map of field IDs to typed field values. Default: {}.

{
  "name": "Vendor onboarding",
  "fields": {
    "status": { "type": "string", "value": "pending" },
    "priority": { "type": "number", "value": 2 },
    "tags": { "type": "string_array", "value": ["q1", "review"] }
  }
}

Response

cURL

curl -X POST "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vendor onboarding",
    "fields": {
      "status": { "type": "string", "value": "pending" },
      "priority": { "type": "number", "value": 2 },
      "tags": { "type": "string_array", "value": ["q1", "review"] }
    }
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.databases.create('67e89abc123def456789abcd', '890abcdef12345678901cdef', {
  name: 'Vendor onboarding',
  fields: {
    status: { type: 'string', value: 'pending' },
    priority: { type: 'number', value: 2 },
    tags: { type: 'string_array', value: ['q1', 'review'] },
  },
});

201

{
  "id": "abc456789abcd67e89abc12",
  "name": "Vendor onboarding",
  "avatar": null,
  "fields": {
    "status": { "type": "string", "value": "pending" },
    "priority": { "type": "number", "value": 2 },
    "tags": { "type": "string_array", "value": ["q1", "review"] }
  }
}

400

{
  "message": "Validation failed.",
  "code": "bad_request",
  "details": [
    { "path": "fields.priority.type", "message": "Unknown field type 'integer'." }
  ]
}

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 the 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 the 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 record

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

Updates a record name, avatar, or field values. Submitted fields are merged with the existing field map.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the parent notebook.
databaseId	path	string	Yes	Identifier of the database node.
recordId	path	string	Yes	Identifier of the record.

Request Body

Field	Type	Required	Description
name	string	No	New display name for the record.
avatar	string | null	No	New avatar identifier or URL.
fields	object	No	Map of field IDs to typed field values. Values are merged with existing fields.

{
  "name": "Vendor onboarding - in progress",
  "fields": {
    "status": { "type": "string", "value": "in_progress" }
  }
}

Response

cURL

curl -X PATCH "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/{recordId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vendor onboarding - in progress",
    "fields": {
      "status": { "type": "string", "value": "in_progress" }
    }
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.databases.update('67e89abc123def456789abcd', '890abcdef12345678901cdef', '456789abcd67e89abc123def', {
  name: 'Vendor onboarding - in progress',
  fields: {
    status: { type: 'string', value: 'in_progress' },
  },
});

200

{
  "id": "456789abcd67e89abc123def",
  "name": "Vendor onboarding - in progress",
  "avatar": null,
  "fields": {
    "status": { "type": "string", "value": "in_progress" },
    "priority": { "type": "number", "value": 2 }
  }
}

400

{
  "message": "Validation failed.",
  "code": "bad_request",
  "details": [
    { "path": "fields.status.type", "message": "Unknown field type 'enum'." }
  ]
}

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 the 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 the 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 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	Identifier of the parent notebook.
databaseId	path	string	Yes	Identifier of the database node.
recordId	path	string	Yes	Identifier of the record.

This endpoint takes no request body.

Response

cURL

curl -X DELETE "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/databases/{databaseId}/records/{recordId}" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.databases.delete('67e89abc123def456789abcd', '890abcdef12345678901cdef', '456789abcd67e89abc123def');

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 the 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