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" },
sourceFields: { 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": "Successfully fetched sources",
"sources": [
{
"id": "policy_main",
"database": "acme_corp",
"collection": "team_docs",
"tenant_id": "acme_corp",
"sub_tenant_id": "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,
"message": "Successfully fetched sources",
"user_memories": [
{
"memory_id": "mem_user_alex_tone",
"database": "acme_corp",
"collection": "team_docs",
"tenant_id": "acme_corp",
"sub_tenant_id": "team_docs",
"title": "Tone preference",
"type": "memory",
"metadata": { "user_id": "alex" }
}
],
"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
Page through knowledge sources or memories, with optional filters.
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" },
sourceFields: { 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": "Successfully fetched sources",
"sources": [
{
"id": "policy_main",
"database": "acme_corp",
"collection": "team_docs",
"tenant_id": "acme_corp",
"sub_tenant_id": "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,
"message": "Successfully fetched sources",
"user_memories": [
{
"memory_id": "mem_user_alex_tone",
"database": "acme_corp",
"collection": "team_docs",
"tenant_id": "acme_corp",
"sub_tenant_id": "team_docs",
"title": "Tone preference",
"type": "memory",
"metadata": { "user_id": "alex" }
}
],
"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" },
sourceFields: { 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). At most 100 IDs. (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) | |
Principals to list as (document ACLs). Only knowledge sources those principals may see come back. Omitted, [], or ["*"] lists everything. Ignored for type=memory. See Access Control. |
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 (exceptsource_fields.title, a case-insensitive prefix match). There are no range, contains, or OR operators on this endpoint; run multiple calls and merge client-side for OR behavior. Anullfilter value returns400.- AND: all filter pairs combine with a logical AND.
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. Each key is an equality check on the stored metadata; none is ignored. In a database with a schema, ingest rejects undeclared keys, so filtering on one returns nothing (except connector_id and provider, which connectors always write). | |
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) and connector fields (app_provider, app_kind, app_external_id, app_parent_id) | Use for app-source categories or quick title lookups. title must be a string and matches by case-insensitive prefix: "standup" finds “Standup notes 2026-05-12”. External IDs are unique only per provider, so pair app_external_id or app_parent_id with app_provider. Any other key returns 400. |
Field projection
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, plus the legacy names tenant_metadata and document_metadata. 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.{
"success": true,
"data": {
"success": true,
"message": "Successfully fetched sources",
"sources": [
{
"id": "policy_main",
"database": "acme_corp",
"collection": "team_docs",
"tenant_id": "acme_corp",
"sub_tenant_id": "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,
"message": "Successfully fetched sources",
"user_memories": [
{
"memory_id": "mem_user_alex_tone",
"database": "acme_corp",
"collection": "team_docs",
"tenant_id": "acme_corp",
"sub_tenant_id": "team_docs",
"title": "Tone preference",
"type": "memory",
"metadata": { "user_id": "alex" }
}
],
"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, keyed by memory_id, with the same fields as knowledge rows. The memory text and inferred_content are not included; read them with Inspect Context.
- Scope fields: every row carries
databaseandcollection, plus the deprecatedtenant_idandsub_tenant_idwith the same values. - Memory listing unavailable: if the memory store cannot be read, the call still returns
200with an emptyuser_memoriesandmessageset to"Memories temporarily unavailable". Checkmessagebefore you treat an empty list as “no memories”.
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"
}
]
}
Null on success; an object with code and message on failure.
Show child attributes
Show child attributes
Example:
null
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": "team_docs",
"tenant_id": "acme_corp"
}
Whether the request succeeded.
Example:
true
Was this page helpful?