# Notes: Databases

**Page:** api/notes/databases

[Download Raw Markdown](./api/notes/databases.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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



```bash
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'
```


```ts
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,
});
```


```json
{
  "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
}
```


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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 |



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


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


```json
{
  "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." }
  }
}
```


```json
{
  "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 |


```json
{
  "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 |



```bash
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"]'
```


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


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


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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: `{}` |



```bash
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"] }
    }
  }'
```


```ts
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"] },
    },
  },
});
```


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


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


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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 |



```bash
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 }
    }
  }'
```


```ts
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 },
    },
  },
});
```


```json
{
  "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" }
  }
}
```


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


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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 |




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 |



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


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


```json
{
  "success": true
}
```


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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 |




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