Inspect Context

file = client.context.inspect(
    id="policy_main",
    database="acme_corp",
    mode="both",
    expiry_seconds=3600,
)

const file = await client.context.inspect({
  id: "policy_main",
  database: "acme_corp",
  mode: "both",
  expirySeconds: 3600,
});

curl -G 'https://api.hydradb.com/context/inspect' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "id=policy_main" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "mode=both" \
  --data-urlencode "expiry_seconds=3600"

{
  "success": true,
  "data": {
    "success": true,
    "id": "policy_main",
    "content": null,
    "content_base64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c...",
    "inferred_content": null,
    "presigned_url": "https://storage.hydradb.com/.../policy_main.pdf?X-Amz-...",
    "content_type": "application/pdf",
    "size_bytes": 1842233,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Source 'policy_main' not found. Verify the id is correct and the source has been ingested."
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

GET

context

inspect

file = client.context.inspect(
    id="policy_main",
    database="acme_corp",
    mode="both",
    expiry_seconds=3600,
)

const file = await client.context.inspect({
  id: "policy_main",
  database: "acme_corp",
  mode: "both",
  expirySeconds: 3600,
});

curl -G 'https://api.hydradb.com/context/inspect' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "id=policy_main" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "mode=both" \
  --data-urlencode "expiry_seconds=3600"

{
  "success": true,
  "data": {
    "success": true,
    "id": "policy_main",
    "content": null,
    "content_base64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c...",
    "inferred_content": null,
    "presigned_url": "https://storage.hydradb.com/.../policy_main.pdf?X-Amz-...",
    "content_type": "application/pdf",
    "size_bytes": 1842233,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Source 'policy_main' not found. Verify the id is correct and the source has been ingested."
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

Returns the original content of one knowledge source or memory, a presigned download URL, or both. Pass its id.

file = client.context.inspect(
    id="policy_main",
    database="acme_corp",
    mode="both",
    expiry_seconds=3600,
)

const file = await client.context.inspect({
  id: "policy_main",
  database: "acme_corp",
  mode: "both",
  expirySeconds: 3600,
});

curl -G 'https://api.hydradb.com/context/inspect' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "id=policy_main" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "mode=both" \
  --data-urlencode "expiry_seconds=3600"

Query parameters

Name	Description
	ID of the source to fetch.
	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`)
	What to return. See Fetch modes. (default=`"both"`)
	TTL of the presigned URL (when `mode` includes `url`). Range `60` to `604800` (7 days). (default=`3600`)
	Principals to answer as (document ACLs). A source they cannot see returns the same `404` as a missing one. Repeated (`acl=a&acl=b`) or comma-separated. Omit for no ACL scoping. See Access Control.

Fetch modes

Mode	Returns	Use when
`content`	The stored bytes. Valid UTF-8 (plain text, Markdown, CSV, memory text, app sources) comes back as text in `content`; anything else (PDF, DOCX, images) comes back base64-encoded in `content_base64`. The other field is `null`.	You want the content inline. It is the stored original, so a PDF comes back as base64, not extracted text. Check both fields for unknown types.
`url`	Presigned URL (`presigned_url`) valid for `expiry_seconds`. `content`, `content_base64`, and `inferred_content` are `null`.	You want a client or a service to download the original file directly without proxying through your backend.
`both`(default)	Everything `content` returns, and presigned URL.	UI flows that show text inline plus a “Download original” link.

In content and both modes, the response also includes inferred_content when available: the model-derived text for the source (for memories, the inferred memory statement; for knowledge, derived/normalized content). It is null when the source has no inferred content.

Mode examples

mode=content
mode=url
mode=both (binary file)
Memory source (mode=both)

{
  "success": true,
  "data": {
    "success": true,
    "id": "policy_main",
    "content": null,
    "content_base64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c...",
    "inferred_content": null,
    "presigned_url": null,
    "content_type": "application/pdf",
    "size_bytes": 1842233,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "id": "policy_main",
    "content": null,
    "content_base64": null,
    "inferred_content": null,
    "presigned_url": "https://storage.hydradb.com/.../policy_main.pdf?X-Amz-...",
    "content_type": "application/pdf",
    "size_bytes": 1842233,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "id": "diagram_png",
    "content": null,
    "content_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "inferred_content": null,
    "presigned_url": "https://storage.hydradb.com/.../diagram.png?X-Amz-...",
    "content_type": "image/png",
    "size_bytes": 92844,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "id": "mem_user_alex_tone",
    "content": "Prefers concise answers and dark mode.",
    "content_base64": null,
    "inferred_content": "User prefers concise answers and dark mode.",
    "presigned_url": "https://storage.hydradb.com/.../mem_user_alex_tone?X-Amz-...",
    "content_type": "text/plain; charset=utf-8",
    "size_bytes": 38,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "id": "policy_main",
    "content": null,
    "content_base64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c...",
    "inferred_content": null,
    "presigned_url": "https://storage.hydradb.com/.../policy_main.pdf?X-Amz-...",
    "content_type": "application/pdf",
    "size_bytes": 1842233,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Source 'policy_main' not found. Verify the id is correct and the source has been ingested."
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

For a binary file

{
  "success": true,
  "data": {
    "success": true,
    "id": "diagram_png",
    "content": null,
    "content_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "inferred_content": null,
    "presigned_url": "https://storage.hydradb.com/.../diagram.png?X-Amz-...",
    "content_type": "image/png",
    "size_bytes": 92844,
    "message": "File fetched successfully",
    "error": null
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Behavior notes

Recently ingested sources: Fetching immediately after ingestion returns the stored original, but inferred_content stays null until processing produces it. For reliable reads, use Ingestion Status first.
Presigned URL TTL: The URL is valid only for expiry_seconds. Anyone with the URL can download the file during that window, so treat it as a short-lived secret.
Memory items: Fetching a memory’s id returns its raw text content (a conversation memory returns its stored JSON, with user_name and pairs). Memories are stored like files, so mode=url and mode=both also return a presigned_url.

Errors

Common codes: 400 INVALID_INPUT (missing id or database, an unknown mode, or expiry_seconds outside 60 to 604800), 404 DATABASE_NOT_FOUND, 404 NOT_FOUND (the source does not exist, or acl is set and its principals may not see it), 500 INTERNAL_ERROR (a transient storage error; retry). See Error Responses for the full list.

Authorizations

Authorization

string

header

required

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

Query Parameters

string

required

Source ID

Example:

"HydraDoc1234"

database

string

required

Database (canonical name for the tenant scope)

Example:

"acme_corp"

collection

string

Collection (canonical name for the sub-tenant scope)

Example:

"team_docs"

tenant_id

string

deprecated

Deprecated alias for database

Example:

"tenant_1234"

sub_tenant_id

string

deprecated

Deprecated alias for collection

Example:

"sub_tenant_4567"

expiry_seconds

integer

default:3600

Presigned URL expiry in seconds

mode

string

Fetch mode

Example:

"thinking"

acl

string[]

Principals to answer as (PRO-1684 document ACLs): the source must be visible to them, or the response is 404. Repeated (acl=a&acl=b) or comma-separated. Omit for no ACL scoping.

Response

data

object

Show child attributes

Example:

{
  "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
  "content_type": "text/markdown",
  "error": null,
  "id": "HydraDoc1234",
  "inferred_content": "Summary: Q4 revenue rose 23% QoQ, driven by enterprise expansion.",
  "message": "Success",
  "presigned_url": "https://storage.hydradb.com/sources/HydraDoc1234?sig=...",
  "size_bytes": 20480,
  "success": true
}

error

object | null

Null on success; an object with code and message on failure.

Show child attributes

Example:

null

Start here

Databases

Context

Query

Connectors

Webhooks

Reference

Query parameters

Fetch modes

Mode examples

Behavior notes

Errors

Authorizations

Query Parameters

Response

​Query parameters

​Fetch modes

​Mode examples

​Behavior notes

​Errors

Authorizations

Query Parameters

Response

Query parameters

Fetch modes

Mode examples

Behavior notes

Errors