sources = client.context.list(
database="acme_corp",
type="knowledge",
page=1,
page_size=50,
filters={
"metadata": {"department": "legal"},
"source_fields": {"type": "slack"},
},
include_fields=["title", "type", "timestamp", "additional_metadata"],
)
const sources = await client.context.list({
database: "acme_corp",
type: "knowledge",
page: 1,
pageSize: 50,
filters: {
metadata: { department: "legal" },
source_fields: { type: "slack" },
},
includeFields: ["title", "type", "timestamp", "additional_metadata"],
});
curl -X POST 'https://api.hydradb.com/context/list' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"database": "acme_corp",
"type": "knowledge",
"page": 1,
"page_size": 50,
"filters": {
"metadata": { "department": "legal" },
"source_fields": { "type": "slack" }
},
"include_fields": ["title", "type", "timestamp", "additional_metadata"]
}'
{
"success": true,
"data": {
"success": true,
"message": "Sources retrieved successfully",
"sources": [
{
"id": "policy_main",
"database": "acme_corp",
"collection": "team_docs",
"title": "Compliance Policy",
"type": "pdf",
"timestamp": "2026-05-12T08:14:00Z",
"additional_metadata": { "author": "Compliance Team" }
}
],
"total": 318,
"pagination": {
"page": 1,
"page_size": 50,
"total": 318,
"total_pages": 7,
"has_next": true,
"has_previous": false
}
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": true,
"data": {
"success": true,
"user_memories": [
{
"memory_id": "mem_user_alex_tone",
"memory_content": "Prefers concise answers and dark mode.",
"inferred_content": "User prefers concise answers and dark mode."
}
],
"total": 1,
"pagination": {
"page": 1,
"page_size": 50,
"total": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": false,
"data": null,
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 4.8
}
}
Context
List Context
Browse over knowledge or memories with optional filters. Results are paginated.
POST
/
context
/
list
sources = client.context.list(
database="acme_corp",
type="knowledge",
page=1,
page_size=50,
filters={
"metadata": {"department": "legal"},
"source_fields": {"type": "slack"},
},
include_fields=["title", "type", "timestamp", "additional_metadata"],
)
const sources = await client.context.list({
database: "acme_corp",
type: "knowledge",
page: 1,
pageSize: 50,
filters: {
metadata: { department: "legal" },
source_fields: { type: "slack" },
},
includeFields: ["title", "type", "timestamp", "additional_metadata"],
});
curl -X POST 'https://api.hydradb.com/context/list' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"database": "acme_corp",
"type": "knowledge",
"page": 1,
"page_size": 50,
"filters": {
"metadata": { "department": "legal" },
"source_fields": { "type": "slack" }
},
"include_fields": ["title", "type", "timestamp", "additional_metadata"]
}'
{
"success": true,
"data": {
"success": true,
"message": "Sources retrieved successfully",
"sources": [
{
"id": "policy_main",
"database": "acme_corp",
"collection": "team_docs",
"title": "Compliance Policy",
"type": "pdf",
"timestamp": "2026-05-12T08:14:00Z",
"additional_metadata": { "author": "Compliance Team" }
}
],
"total": 318,
"pagination": {
"page": 1,
"page_size": 50,
"total": 318,
"total_pages": 7,
"has_next": true,
"has_previous": false
}
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": true,
"data": {
"success": true,
"user_memories": [
{
"memory_id": "mem_user_alex_tone",
"memory_content": "Prefers concise answers and dark mode.",
"inferred_content": "User prefers concise answers and dark mode."
}
],
"total": 1,
"pagination": {
"page": 1,
"page_size": 50,
"total": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": false,
"data": null,
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 4.8
}
}
Specify the category using the
When
type parameter to filter and view ingested knowledge or user memories within a database or collection:
type=knowledge(default) - knowledge sources (documents, app sources).type=memory- user memories.
sources = client.context.list(
database="acme_corp",
type="knowledge",
page=1,
page_size=50,
filters={
"metadata": {"department": "legal"},
"source_fields": {"type": "slack"},
},
include_fields=["title", "type", "timestamp", "additional_metadata"],
)
const sources = await client.context.list({
database: "acme_corp",
type: "knowledge",
page: 1,
pageSize: 50,
filters: {
metadata: { department: "legal" },
source_fields: { type: "slack" },
},
includeFields: ["title", "type", "timestamp", "additional_metadata"],
});
curl -X POST 'https://api.hydradb.com/context/list' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"database": "acme_corp",
"type": "knowledge",
"page": 1,
"page_size": 50,
"filters": {
"metadata": { "department": "legal" },
"source_fields": { "type": "slack" }
},
"include_fields": ["title", "type", "timestamp", "additional_metadata"]
}'
Request body
| Name | Description |
|---|---|
Owning database. Formerly tenant_id; the tenant_id alias is still accepted (deprecated). | |
Collection scope. If omitted, the default collection is used. Formerly sub_tenant_id; the sub_tenant_id alias is still accepted (deprecated). (default=null) | |
Bucket to list. (default="knowledge") | |
When provided and non-empty, only items with these IDs are returned (pagination + filters still apply). (default=null) | |
Page number (1-indexed). (default=1) | |
Items per page, from 1 to 100. (default=50) | |
Structured exact-match filters. See Filters. (default=null) | |
Field projection. Only the listed fields plus id, database, collection are populated. Only applies to type=knowledge. (default=null - all fields) |
1. Filters
filtersis a structured object with three optional categories. Filters are exact-match constraints i.e. filtered values are matched against stored values as exact values. There are no range, contains, or OR operators on this endpoint; run multiple calls and merge client-side for OR behavior.- AND/OR: All filter pairs combine with a logical AND. To express OR semantics, run multiple calls and union them client-side.
ids+ filters: Whenidsis non-empty, only those IDs are considered, but otherfiltersstill apply on top - useful for “show me items 1, 2, 3 that also belong to department=legal”.
{
"filters": {
"metadata": { "department": "Finance", "region": "US" },
"additional_metadata": { "author": "Alice Smith" },
"source_fields": { "type": "slack", "title": "standup notes" }
}
}
| Category | Matched against | Notes |
|---|---|---|
Context item’s schema-aligned metadata payload | Use for database metadata fields. tenant_metadata is accepted as a legacy alias. Keys must be declared in the database’s database_metadata_schema with enable_match: true; undeclared keys are silently ignored. | |
Context item’s additional_metadata payload | Free-form per-document JSON. No schema declaration required. document_metadata is accepted as a legacy alias. | |
Built-in source fields (type, title, description, url, timestamp) | Use for app-source categories or quick title lookups. |
2. Including Fields for convenient data objects
When you don’t need every field on every row, passinclude_fields to keep response payloads small. Only the listed fields are populated; omitted fields should be treated as unavailable in that response. id, database, and collection are always returned.
Allowed values are title, type, description, note, timestamp, metadata, additional_metadata, and relations. Omit or pass null to return everything.
Projectable vs. fetchable fields.
content, url, and attachments are not valid include_fields values - they are stripped from list responses, and requesting one returns 400. Fetch them per-source via Inspect Context.include_fields only applies to type=knowledge. It is ignored for type=memory.
{
"success": true,
"data": {
"success": true,
"message": "Sources retrieved successfully",
"sources": [
{
"id": "policy_main",
"database": "acme_corp",
"collection": "team_docs",
"title": "Compliance Policy",
"type": "pdf",
"timestamp": "2026-05-12T08:14:00Z",
"additional_metadata": { "author": "Compliance Team" }
}
],
"total": 318,
"pagination": {
"page": 1,
"page_size": 50,
"total": 318,
"total_pages": 7,
"has_next": true,
"has_previous": false
}
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": true,
"data": {
"success": true,
"user_memories": [
{
"memory_id": "mem_user_alex_tone",
"memory_content": "Prefers concise answers and dark mode.",
"inferred_content": "User prefers concise answers and dark mode."
}
],
"total": 1,
"pagination": {
"page": 1,
"page_size": 50,
"total": 1,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
},
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 12.3
}
}
{
"success": false,
"data": null,
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"latency_ms": 4.8
}
}
type=memory, data is a ListUserMemoriesResponse instead - same idea but with a data.user_memories[] array of memory items.
Use the canonical v2 names. Prefer
filters.metadata and filters.additional_metadata. Legacy filters.tenant_metadata and filters.document_metadata are accepted for back-compat, with canonical keys winning on conflicts.Related Resources
- Fetch content: Fetch Content
- Retrieve: Query
- Delete: Delete Context
Authorizations
API key sent as a Bearer token: "Bearer prefix.secret"
Body
application/json
List request
ACL: see ListContentRequest.ACL (PRO-1684 document ACLs).
Collection scope. Defaults to the default collection when omitted. Formerly sub_tenant_id; the sub_tenant_id alias is still accepted (deprecated).
Example:
"team_docs"
Database/Collection are the canonical v2 names; TenantID/SubTenantID are their deprecated aliases (reconciled here in UnmarshalJSON and centrally by the TenantAliases middleware).
Example:
"acme_corp"
Show child attributes
Show child attributes
Example:
{
"additional_metadata": { "author": "ada" },
"metadata": { "department": "finance" }
}
GroupThreads (type=knowledge only) folds each ticket's/thread root's
discussion (comment and message app sources carrying an app_parent_id)
under the parent row as comments, newest first, instead of listing them
as separate top-level rows. Off by default: the flat shape is the
existing contract.
Example:
true
When provided, only items with these IDs are returned. Pagination and filters still apply.
Example:
["HydraDoc1234", "HydraDoc4567"]
Field projection — only the listed fields plus id, database, collection are returned. Only applies to type=knowledge.
Example:
["id", "title", "type"]
Current page number (1-indexed).
Example:
1
Number of items per page.
Example:
50
deprecated: use collection
Example:
"sub_tenant_4567"
deprecated: use database
Example:
"tenant_1234"
Bucket to list: knowledge (default) or memory.
Available options:
knowledge, memory Example:
"knowledge"
Response
OK
Show child attributes
Show child attributes
Example:
{
"message": "Success",
"pagination": {
"has_next": true,
"has_previous": false,
"page": 1,
"page_size": 50,
"total": 128,
"total_pages": 3
},
"sources": [
{
"additional_metadata": { "author": "ada", "doc_version": 3 },
"app_external_id": "C0123456789",
"app_kind": "slack",
"app_provider": "slack",
"collection": "team_docs",
"comments_truncated": true,
"database": "acme_corp",
"description": "Internal overview of the Project Phoenix rollout.",
"id": "HydraDoc1234",
"metadata": { "department": "finance", "priority": 7 },
"note": "Superseded by the Q3 rollout plan.",
"sub_tenant_id": "sub_tenant_4567",
"tenant_id": "tenant_1234",
"timestamp": "2026-07-02T10:00:00Z",
"title": "Project Phoenix Overview",
"type": "knowledge"
}
],
"success": true,
"total": 128,
"user_memories": [
{
"additional_metadata": { "author": "ada", "doc_version": 3 },
"app_external_id": "C0123456789",
"app_kind": "slack",
"app_provider": "slack",
"collection": "team_docs",
"comments_truncated": true,
"database": "acme_corp",
"description": "Internal overview of the Project Phoenix rollout.",
"memory_id": "memory_1234",
"metadata": { "department": "finance", "priority": 7 },
"note": "Superseded by the Q3 rollout plan.",
"sub_tenant_id": "sub_tenant_4567",
"tenant_id": "tenant_1234",
"timestamp": "2026-07-02T10:00:00Z",
"title": "Project Phoenix Overview",
"type": "knowledge"
}
]
}
Error message, empty string on success.
Show child attributes
Show child attributes
Example:
{
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
}
Show child attributes
Show child attributes
Example:
{
"collection": "team_docs",
"database": "acme_corp",
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"source_type": "file",
"sub_tenant_id": "sub_tenant_4567",
"tenant_id": "tenant_1234"
}
Whether the request succeeded.
Example:
true
Was this page helpful?