List Context

sources = client.context.list(
    database="acme_corp",
    collection="team_docs",
    type="knowledge",
    page=1,
    page_size=50,
    filters={
        "metadata": {"department": "legal"},
        "source_fields": {"title": "Compliance"},
    },
    include_fields=["title", "type", "timestamp", "additional_metadata"],
)

const sources = await client.context.list({
  database: "acme_corp",
  collection: "team_docs",
  type: "knowledge",
  page: 1,
  pageSize: 50,
  filters: {
    metadata: { department: "legal" },
    sourceFields: { title: "Compliance" },
  },
  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",
    "collection": "team_docs",
    "type": "knowledge",
    "page": 1,
    "page_size": 50,
    "filters": {
      "metadata": { "department": "legal" },
      "source_fields": { "title": "Compliance" }
    },
    "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
  }
}

POST

context

list

sources = client.context.list(
    database="acme_corp",
    collection="team_docs",
    type="knowledge",
    page=1,
    page_size=50,
    filters={
        "metadata": {"department": "legal"},
        "source_fields": {"title": "Compliance"},
    },
    include_fields=["title", "type", "timestamp", "additional_metadata"],
)

const sources = await client.context.list({
  database: "acme_corp",
  collection: "team_docs",
  type: "knowledge",
  page: 1,
  pageSize: 50,
  filters: {
    metadata: { department: "legal" },
    sourceFields: { title: "Compliance" },
  },
  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",
    "collection": "team_docs",
    "type": "knowledge",
    "page": 1,
    "page_size": 50,
    "filters": {
      "metadata": { "department": "legal" },
      "source_fields": { "title": "Compliance" }
    },
    "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
  }
}

Page through the sources stored in one database and collection, for example to find IDs or audit what was ingested. type selects what to list: knowledge (the default: documents and app sources), memory, or all for both. Narrow results with ids and filters, and return only the fields you need with include_fields. See Metadata Filters for the metadata workflow.

sources = client.context.list(
    database="acme_corp",
    collection="team_docs",
    type="knowledge",
    page=1,
    page_size=50,
    filters={
        "metadata": {"department": "legal"},
        "source_fields": {"title": "Compliance"},
    },
    include_fields=["title", "type", "timestamp", "additional_metadata"],
)

const sources = await client.context.list({
  database: "acme_corp",
  collection: "team_docs",
  type: "knowledge",
  page: 1,
  pageSize: 50,
  filters: {
    metadata: { department: "legal" },
    sourceFields: { title: "Compliance" },
  },
  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",
    "collection": "team_docs",
    "type": "knowledge",
    "page": 1,
    "page_size": 50,
    "filters": {
      "metadata": { "department": "legal" },
      "source_fields": { "title": "Compliance" }
    },
    "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
  }
}

Filters

filters accepts three categories:

{
  "filters": {
    "metadata": { "department": "Finance", "region": "US" },
    "additional_metadata": { "author": "Alice Smith" },
    "source_fields": { "app_provider": "slack", "title": "standup notes" }
  }
}

metadata: schema-backed metadata fields.
additional_metadata: free-form metadata. No schema declaration is required.
source_fields: built-in and connector fields. Supported keys are type, title, description, url, timestamp, app_provider, app_kind, app_external_id, and app_parent_id. Unsupported keys return 400. Pair external IDs with app_provider.

Matching rules:

Values must match exactly, except source_fields.title, which matches a case-insensitive prefix.
All filter pairs combine with AND. When ids is non-empty, filters apply only to those IDs, and pagination still applies.
Range, contains, and OR operators are not supported. For OR behavior, run separate calls and combine the results in your application.
A null filter value returns 400.

Field projection

Pass include_fields to keep response payloads small. Only the listed fields are populated, plus id, database, and collection, which are always returned. Treat omitted fields as unavailable in that response. Omit include_fields or pass null to return everything.

Allowed values are title, type, description, note, timestamp, metadata, additional_metadata, and relations, plus the deprecated aliases tenant_metadata and document_metadata.
content, url, and attachments are not valid values. They are stripped from list responses, and requesting one returns 400. Fetch them per source with Inspect Context.
Projection applies only to type=knowledge.

Behavior notes

Memories: For type=memory, read data.user_memories[]. Each entry includes a memory_id, source details, and metadata. Read the memory text and inferred_content with Inspect Context.
Memory listing unavailable: If the memory store cannot be read, the call still returns 200 with an empty user_memories and message set to "Memories temporarily unavailable". Check message before you treat an empty list as “no memories”.
Access control: acl lists the principals to list as. Omitting it, or sending [] or ["*"], disables caller-supplied filtering. It is ignored for type=memory. For enforced connectors, the authenticated caller is used instead; see ACL enforcement.
Limits: ids accepts at most 100 IDs. page_size ranges from 1 to 100 (default 50), and page starts at 1.

Before this: Ingest Context: store the sources to list
After this: Inspect Context: read one source’s content
After this: Delete Context: remove sources by ID
Related: Query: retrieve chunks by relevance instead of listing sources
Guide: Metadata Filters

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer <your_api_key>.

Body

application/json

List request

acl

string[]

Principals to answer as: only context they may see is listed. Omit it for no access scoping.

collection

string

Collection to list. Omit it to use the database's default collection.

Example:

"team_docs"

database

string

Database to list. Required. Formerly tenant_id; the alias is still accepted.

Example:

"acme_corp"

filters

ListContentFilter · object

Exact-match filters on metadata, additional_metadata and built-in source_fields. All pairs must match.

Show child attributes

Example:

{
  "additional_metadata": { "author": "ada" },
  "metadata": { "department": "finance" },
  "source_fields": {
    "app_external_id": "C0123456789",
    "app_kind": "slack",
    "app_provider": "slack",
    "description": "Internal overview of the Project Phoenix rollout.",
    "timestamp": "2026-07-02T10:00:00Z",
    "title": "Project Phoenix Overview",
    "type": "knowledge",
    "url": "https://docs.hydradb.com/phoenix"
  }
}

group_threads

boolean

Nest each thread's comments and replies under their parent row as comments, newest first, instead of listing them as separate rows. Default false.

Example:

true

ids

string[]

List only these context IDs, at most 100. Pagination and filters still apply.

Example:

["HydraDoc1234", "HydraDoc4567"]

include_fields

string[]

Return only these fields plus id, database and collection. Supported fields are title, type, description, note, timestamp, metadata, additional_metadata and relations.

Example:

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

page

integer

Page number, starting at 1. Default 1.

Example:

1

page_size

integer

Rows per page, from 1 to 100. Default 50.

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>

Corpus to list, knowledge, memory or all for both. Defaults to knowledge.

Available options:

knowledge,

memory,

all

Example:

"knowledge"

Response

data

ListV2ListResponse · object

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",
      "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

HandlerApiError · object | null

Error details on failure, or null on success.

Show child attributes

Example:

null

Overview

Databases

Context

Query

Connectors

Webhooks

Filters

Field projection

Behavior notes

Authorizations

Body

Response

​Filters

​Field projection

​Behavior notes

​Related resources

Authorizations

Body

Response

Filters

Field projection

Behavior notes

Related resources