List Data

List Content

import requests

url = "https://api.hydradb.com/list/data"

payload = {
    "tenant_id": "tenant_1234",
    "sub_tenant_id": "sub_tenant_4567",
    "kind": "knowledge",
    "source_ids": ["<string>"],
    "page": 1,
    "page_size": 1,
    "filters": {
        "tenant_metadata": {
            "compliance_tag": "GDPR",
            "department": "Finance"
        },
        "document_metadata": {
            "author": "Alice Smith",
            "year": 2023
        },
        "source_fields": {
            "title": "standup notes",
            "type": "slack"
        }
    },
    "include_fields": ["title", "type", "url", "timestamp"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tenant_id: 'tenant_1234',
    sub_tenant_id: 'sub_tenant_4567',
    kind: 'knowledge',
    source_ids: ['<string>'],
    page: 1,
    page_size: 1,
    filters: {
      tenant_metadata: {compliance_tag: 'GDPR', department: 'Finance'},
      document_metadata: {author: 'Alice Smith', year: 2023},
      source_fields: {title: 'standup notes', type: 'slack'}
    },
    include_fields: ['title', 'type', 'url', 'timestamp']
  })
};

fetch('https://api.hydradb.com/list/data', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.hydradb.com/list/data \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "kind": "knowledge",
  "source_ids": [
    "<string>"
  ],
  "page": 1,
  "page_size": 1,
  "filters": {
    "tenant_metadata": {
      "compliance_tag": "GDPR",
      "department": "Finance"
    },
    "document_metadata": {
      "author": "Alice Smith",
      "year": 2023
    },
    "source_fields": {
      "title": "standup notes",
      "type": "slack"
    }
  },
  "include_fields": [
    "title",
    "type",
    "url",
    "timestamp"
  ]
}
'

{
  "total": 1,
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1,
    "total_pages": 1,
    "has_next": true,
    "has_previous": true
  },
  "success": true,
  "message": "Sources retrieved successfully",
  "sources": [
    {
      "id": "HydraDoc1234",
      "tenant_id": "tenant_1234",
      "sub_tenant_id": "sub_tenant_4567",
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "note": "<note>",
      "url": "<url>",
      "timestamp": "<timestamp>",
      "content": {
        "text": "<text>",
        "html_base64": "<html_base64>",
        "csv_base64": "<csv_base64>",
        "markdown": "<markdown>",
        "files": [
          {}
        ],
        "layout": []
      },
      "tenant_metadata": {},
      "document_metadata": {},
      "meta": {},
      "attachments": [
        {
          "id": "HydraDoc1234",
          "url": "<url>",
          "title": "<title>",
          "content_type": "<content_type>",
          "content_url": "<content_url>",
          "misc": {},
          "content": {
            "text": "<text>",
            "html_base64": "<html_base64>",
            "csv_base64": "<csv_base64>",
            "markdown": "<markdown>",
            "files": [
              {}
            ],
            "layout": []
          }
        }
      ],
      "relations": {
        "hydradb_source_ids": [
          "<string>"
        ],
        "properties": {}
      }
    }
  ]
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

POST

list

data

List Content

import requests

url = "https://api.hydradb.com/list/data"

payload = {
    "tenant_id": "tenant_1234",
    "sub_tenant_id": "sub_tenant_4567",
    "kind": "knowledge",
    "source_ids": ["<string>"],
    "page": 1,
    "page_size": 1,
    "filters": {
        "tenant_metadata": {
            "compliance_tag": "GDPR",
            "department": "Finance"
        },
        "document_metadata": {
            "author": "Alice Smith",
            "year": 2023
        },
        "source_fields": {
            "title": "standup notes",
            "type": "slack"
        }
    },
    "include_fields": ["title", "type", "url", "timestamp"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tenant_id: 'tenant_1234',
    sub_tenant_id: 'sub_tenant_4567',
    kind: 'knowledge',
    source_ids: ['<string>'],
    page: 1,
    page_size: 1,
    filters: {
      tenant_metadata: {compliance_tag: 'GDPR', department: 'Finance'},
      document_metadata: {author: 'Alice Smith', year: 2023},
      source_fields: {title: 'standup notes', type: 'slack'}
    },
    include_fields: ['title', 'type', 'url', 'timestamp']
  })
};

