List Context

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
  }
}

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

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

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

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

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
  }
}

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
Retrieve: Query
Delete: Delete Context

Authorizations

Authorization

string

header

required

API key sent as a Bearer token: "Bearer prefix.secret"

Body

application/json

List request

collection

string

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

string

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"

filters

object

Show child attributes

Example:

{
  "additional_metadata": { "author": "ada" },
  "metadata": { "department": "finance" }
}

ids

string[]

When provided, only items with these IDs are returned. Pagination and filters still apply.

Example:

["HydraDoc1234", "HydraDoc4567"]

include_fields

string[]

Field projection — only the listed fields plus id, database, collection are returned. Only applies to type=knowledge.

Example:

["id", "title", "type"]

page

integer

Current page number (1-indexed).

Example:

1

page_size

integer

Number of items per page.

Example:

50

sub_tenant_id

string

deprecated

deprecated: use collection

Example:

"sub_tenant_4567"

tenant_id

string

deprecated

deprecated: use database

Example:

"tenant_1234"

type

enum<string>

Bucket to list: knowledge (default) or memory.

Available options:

knowledge,

memory

Example:

"knowledge"

Response

data

object

Show child attributes

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

object

Error message, empty string on success.

Show child attributes

Example:

{
  "code": "DATABASE_NOT_FOUND",
  "message": "Database not found"
}

API Documentation

Databases

Context

Query

Connectors

Miscellaneous

Request body

1. Filters

2. Including Fields for convenient data objects

Authorizations

Body

Response

​Request body

​1. Filters

​2. Including Fields for convenient data objects

Authorizations

Body

Response

Request body

1. Filters

2. Including Fields for convenient data objects