> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Data
> Paginated listing of stored knowledge or memories with optional filters.
## When to use it
* **Admin dashboards** – browse what's been ingested into a tenant
* **Audit and exports** – paginate through all sources for reporting
* **Debugging** – verify metadata was attached correctly at ingestion
* **Bulk operations** – iterate over sources for cleanup or reprocessing
## Endpoint
* **Auth:** Bearer token
* **Idempotency:** Read-only
* **Async:** No
## Example
```bash cURL theme={"dark"}
curl -X POST 'https://api.hydradb.com/list/data' \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"tenant_id": "my_first_tenant",
"kind": "knowledge",
"page": 1,
"page_size": 25,
"filters": {
"tenant_metadata": { "category": "engineering" },
"additional_metadata": { "author": "Alice Smith" }
},
"include_fields": ["title", "type", "url", "timestamp"]
}'
```
```typescript TypeScript SDK theme={"dark"}
const result = await client.fetch.listData({
tenant_id: "my_first_tenant",
kind: "knowledge",
page: 1,
page_size: 25,
filters: {
tenant_metadata: { category: "engineering" },
additional_metadata: { author: "Alice Smith" }
},
include_fields: ["title", "type", "url", "timestamp"]
});
```
```python Python SDK theme={"dark"}
result = client.fetch.list_data(
tenant_id="my_first_tenant",
kind="knowledge",
page=1,
page_size=25,
filters={
"tenant_metadata": {"category": "engineering"},
"additional_metadata": {"author": "Alice Smith"},
},
include_fields=["title", "type", "url", "timestamp"],
)
```
## Request parameters
| Name | Type | Required | Default | Description |
| ---------------- | --------- | -------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `tenant_id` | string | Yes | – | The tenant to list from. |
| `sub_tenant_id` | string | No | default | Sub-tenant scope. |
| `kind` | enum | No | `knowledge` | `knowledge` to list sources, `memories` to list user memories. |
| `page` | integer | No | `1` | Page number (1-indexed). |
| `page_size` | integer | No | `50` | Items per page (1–100). |
| `source_ids` | string\[] | No | – | If non-empty, only items with these IDs are returned (max 100). Filters and pagination still apply. |
| `filters` | object | No | – | Optional filters. See [Filters](#filters). |
| `include_fields` | string\[] | No | – | Project specific source fields to reduce payload size. Knowledge only – ignored for memories. |
## Filters
Filters narrow results using **AND logic** – every key-value pair must match.
| Filter category | Key (canonical) | Aliases also accepted | Targets |
| ----------------------- | --------------------- | --------------------- | ----------------------------------------------------- |
| Tenant-level metadata | `tenant_metadata` | `metadata` | Fields defined in `tenant_metadata_schema` |
| Document-level metadata | `additional_metadata` | `document_metadata` | Fields you sent as `additional_metadata` at ingestion |
| Source-level fields | `source_fields` | - | Top-level source fields |
Canonical filter keys match the ingestion field names. `metadata` / `document_metadata` are accepted as legacy aliases (back-compat with earlier API versions) - both names route to the same filter.
**Allowed `source_fields` keys:** `description`, `timestamp`, `title`, `type`, `url`.
```json theme={"dark"}
{
"filters": {
"tenant_metadata": { "department": "Finance" },
"additional_metadata": { "author": "Alice Smith" },
"source_fields": { "type": "slack", "title": "standup notes" }
}
}
```
## Field projection (knowledge only)
For large knowledge bases, response payloads can grow significantly. Use `include_fields` to return only the fields you need:
| Allowed values |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| `attachments`, `content`, `description`, `additional_metadata`, `note`, `relations`, `metadata`, `timestamp`, `title`, `type`, `url` |
When `include_fields` is set, only the listed fields plus `id`, `tenant_id`, and `sub_tenant_id` are populated. Other fields return their default/empty values.
## Response
The response shape depends on `kind`.
### `kind: "knowledge"` (default)
```json theme={"dark"}
{
"sources": [
{
"id": "doc_12345",
"title": "Q4 Pricing Strategy",
"type": "file",
"url": "https://...",
"timestamp": "2025-09-15T10:00:00Z",
"metadata": { "category": "engineering" },
"additional_metadata": { "author": "Alice Smith" }
}
],
"pagination": {
"page": 1,
"page_size": 25,
"total": 143,
"total_pages": 6,
"has_next": true,
"has_previous": false
}
}
```
### `kind: "memories"`
```json theme={"dark"}
{
"success": true,
"user_memories": [
{
"memory_id": "1d50e5cd7c196a2bbcc1a59b037b3a44",
"memory_content": "User prefers detailed technical explanations and dark mode"
}
],
"total": 12,
"pagination": {
"page": 1,
"page_size": 25,
"total": 12,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}
```
## Pagination
The `pagination` object on every response includes:
| Field | Description |
| -------------- | ------------------------------- |
| `page` | Current page (1-indexed). |
| `page_size` | Items per page. |
| `total` | Total items matching the query. |
| `total_pages` | Total pages available. |
| `has_next` | Whether a next page exists. |
| `has_previous` | Whether a previous page exists. |
## Behavior notes
**Filter logic is AND.** Every key in `metadata`, `additional_metadata`, and `source_fields` must match for an item to be included.
**`source_ids` does not bypass filters.** When `source_ids` is provided, returned items are restricted to those IDs **and** must still match any active filters.
## Related endpoints
* **Inspect a single source:** [Fetch content](/api-reference/endpoint/fetch-content) – retrieve original file or presigned URL
* **Inspect graph relationships:** [Graph relations by source ID](/api-reference/endpoint/graph-relations) – see entity links for a source
* **Remove items:** [Delete knowledge](/api-reference/endpoint/delete-knowledge) · [Delete memory](/api-reference/endpoint/delete-memory)
## Errors
Common codes: `400 INVALID_PARAMETERS`, `404 TENANT_NOT_FOUND`, `422 VALIDATION_ERROR`. See [Error Responses](/api-reference/error-responses) for the full list.
Read more: [Essentials → Metadata](/essentials/metadata)
## OpenAPI
````yaml POST /list/data
openapi: 3.1.0
info:
title: HydraDB API
description: REST APIs for the HydraDB retrieval engine
version: 0.0.1
servers:
- url: https://api.hydradb.com
description: Production
x-fern-server-name: hydradb-prod
security: []
paths:
/list/data:
post:
tags:
- list
summary: List Content
operationId: list_content_list_data_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListContentRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SourceListResponse'
- $ref: '#/components/schemas/ListUserMemoriesResponse'
title: Response List Content List Data Post
'400':
description: Bad Request - Invalid input parameters
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'401':
description: Unauthorized - Authentication required
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'403':
description: Forbidden - Access denied
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'404':
description: Not Found - Resource does not exist
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'422':
description: Unprocessable Entity - Validation failed
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: >-
#/components/schemas/cortex__models__response__commons__ActualErrorResponse
security:
- HTTPBearer: []
components:
schemas:
ListContentRequest:
properties:
tenant_id:
type: string
title: Tenant Id
description: Tenant ID
example: tenant_1234
sub_tenant_id:
anyOf:
- type: string
- type: 'null'
title: Sub Tenant Id
description: Sub-tenant ID
example: sub_tenant_4567
kind:
$ref: '#/components/schemas/ListContentKind'
description: Whether to list normal sources or user memories.
default: knowledge
source_ids:
anyOf:
- items:
type: string
type: array
maxItems: 100
- type: 'null'
title: Source Ids
description: Optional list of IDs to fetch (max 100). If omitted, returns all.
page:
type: integer
minimum: 1
title: Page
description: Page number to retrieve (1-indexed). Defaults to 1.
default: 1
example: 1
page_size:
type: integer
maximum: 100
minimum: 1
title: Page Size
description: Number of items per page (1-100). Defaults to 50.
default: 50
example: 1
filters:
anyOf:
- $ref: '#/components/schemas/ContentFilter'
- type: 'null'
description: >-
Optional filters. Provide key-value pairs to match against
tenant_metadata, document_metadata, and/or source-level fields
(title, type, description, url, timestamp).
include_fields:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Include Fields
description: >-
Optional list of source fields to include in the response. When
provided, only the specified fields (plus id, tenant_id,
sub_tenant_id which are always returned) will be populated; all
other fields will have their default/empty values. This reduces
payload size and improves performance. Allowed values: attachments,
content, description, document_metadata, note, relations,
tenant_metadata, timestamp, title, type, url. Omit or pass null to
return all fields. Only applies to kind=knowledge; ignored for
kind=memories.
examples:
- - title
- type
- url
- timestamp
type: object
required:
- tenant_id
title: ListContentRequest
description: |-
Unified request model for listing either sources or user memories.
Supports **pagination** (page / page_size) and optional **filters**
on tenant_metadata and document_metadata.
If `source_ids` is provided and non-empty, only those IDs are returned
(pagination and filters still apply).
SourceListResponse:
properties:
success:
type: boolean
title: Success
default: true
example: true
message:
type: string
title: Message
default: Sources retrieved successfully
sources:
items:
$ref: '#/components/schemas/SourceModel'
type: array
title: Sources
total:
type: integer
title: Total
description: Total number of sources matching the query.
example: 1
pagination:
$ref: '#/components/schemas/PaginationMeta'
description: Pagination metadata for navigating through results.
type: object
required:
- total
- pagination
title: SourceListResponse
ListUserMemoriesResponse:
properties:
success:
type: boolean
title: Success
description: Indicates whether the memory listing operation was successful
default: true
example: true
user_memories:
items:
$ref: '#/components/schemas/UserMemory'
type: array
title: User Memories
description: Array of user memories for the current page
example:
- memory_id: memory_1234
memory_content: >-
I prefer detailed technical explanations and works in the
Pacific timezone
- memory_id: memory_4567
memory_content: I prefer dark mode
total:
type: integer
title: Total
description: Total number of user memories matching the query
default: 0
example: 1
pagination:
$ref: '#/components/schemas/PaginationMeta'
description: Pagination metadata for navigating through results.
type: object
required:
- pagination
title: ListUserMemoriesResponse
description: Response model for listing all user memories.
cortex__models__response__commons__ActualErrorResponse:
properties:
detail:
$ref: >-
#/components/schemas/cortex__models__response__commons__ErrorResponse
type: object
required:
- detail
title: ActualErrorResponse
ListContentKind:
type: string
enum:
- knowledge
- memories
title: ListContentKind
ContentFilter:
properties:
tenant_metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Tenant Metadata
description: >-
Key-value pairs matched against source.tenant_metadata. All provided
pairs must match (AND logic).
examples:
- compliance_tag: GDPR
department: Finance
document_metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Document Metadata
description: >-
Key-value pairs matched against source.document_metadata. All
provided pairs must match (AND logic).
examples:
- author: Alice Smith
year: 2023
source_fields:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Source Fields
description: >-
Key-value pairs matched against top-level source fields that you
supply during ingestion. Allowed keys: description, timestamp,
title, type, url. All provided pairs must match (AND logic).
examples:
- title: standup notes
type: slack
type: object
title: ContentFilter
description: |-
Optional filters for narrowing list results.
All filter categories use **AND** logic — every provided key-value pair
must match for a document to be included.
Examples
--------
```json
{
"tenant_metadata": {"department": "Finance", "region": "US"},
"document_metadata": {"author": "Alice Smith"},
"source_fields": {"type": "slack", "title": "standup notes"}
}
```
SourceModel:
properties:
id:
type: string
title: Id
description: >-
Stable, unique identifier for the source. If omitted, one may be
generated upstream.
example: HydraDoc1234
tenant_id:
type: string
title: Tenant Id
description: Unique identifier for the tenant/organization
example: tenant_1234
sub_tenant_id:
type: string
title: Sub Tenant Id
description: >-
Optional sub-tenant identifier used to organize data within a
tenant. If omitted, the default sub-tenant created during tenant
setup will be used.
example: sub_tenant_4567
title:
type: string
title: Title
description: Short human-readable title for the source.
default: ''
example:
type:
type: string
title: Type
description: High-level category of the source (e.g., document, email, ticket).
default: ''
example: <type>
description:
type: string
title: Description
description: Optional long-form description providing additional context.
default: ''
example: <description>
note:
type: string
title: Note
description: Free-form notes for internal use or ingestion hints.
default: ''
example: <note>
url:
type: string
title: Url
description: Canonical URL or reference link associated with the source.
default: ''
example: <url>
timestamp:
type: string
title: Timestamp
description: Creation or last-updated timestamp of the source in ISO-8601 format.
default: ''
example: <timestamp>
content:
$ref: '#/components/schemas/ContentModel'
description: Primary content payload used for indexing and retrieval.
tenant_metadata:
additionalProperties: true
type: object
title: Tenant Metadata
description: >+
JSON string containing tenant-level document metadata (e.g.,
department, compliance_tag)
Example: > "{"department":"Finance","compliance_tag":"GDPR"}"
document_metadata:
additionalProperties: true
type: object
title: Document Metadata
description: >+
JSON string containing document-specific metadata (e.g., title,
author, file_id). If file_id is not provided, the system will
generate an ID automatically.
Example: > "{"title":"Q1 Report.pdf","author":"Alice
Smith","file_id":"custom_file_123"}"
meta:
additionalProperties: true
type: object
title: Meta
description: >-
System-provided attributes (e.g., app_name, local file size) not
intended for search filtering.
attachments:
items:
$ref: '#/components/schemas/AttachmentModel'
type: array
title: Attachments
description: >-
Attachments related to the source such as images, PDFs, or
supplemental files.
relations:
anyOf:
- $ref: '#/components/schemas/ForcefulRelationsPayload'
- type: 'null'
description: >-
Forcefully connect 2 sources based on HydraDB source IDs or common
properties.
type: object
required:
- id
- tenant_id
- sub_tenant_id
title: SourceModel
PaginationMeta:
properties:
page:
type: integer
title: Page
description: Current page number (1-indexed).
example: 1
page_size:
type: integer
title: Page Size
description: Number of items returned per page.
example: 1
total:
type: integer
title: Total
description: Total number of items matching the query.
example: 1
total_pages:
type: integer
title: Total Pages
description: Total number of pages available.
example: 1
has_next:
type: boolean
title: Has Next
description: Whether a next page exists.
example: true
has_previous:
type: boolean
title: Has Previous
description: Whether a previous page exists.
example: true
type: object
required:
- page
- page_size
- total
- total_pages
- has_next
- has_previous
title: PaginationMeta
description: Pagination metadata returned with every paginated response.
UserMemory:
properties:
memory_id:
type: string
title: Memory Id
description: Unique identifier for the user memory
examples:
- HydraUserMemory1234...
example: memory_1234
memory_content:
type: string
title: Memory Content
description: The actual memory content text that was stored
examples:
- User prefers dark mode interface and uses keyboard shortcuts
example: <memory_content>
type: object
required:
- memory_id
- memory_content
title: UserMemory
description: Represents a user memory stored in the system.
cortex__models__response__commons__ErrorResponse:
properties:
success:
type: boolean
title: Success
default: false
example: true
message:
type: string
title: Message
default: Error occurred
error_code:
anyOf:
- type: string
- type: 'null'
title: Error Code
type: object
title: ErrorResponse
ContentModel:
properties:
text:
type: string
title: Text
description: Plain text content extracted or provided for indexing.
default: ''
example: <text>
html_base64:
type: string
title: Html Base64
description: Base64-encoded HTML content preserving structure and formatting.
default: ''
example: <html_base64>
csv_base64:
type: string
title: Csv Base64
description: Base64-encoded CSV data for tabular content ingestion.
default: ''
example: <csv_base64>
markdown:
type: string
title: Markdown
description: Raw Markdown content to be indexed as rich text.
default: ''
example: <markdown>
files:
items:
additionalProperties: true
type: object
type: array
title: Files
description: >-
List of file descriptors associated with the source (e.g.,
filenames, sizes).
layout:
items:
additionalProperties: true
type: object
type: array
title: Layout
description: >-
Optional layout metadata such as sections or blocks to guide
chunking.
example: []
type: object
title: ContentModel
AttachmentModel:
properties:
id:
type: string
title: Id
description: Unique identifier for the attachment.
default: ''
example: HydraDoc1234
url:
type: string
title: Url
description: Public or internal URL referencing the attachment resource.
default: ''
example: <url>
title:
type: string
title: Title
description: Human-readable title or filename of the attachment.
default: ''
example: <title>
content_type:
type: string
title: Content Type
description: MIME type of the attachment (e.g., application/pdf).
default: ''
example: <content_type>
content_url:
type: string
title: Content Url
description: >-
Direct URL for content retrieval when different from the reference
URL.
default: ''
example: <content_url>
misc:
additionalProperties: true
type: object
title: Misc
description: Additional attachment attributes defined by the tenant (free-form).
content:
$ref: '#/components/schemas/ContentModel'
description: Structured content payload for the attachment when available.
type: object
title: AttachmentModel
ForcefulRelationsPayload:
properties:
hydradb_source_ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: HydraDB Source Ids
description: HydraDB source IDs to forcefully relate to the uploaded source.
properties:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Properties
description: Optional properties to attach to the forceful relation.
type: object
title: ForcefulRelationsPayload
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````