fetch('https://api.hydradb.com/list/data', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.hydradb.com/list/data \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "kind": "knowledge",
  "source_ids": [
    "<string>"
  ],
  "page": 1,
  "page_size": 1,
  "filters": {
    "tenant_metadata": {
      "compliance_tag": "GDPR",
      "department": "Finance"
    },
    "document_metadata": {
      "author": "Alice Smith",
      "year": 2023
    },
    "source_fields": {
      "title": "standup notes",
      "type": "slack"
    }
  },
  "include_fields": [
    "title",
    "type",
    "url",
    "timestamp"
  ]
}
'

{
  "total": 1,
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1,
    "total_pages": 1,
    "has_next": true,
    "has_previous": true
  },
  "success": true,
  "message": "Sources retrieved successfully",
  "sources": [
    {
      "id": "HydraDoc1234",
      "tenant_id": "tenant_1234",
      "sub_tenant_id": "sub_tenant_4567",
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "note": "<note>",
      "url": "<url>",
      "timestamp": "<timestamp>",
      "content": {
        "text": "<text>",
        "html_base64": "<html_base64>",
        "csv_base64": "<csv_base64>",
        "markdown": "<markdown>",
        "files": [
          {}
        ],
        "layout": []
      },
      "tenant_metadata": {},
      "document_metadata": {},
      "meta": {},
      "attachments": [
        {
          "id": "HydraDoc1234",
          "url": "<url>",
          "title": "<title>",
          "content_type": "<content_type>",
          "content_url": "<content_url>",
          "misc": {},
          "content": {
            "text": "<text>",
            "html_base64": "<html_base64>",
            "csv_base64": "<csv_base64>",
            "markdown": "<markdown>",
            "files": [
              {}
            ],
            "layout": []
          }
        }
      ],
      "relations": {
        "hydradb_source_ids": [
          "<string>"
        ],
        "properties": {}
      }
    }
  ]
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": true,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

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

curl -X POST 'https://api.hydradb.com/list/data' \
  -H "Authorization: Bearer <your_api_key>" \
  -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"]
  }'

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

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

{
  "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)

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

{
  "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.

Inspect a single source: Fetch content – retrieve original file or presigned URL
Inspect graph relationships: Graph relations by source ID – see entity links for a source
Remove items: Delete knowledge · Delete memory

Errors

Common codes: 400 INVALID_PARAMETERS, 404 TENANT_NOT_FOUND, 422 VALIDATION_ERROR. See Error Responses for the full list. Read more: Essentials → Metadata

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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

tenant_id

string

required

Tenant ID

Example:

"tenant_1234"

sub_tenant_id

string | null

Sub-tenant ID

Example:

"sub_tenant_4567"

kind

enum<string>

default:knowledge

Whether to list normal sources or user memories.

Available options:

knowledge,

memories

source_ids

string[] | null

Optional list of IDs to fetch (max 100). If omitted, returns all.

Maximum array length: 100

page

integer

default:1

Page number to retrieve (1-indexed). Defaults to 1.

Required range: x >= 1

Example:

1

page_size

integer

default:50

Number of items per page (1-100). Defaults to 50.

Required range: 1 <= x <= 100

Example:

1

filters

ContentFilter · object | null

Optional filters. Provide key-value pairs to match against tenant_metadata, document_metadata, and/or source-level fields (title, type, description, url, timestamp).

Show child attributes

include_fields

string[] | null

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.

Example:

["title", "type", "url", "timestamp"]

Response

Successful Response

SourceListResponse
ListUserMemoriesResponse

total

integer

required

Total number of sources matching the query.

Example:

1

pagination

PaginationMeta · object

required

Pagination metadata for navigating through results.

Show child attributes

success

boolean

default:true

Example:

true

message

string

default:Sources retrieved successfully

sources

SourceModel · object[]

Show child attributes

API Documentation

Tenants

Knowledge & Memories

Recall

Managing Data

When to use it

Endpoint

Example

Request parameters

Filters

Field projection (knowledge only)

Response

`kind: "knowledge"` (default)

`kind: "memories"`

Behavior notes

Errors

Authorizations

Body

Response

​When to use it

​Endpoint

​Example

​Request parameters

​Filters

​Field projection (knowledge only)

​Response

​kind: "knowledge" (default)

​kind: "memories"

​Pagination

​Behavior notes

​Related endpoints

​Errors

Authorizations

Body

Response

When to use it

Endpoint

Example

Request parameters

Filters

Field projection (knowledge only)

Response

`kind: "knowledge"` (default)

`kind: "memories"`

Pagination

Behavior notes

Related endpoints

Errors