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": "Section 1. Authentication policies...",
    "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,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "SOURCE_NOT_FOUND",
    "message": "Source not found"
  },
  "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": "Section 1. Authentication policies...",
    "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,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "SOURCE_NOT_FOUND",
    "message": "Source not found"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

Specify the id of the knowledge or memory you want to retrieve.

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 ≤ x ≤ 604800` (7 days). (default=`3600`)

Fetch modes

Mode	Returns	Use when
`content`	The payload in `content_base64` (base64-encoded); `content` is `null` in this mode. Decode `content_base64` to recover the parsed text or the raw binary bytes.	You want to render the content in-app or feed it to another model.
`url`	Presigned URL (`presigned_url`) valid for `expiry_seconds`.	You want a client or a service to download the original file directly without proxying through your backend.
`both`(default)	Text and presigned URL.	UI flows that show parsed text inline plus a “Download original” link.

Regardless of mode, 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.

Use mode=url when you need the original file. Use mode=content when you only need extracted text for display, summarization, or prompting.

Mode examples

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

{
  "success": true,
  "data": {
    "success": true,
    "id": "policy_main",
    "content": null,
    "content_base64": "U2VjdGlvbiAxLiBBdXRoZW50aWNhdGlvbiBwb2xpY2llcy4uLg==",
    "inferred_content": null,
    "presigned_url": null,
    "content_type": "application/pdf",
    "size_bytes": 1842233,
    "message": "File fetched successfully"
  },
  "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,
  "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,
  "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": null,
    "content_type": "text/plain",
    "size_bytes": null,
    "message": "Memory fetched successfully"
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "id": "policy_main",
    "content": "Section 1. Authentication policies...",
    "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,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "SOURCE_NOT_FOUND",
    "message": "Source not found"
  },
  "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,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Behavior notes

Text vs binary handling. In mode=both, text-parseable sources (PDF, DOCX, MD, TXT) populate content with parsed text while non-text/binary files come back in content_base64; check both fields when handling unknown content types. In mode=content, the payload is always returned base64-encoded in content_base64 and content is null - decode content_base64 to recover the text or bytes.

inferred_content: Alongside the raw content, the response carries inferred_content - the model-derived text for the source. For memories this is the inferred memory statement (e.g. "User prefers concise answers and dark mode."); for knowledge sources it is typically null unless derived content exists. It is returned for every mode.
Recently ingested sources: Fetching immediately after ingestion may return a record before the parsed text is ready. 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. There are no presigned URLs for memory items - mode=url and mode=both return presigned_url: null.

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": "application/pdf",
  "error": "",
  "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

Error message, empty string on success.

Show child attributes

Example:

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

API Documentation

Databases

Context

Query

Connectors

Webhooks

Miscellaneous

Query parameters

Fetch modes

Mode examples

Behavior notes

Authorizations

Query Parameters

Response

​Query parameters

​Fetch modes

​Mode examples

​Behavior notes

Authorizations

Query Parameters

Response

Query parameters

Fetch modes

Mode examples

Behavior notes