> ## 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 Context > Browse over knowledge or memories with optional filters. Results are paginated. export const Field = ({name, type, required, recommended}) => { const label = required ? 'required' : recommended ? 'recommended' : null; const typeLabel = typeof type === 'string' ? type : null; const ariaParts = [name, typeLabel && `${typeLabel}`, label].filter(Boolean); return {name} {required && *} {recommended && ●} {type && {type}} {label && {label} } ; }; Specify the category using the `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. Supports pagination, metadata filters, and field projection. For metadata design and query-time behavior, see [Scoping using metadata](/essentials/v2/metadata). ```python Python SDK theme={"dark"} 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"], ) ``` ```typescript TypeScript SDK theme={"dark"} 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"], }); ``` ```bash cURL theme={"dark"} curl -X POST 'https://api.hydradb.com/context/list' \ -H "Authorization: Bearer " \ -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](#1-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 * `filters` is 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:** When `ids` is non-empty, only those IDs are considered, but other `filters` still apply on top - useful for "show me items 1, 2, 3 that also belong to department=legal". ```json theme={"dark"} { "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, pass `include_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](/api-reference/v2/endpoint/fetch-content). `include_fields` only applies to `type=knowledge`. It is ignored for `type=memory`. ```json Success theme={"dark"} { "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 } } ``` ```json Memories response theme={"dark"} { "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 } } ``` ```json Failure theme={"dark"} { "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 } } ``` When `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](/api-reference/v2/endpoint/fetch-content) * **Retrieve:** [Query](/api-reference/v2/endpoint/query) * **Delete:** [Delete Context](/api-reference/v2/endpoint/delete-source) ## OpenAPI ````yaml api-reference/v2/openapi.json POST /context/list openapi: 3.1.0 info: contact: email: support@hydradb.com name: HydraDB Support description: >- HydraDB Application API — knowledge ingestion, search, and memory management. license: name: Proprietary title: HydraDB Application API version: 0.1.0 servers: - description: Production server url: https://api.hydradb.com security: [] externalDocs: description: '' url: '' paths: /context/list: post: tags: - context summary: List documents description: List knowledge sources or memories (id + metadata) for a tenant. requestBody: content: application/json: schema: $ref: '#/components/schemas/list.V2ListContentRequest' description: List request required: true responses: '200': content: application/json: schema: $ref: >- #/components/schemas/handler.Envelope-list_V2SourceListResponse description: OK '400': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponse' description: Bad Request security: - BearerAuth: [] components: schemas: list.V2ListContentRequest: properties: collection: description: >- 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 type: string database: description: >- 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 type: string filters: $ref: '#/components/schemas/list.ContentFilter' example: additional_metadata: author: ada metadata: department: finance ids: description: >- When provided, only items with these IDs are returned. Pagination and filters still apply. example: - HydraDoc1234 - HydraDoc4567 items: type: string type: array uniqueItems: false include_fields: description: >- Field projection — only the listed fields plus id, database, collection are returned. Only applies to type=knowledge. example: - id - title - type items: type: string type: array uniqueItems: false page: description: Current page number (1-indexed). example: 1 type: integer page_size: description: Number of items per page. example: 50 type: integer sub_tenant_id: deprecated: true description: 'deprecated: use collection' example: sub_tenant_4567 type: string x-deprecated: 'true' tenant_id: deprecated: true description: 'deprecated: use database' example: tenant_1234 type: string x-deprecated: 'true' type: description: 'Bucket to list: `knowledge` (default) or `memory`.' enum: - knowledge - memory example: knowledge type: string type: object handler.Envelope-list_V2SourceListResponse: properties: data: $ref: '#/components/schemas/list.V2SourceListResponse' example: inner: message: Success pagination: has_next: true has_previous: false page: 1 page_size: 50 total: 128 total_pages: 3 success: true total: 128 error: $ref: '#/components/schemas/handler.apiError' description: Error message, empty string on success. example: code: DATABASE_NOT_FOUND message: Database not found meta: $ref: '#/components/schemas/handler.responseMeta' 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 success: description: Whether the request succeeded. example: true type: boolean type: object handler.ErrorResponse: properties: data: {} detail: $ref: '#/components/schemas/handler.ErrorDetail' description: Structured error detail with code, message, and deprecation hints. example: deprecated: true deprecated_field: tenant_id error_code: VALIDATION_ERROR message: Request validation failed preferred_field: database success: true error: $ref: '#/components/schemas/handler.apiError' description: Error message, empty string on success. example: code: DATABASE_NOT_FOUND message: Database not found meta: $ref: '#/components/schemas/handler.ErrorMeta' example: latency_ms: 12.3 request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d success: description: Whether the request succeeded. example: true type: boolean type: object list.ContentFilter: properties: additional_metadata: additionalProperties: {} description: >- Filters /context/list by document/additional metadata. Example: {"author": "ada"}. example: author: ada type: object metadata: additionalProperties: {} description: >- Filters /context/list by tenant/source metadata. Example: {"department": "finance"}. example: department: finance type: object source_fields: additionalProperties: {} description: >- SourceFields filters by well-known source fields such as title, type, description, url, and timestamp. type: object type: object list.V2SourceListResponse: properties: inner: $ref: '#/components/schemas/list.SourceListResponse' example: message: Success pagination: has_next: true has_previous: false page: 1 page_size: 50 total: 128 total_pages: 3 success: true total: 128 type: object handler.apiError: properties: code: description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`). example: DATABASE_NOT_FOUND type: string message: description: Human-readable description of the error. example: Database not found type: string type: object handler.responseMeta: properties: api_version: description: >- APIVersion echoes the version of the API that served the request (PRO-1209), sourced from reqmeta.APIVersion — the same value carried by OpenAPI info.version and /health — so a client always knows which API version produced a response. Always present (no omitempty). type: string collection: description: >- 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 type: string database: description: >- Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated). example: acme_corp type: string deprecation: description: >- Deprecation lists any migration nudges that apply to this request — the caller used a legacy /tenants route, a legacy tenant_id/sub_tenant_id field, or the deprecated sub_tenant_ids selector. It is a non-breaking signal (the status code is unchanged); omitempty keeps it absent for fully-migrated requests. A list so independent deprecations coexist without clobbering. items: $ref: '#/components/schemas/handler.deprecationNotice' type: array uniqueItems: false latency_ms: description: Server-side processing time in milliseconds. example: 12.3 type: number request_id: description: Unique identifier for this request, useful for support and tracing. example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d type: string source_type: description: Type of the parent source (e.g. `file`, `slack`, `notion`). example: file type: string sub_tenant_id: deprecated: true example: sub_tenant_4567 type: string x-deprecated: 'true' tenant_id: deprecated: true example: tenant_1234 type: string x-deprecated: 'true' type: object handler.ErrorDetail: properties: deprecated: description: Whether this response concerns a deprecated field or route. example: true type: boolean deprecated_field: description: The deprecated field name. example: tenant_id type: string error_code: description: Machine-readable error classification code. example: VALIDATION_ERROR type: string message: description: Human-readable description of the error. example: Request validation failed type: string preferred_field: description: The canonical replacement for the deprecated field. example: database type: string success: description: Always false for error responses. example: true type: boolean type: object handler.ErrorMeta: properties: api_version: type: string latency_ms: example: 12.3 type: number request_id: description: Unique identifier for this request, useful for support and tracing. example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d type: string type: object list.SourceListResponse: properties: message: description: Human-readable result message. example: Success type: string pagination: $ref: '#/components/schemas/dashboard.PaginationMeta' example: has_next: true has_previous: false page: 1 page_size: 50 total: 128 total_pages: 3 sources: description: Retrieved knowledge sources or memories for this page. items: additionalProperties: {} type: object type: array uniqueItems: false success: description: Whether the request succeeded. example: true type: boolean total: description: Total number of items across all pages. example: 128 type: integer type: object handler.deprecationNotice: properties: deprecated: description: Whether this response concerns a deprecated field or route. example: true type: boolean deprecated_field: description: The deprecated field name. example: tenant_id type: string deprecated_since: description: API version when the field was deprecated. example: 2.0.1 type: string message: description: Migration guidance message. example: tenant_id is deprecated; use database instead. type: string preferred_field: description: The canonical replacement for the deprecated field. example: database type: string type: object dashboard.PaginationMeta: properties: has_next: description: Whether a next page exists. example: true type: boolean has_previous: description: Whether a previous page exists. example: false type: boolean page: description: Current page number (1-indexed). example: 1 type: integer page_size: description: Number of items per page. example: 50 type: integer total: description: Total number of items across all pages. example: 128 type: integer total_pages: description: Total number of pages. example: 3 type: integer type: object securitySchemes: BearerAuth: bearerFormat: API key description: 'API key sent as a Bearer token: "Bearer prefix.secret"' scheme: bearer type: http ````