import json
with open("policy.pdf", "rb") as policy:
result = client.context.ingest(
database="acme_corp",
collection="company_docs",
type="knowledge",
documents=[("policy.pdf", policy, "application/pdf")],
document_metadata=json.dumps([{"id": "policy_main"}]),
)
const result = await client.context.ingest({
database: "acme_corp",
collection: "company_docs",
type: "knowledge",
documents: [{ path: "policy.pdf", filename: "policy.pdf", contentType: "application/pdf" }],
documentMetadata: JSON.stringify([{ id: "policy_main" }]),
});
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer $HYDRADB_API_KEY" \
-H "API-Version: 2" \
-F "database=acme_corp" \
-F "collection=company_docs" \
-F "type=knowledge" \
-F "[email protected]" \
-F 'document_metadata=[{"id":"policy_main"}]'
{
"data": {
"failed_count": 0,
"generation_started_at_ms": 1,
"message": "Success",
"results": [
{
"error": null,
"error_code": null,
"filename": "policy.pdf",
"id": "HydraDoc1234",
"infer": true,
"relations_created": 5,
"status": "queued",
"title": "Project Phoenix Overview"
}
],
"success": true,
"success_count": 2
},
"error": null,
"meta": {
"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",
"warnings": [
{
"code": "acl_ignored_by_connector_enforcement",
"collections": [
"team_docs",
"engineering"
],
"message": "This connector enforces ACL, so the request's acl was ignored."
}
]
},
"success": true
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}Context
Ingest Context
Store documents, app sources, and memories for your AI.
POST
/
context
/
ingest
import json
with open("policy.pdf", "rb") as policy:
result = client.context.ingest(
database="acme_corp",
collection="company_docs",
type="knowledge",
documents=[("policy.pdf", policy, "application/pdf")],
document_metadata=json.dumps([{"id": "policy_main"}]),
)
const result = await client.context.ingest({
database: "acme_corp",
collection: "company_docs",
type: "knowledge",
documents: [{ path: "policy.pdf", filename: "policy.pdf", contentType: "application/pdf" }],
documentMetadata: JSON.stringify([{ id: "policy_main" }]),
});
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer $HYDRADB_API_KEY" \
-H "API-Version: 2" \
-F "database=acme_corp" \
-F "collection=company_docs" \
-F "type=knowledge" \
-F "[email protected]" \
-F 'document_metadata=[{"id":"policy_main"}]'
{
"data": {
"failed_count": 0,
"generation_started_at_ms": 1,
"message": "Success",
"results": [
{
"error": null,
"error_code": null,
"filename": "policy.pdf",
"id": "HydraDoc1234",
"infer": true,
"relations_created": 5,
"status": "queued",
"title": "Project Phoenix Overview"
}
],
"success": true,
"success_count": 2
},
"error": null,
"meta": {
"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",
"warnings": [
{
"code": "acl_ignored_by_connector_enforcement",
"collections": [
"team_docs",
"engineering"
],
"message": "This connector enforces ACL, so the request's acl was ignored."
}
]
},
"success": true
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}{
"data": null,
"detail": {
"deprecated": true,
"deprecated_field": "tenant_id",
"deprecated_since": "2.0.1",
"error_code": "VALIDATION_ERROR",
"message": "Request validation failed",
"preferred_field": "database",
"retry_after_seconds": 1,
"retryable": true
},
"error": {
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
},
"meta": {
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
},
"success": false
}Ingest context into a database in one multipart request. Ingestion is asynchronous: the response returns an ID for each source, and a source is searchable once indexing completes. Choose the payload by what you are storing:
See Metadata Filters for choosing metadata fields and filtering on them, and metadata size limits for how HydraDB measures the caps.
Those seven, plus the deprecated aliases
| Payload | Send | Use for |
|---|---|---|
| Documents | type: "knowledge" and documents | Binary uploads that HydraDB should parse: PDFs, Office and iWork files, spreadsheets, images, and plain text. See Supported file formats. |
| App sources | type: "knowledge" and app_knowledge | Text and metadata your application has already extracted from an app (Slack threads, Notion pages, emails, tickets). See Context. |
| Memories | type: "memory" and memories | Preferences, decisions, inferred behavior traits, and past conversations your agent should remember in future sessions. See Context. |
import json
with open("policy.pdf", "rb") as policy:
result = client.context.ingest(
database="acme_corp",
collection="company_docs",
type="knowledge",
documents=[("policy.pdf", policy, "application/pdf")],
document_metadata=json.dumps([{"id": "policy_main"}]),
)
const result = await client.context.ingest({
database: "acme_corp",
collection: "company_docs",
type: "knowledge",
documents: [{ path: "policy.pdf", filename: "policy.pdf", contentType: "application/pdf" }],
documentMetadata: JSON.stringify([{ id: "policy_main" }]),
});
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer $HYDRADB_API_KEY" \
-H "API-Version: 2" \
-F "database=acme_corp" \
-F "collection=company_docs" \
-F "type=knowledge" \
-F "[email protected]" \
-F 'document_metadata=[{"id":"policy_main"}]'
Form fields
| Name | Description |
|---|---|
Use singular "memory" when ingesting memories. (default="knowledge") | |
| Target database. | |
| Collection to write to. A new name creates the collection automatically. Omit it to use the default collection. List existing collections with List Collections. | |
Replace existing sources with the same ID. Set to false to error on conflict: a document or app source whose ID exists comes back failed with error_code: "E9003". (default=true) | |
Binary uploads, knowledge only. Required when type=knowledge and you want HydraDB to parse documents. Omit when ingesting memories. See Supported file formats. (default=[]) | |
One entry per file in documents, in the same order. The counts must match, or the request returns 400. If omitted, documents index with inferred defaults such as filename/title. See item fields. | |
| Pre-extracted source objects (Slack, Notion, web pages, etc.), knowledge only. See item fields. | |
Map of source ID to your own entities and relations. Replaces LLM graph extraction for each keyed source. Works for type=knowledge and type=memory. See the “Bring your own graph” example in item fields and the Bring Your Own Graph guide. | |
Memory items, memory only. Required and non-empty when type=memory. The form field is plural memories, even though type is singular memory. See item fields. |
- Multipart, not JSON: This endpoint uses
multipart/form-data. Stringify all JSON arrays (document_metadata,app_knowledge,memories) before placing them in the form field. A body that is neither a form nor JSON returns415. 202 Acceptedmeans queued, not indexed: A successful response only confirms your sources were accepted, not that they are ready to query. Before querying, pollGET /context/statuswith the returned IDs until each source reachesgraph_creation(searchable),completed, orerrored. Alternatively, register a webhook forindexing.status_changedevents (see Webhooks).- Memory and knowledge: Use
type: "memory"for memory ingestion, listing, and deletion. Usetype: "all"onPOST /querywhen results should combine both.
Supported file formats
Each file indocuments can be up to 50 MB. A larger file returns 413 with a message naming the file, and no part of the request is processed. Split larger files before uploading.
View supported and unsupported file formats
View supported and unsupported file formats
HydraDB accepts these formats through
What HydraDB extracts differs by type:
Files with no readable text fail with
Use the file’s real extension. When the filename has no extension, HydraDB uses the part’s
documents:| Type | Formats |
|---|---|
| Documents | .pdf .doc .docx .docm .dot .dotx .odt .ott .rtf |
| Spreadsheets | .xls .xlsx .xlsm .xlsb .ods .ots .csv .tsv |
| Presentations | .ppt .pptx .pptm .odp .otp |
| Apple iWork | .pages .numbers .key |
| Images | .png .jpg .jpeg .tif .tiff .webp .gif .bmp |
| Plain text | .txt .md .markdown .json |
| Type | What gets indexed |
|---|---|
| Documents and presentations | The text, in reading order. Slide titles and body text both come through. |
| Spreadsheets | Cell values rendered as a table, one per sheet. Formulas are indexed as their computed result, not the formula itself. |
| Images and scans | Text read out of the picture with OCR. A photo of a page and a scan of a page both work. |
| Plain text | The file as-is. |
E2002. Upload a version containing text.Unsupported formats
| Format | Upload this instead |
|---|---|
.heic .heif .avif | Export the photo as JPEG or PDF |
.svg .ico | Export as PNG or JPEG |
.html .htm .xml | Save the page as PDF |
.eml .msg | Save the message as PDF, or send it as an app source |
.epub .wpd | Convert to PDF or DOCX |
.zip | Upload the files individually |
Content-Type. Renaming an unsupported file does not convert it: a renamed file may fail during indexing. Check Ingestion Status for that failure.When a file is not supported
An unsupported file is rejected in the upload response and does not block other files in the upload. The request returns202 as usual. The rejected file comes back with status: "failed" and error_code: "E1002", and every other file is queued normally:{
"success": true,
"data": {
"success": false,
"message": "Upload completed with some failures.",
"results": [
{ "id": "6cc7bcd185b044cd", "filename": "report.pdf", "status": "queued", "error": null, "error_code": null },
{ "id": "f47411c736447126", "filename": "photo.heic", "status": "failed", "error": "This file format isn't supported. Please upload a PDF, Office document (Word, Excel, PowerPoint), image, CSV or text file.", "error_code": "E1002" },
{ "id": "d0c919bdec196a8d", "filename": "notes.txt", "status": "queued", "error": null, "error_code": null }
],
"success_count": 2,
"failed_count": 1
},
"error": null,
"meta": { "request_id": "bcd03673-174d-4a73-83e6-73bfcdc16061", "api_version": "2.0.1" }
}
data.success is true only when every file was queued. Check data.results for individual failures.Files rejected with E1002 have no ingestion status record. Handle the format error from the upload response.Shared item fields
Items indocument_metadata, app_knowledge, and memories share three fields. The per-type tables under Examples and item fields list only what differs.
| Field | Description |
|---|---|
The source’s ID and its upsert key. Use your application’s ID to keep the same identifier in both systems. Must not contain a comma (,): the comma is reserved as the ID separator on Ingestion Status (GET /context/status?ids=a,b), so an item whose id contains a comma is rejected with a 400. | |
Database-schema fields for filtering and search. Keys must be declared in database_metadata_schema. Send an object, for example { "department": "legal" }. At most 16 KiB. (default={}) | |
Free-form per-source fields for display or bookkeeping, sent as an object. To filter on these at query time, nest them under metadata_filters.additional_metadata. At most 1 KiB. (default={}) |
Examples and item fields
Knowledge documents: upload PDFs, DOCX, CSV, markdown, or text
Knowledge documents: upload PDFs, DOCX, CSV, markdown, or text
import json
with open("/path/to/policy.pdf", "rb") as f1, open("/path/to/runbook.pdf", "rb") as f2:
result = client.context.ingest(
type="knowledge",
database="acme_corp",
documents=[
("policy.pdf", f1, "application/pdf"),
("runbook.pdf", f2, "application/pdf"),
],
document_metadata=json.dumps([
{"id": "policy_main", "metadata": {"department": "legal"}},
{"id": "runbook_deploy", "metadata": {"department": "ops"}},
]),
)
const result = await client.context.ingest({
type: "knowledge",
database: "acme_corp",
documents: [
{ path: "/path/to/policy.pdf", filename: "policy.pdf", contentType: "application/pdf" },
{ path: "/path/to/runbook.pdf", filename: "runbook.pdf", contentType: "application/pdf" },
],
documentMetadata: JSON.stringify([
{ id: "policy_main", metadata: { department: "legal" } },
{ id: "runbook_deploy", metadata: { department: "ops" } },
]),
});
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-F "type=knowledge" \
-F "database=acme_corp" \
-F "documents=@/path/to/policy.pdf" \
-F "documents=@/path/to/runbook.pdf" \
-F 'document_metadata=[
{ "id": "policy_main", "metadata": { "department": "legal" } },
{ "id": "runbook_deploy", "metadata": { "department": "ops" } }
]'
| Field | Description |
|---|---|
Optional. If set, becomes the id for this document. See shared item fields. | |
| See shared item fields. | |
| See shared item fields. | |
Forceful relations (links you declare between sources). Shape: { "ids": ["...", "..."] }. Linked sources come back in additional_context on mode: "thinking" queries. | |
Run model enrichment on this file. (default=false) | |
How this content came to be known: assertion, record, said, done, third_party, or inferred. Any other value returns 400. | |
| A stable handle for who or what the content is about. |
source_id and file_id (for id) and document_metadata (for additional_metadata), are the only keys accepted. Anything else (including title, type, url and timestamp) is rejected with a 400 naming the unsupported key, rather than being silently dropped.In particular, a document’s title is derived, not settable. It defaults to the uploaded filename and is returned as source_title on query results and title on /context/list. It cannot be overridden at ingest, and PATCH /context/{id}/metadata only merges additional_metadata and database_metadata. Use additional_metadata for your own display fields, or ingest through app_knowledge, whose items carry an explicit title.Knowledge documents: upload in-memory text as a .txt file
Knowledge documents: upload in-memory text as a .txt file
If you already have text in memory, create a file-like object and upload it through
documents as a text/plain .txt file.import io
import json
text = """Q4 planning notes
- Launch checklist is owned by Priya.
- Legal review is due by Friday.
"""
# Create a file-like object in memory. No local .txt file is required.
txt_file = io.BytesIO(text.encode("utf-8"))
response = client.context.ingest(
type="knowledge",
database="acme_corp",
collection="team_docs",
documents=[("meeting-notes.txt", txt_file, "text/plain")],
document_metadata=json.dumps([
{"id": "meeting_notes_q4", "metadata": {"department": "product"}}
]),
)
const text = `Q4 planning notes
- Launch checklist is owned by Priya.
- Legal review is due by Friday.
`;
const response = await client.context.ingest({
type: "knowledge",
database: "acme_corp",
collection: "team_docs",
documents: [
{
filename: "meeting-notes.txt",
contentType: "text/plain",
data: Buffer.from(text, "utf-8"),
},
],
documentMetadata: JSON.stringify([
{ id: "meeting_notes_q4", metadata: { department: "product" } },
]),
});
printf 'Q4 planning notes\n\n- Launch checklist is owned by Priya.\n- Legal review is due by Friday.\n' | \
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-F "type=knowledge" \
-F "database=acme_corp" \
-F "collection=team_docs" \
-F "documents=@-;filename=meeting-notes.txt;type=text/plain" \
-F 'document_metadata=[{"id":"meeting_notes_q4","metadata":{"department":"product"}}]'
App sources: index text from your workspace or personal apps
App sources: index text from your workspace or personal apps
import json
client.context.ingest(
type="knowledge",
database="acme_corp",
collection="team_docs",
app_knowledge=json.dumps([
{
"id": "slack_thread_001",
"title": "Pricing discussion",
"kind": "message",
"provider": "slack",
"external_id": "1716213600.000100",
"fields": {"kind": "message", "body": "We agreed on three tiers...", "author": "alice"},
"metadata": {"channel": "product"},
}
]),
)
await client.context.ingest({
type: "knowledge",
database: "acme_corp",
collection: "team_docs",
appKnowledge: JSON.stringify([
{
id: "slack_thread_001",
title: "Pricing discussion",
kind: "message",
provider: "slack",
external_id: "1716213600.000100",
fields: { kind: "message", body: "We agreed on three tiers...", author: "alice" },
metadata: { channel: "product" },
},
]),
});
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-F "type=knowledge" \
-F "database=acme_corp" \
-F "collection=team_docs" \
-F 'app_knowledge=[
{
"id": "slack_thread_001",
"title": "Pricing discussion",
"kind": "message",
"provider": "slack",
"external_id": "1716213600.000100",
"fields": { "kind": "message", "body": "We agreed on three tiers...", "author": "alice" },
"metadata": { "channel": "product" }
}
]'
| Field | Description |
|---|---|
| Required. Send an empty string to have one generated upstream. See shared item fields. | |
Optional. If sent, must match the form-level database. | |
Optional. If sent, must match the form-level collection. | |
| Short title or subject shown in query results. | |
| Optional long-form description. | |
| Canonical URL or reference link. | |
| ISO-8601 timestamp (creation or last-updated). | |
App object kind: email, message, ticket, knowledge_base, comment, meeting, or custom. Selects the parser for fields. | |
App namespace such as slack, gmail, jira, or notion. | |
| The provider’s ID for this exact item. Enables exact lookup and relation resolution. | |
App-native content and structure (body, description, title, or data, by kind). fields.kind must match kind. See Context. | |
Older generic payload, { "text": "..." }. Prefer kind and fields, which let app-aware retrieval see authors, threads, and parents. | |
| See shared item fields. | |
| See shared item fields. | |
Optional related attachments. (default=[]) | |
Relations to other sources: { "ids": [...] } as on document_metadata items, or the typed [{ "predicate", "target" }] list described in Context. | |
Principals allowed to retrieve this source. Omit to leave it unrestricted. A malformed principal rejects the whole request with 400. See Query. |
Memories: store notes or infer user preferences
Memories: store notes or infer user preferences
import json
client.context.ingest(
type="memory",
database="acme_corp",
collection="user_alex",
memories=json.dumps([
{
"text": "Prefers dark mode and short answers.",
"infer": True,
"user_name": "Alex",
}
]),
)
await client.context.ingest({
type: "memory",
database: "acme_corp",
collection: "user_alex",
memories: JSON.stringify([
{
text: "Prefers dark mode and short answers.",
infer: true,
user_name: "Alex",
},
]),
});
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-F "type=memory" \
-F "database=acme_corp" \
-F "collection=user_alex" \
-F 'memories=[
{
"text": "Prefers dark mode and short answers.",
"infer": true,
"user_name": "Alex"
}
]'
| Field | Description |
|---|---|
| Optional. See shared item fields. (default=auto-generated) | |
Label returned as title by List Context and source_title by Query. (default=the memory’s id) | |
Raw text or markdown content. Required unless user_assistant_pairs is provided. | |
Conversation pairs { user, assistant }. Required unless text is provided. | |
Treat text as markdown for chunking. (default=false) | |
When true, HydraDB extracts the underlying preference from raw signal, using earlier context to improve accuracy. When false, it stores the text verbatim. (default=false) | |
Guides extraction when infer: true. Ignored when infer: false. | |
The user’s name. Feeds inference. (default="User") | |
| See shared item fields. | |
| See shared item fields. |
Memories: store conversation pairs as chat history or support context
Memories: store conversation pairs as chat history or support context
import json
client.context.ingest(
type="memory",
database="acme_corp",
collection="user_alex",
memories=json.dumps([
{
"title": "Support conversation about refunds",
"user_assistant_pairs": [
{"user": "Can I get a refund?", "assistant": "Refunds are available within 30 days."},
],
"infer": False,
}
]),
)
await client.context.ingest({
type: "memory",
database: "acme_corp",
collection: "user_alex",
memories: JSON.stringify([
{
title: "Support conversation about refunds",
user_assistant_pairs: [
{ user: "Can I get a refund?", assistant: "Refunds are available within 30 days." },
],
infer: false,
},
]),
});
curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-F "type=memory" \
-F "database=acme_corp" \
-F "collection=user_alex" \
-F 'memories=[
{
"title": "Support conversation about refunds",
"user_assistant_pairs": [
{ "user": "Can I get a refund?", "assistant": "Refunds are available within 30 days." }
],
"infer": false
}
]'
Bring your own graph: supply entities and relations
Bring your own graph: supply entities and relations
Sources keyed in
Caps per graph: at most 5,000 entities, 10,000 relations, and 500 relations per entity; over-cap returns
graph_payload are still chunked and embedded, so they stay searchable. See Bring Your Own Graph for the full guide.curl -X POST 'https://api.hydradb.com/context/ingest' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-F "type=knowledge" \
-F "database=acme_corp" \
-F "documents=@/path/to/policy.pdf" \
-F 'document_metadata=[{ "id": "billing-policy-doc" }]' \
-F 'graph_payload={
"billing-policy-doc": {
"entities": {
"alice": { "name": "Alice Carter", "type": "PERSON", "namespace": "employees" },
"billing": { "name": "Billing Policy", "type": "POLICY", "namespace": "policies" }
},
"relations": [
{ "source": "alice", "target": "billing", "predicate": "OWNS",
"context": "Alice Carter owns the billing policy." }
]
}
}'
import json
with open("/path/to/policy.pdf", "rb") as f:
client.context.ingest(
type="knowledge",
database="acme_corp",
documents=[("policy.pdf", f, "application/pdf")],
document_metadata=json.dumps([{"id": "billing-policy-doc"}]),
graph_payload=json.dumps({
"billing-policy-doc": {
"entities": {
"alice": {"name": "Alice Carter", "type": "PERSON", "namespace": "employees"},
"billing": {"name": "Billing Policy", "type": "POLICY", "namespace": "policies"},
},
"relations": [
{"source": "alice", "target": "billing", "predicate": "OWNS",
"context": "Alice Carter owns the billing policy."},
],
}
}),
)
await client.context.ingest({
type: "knowledge",
database: "acme_corp",
documents: [{ path: "/path/to/policy.pdf", filename: "policy.pdf", contentType: "application/pdf" }],
documentMetadata: JSON.stringify([{ id: "billing-policy-doc" }]),
graphPayload: JSON.stringify({
"billing-policy-doc": {
entities: {
alice: { name: "Alice Carter", type: "PERSON", namespace: "employees" },
billing: { name: "Billing Policy", type: "POLICY", namespace: "policies" },
},
relations: [
{ source: "alice", target: "billing", predicate: "OWNS",
context: "Alice Carter owns the billing policy." },
],
},
}),
});
| Field | Description |
|---|---|
Top-level key: a document_metadata id or app_knowledge item id for type=knowledge, or a memory id for type=memory. Value is that source’s graph. A key matching no source returns 400. | |
Map keyed by a caller-local id; each value is an entity. The key is only a handle for relations to reference. It is not stored. | |
| Entity name. Normalized (lowercased) server-side so it matches at query time. At most 256 chars. | |
Entity type (e.g. PERSON, POLICY). Stored as supplied. | |
| Logical grouping for the entity. Stored as supplied. | |
| Optional external id (email, URL, etc.), display only. | |
| Edges referencing entity-map keys. | |
| Entity-map key of the source entity. | |
| Entity-map key of the target entity. | |
| Relationship label, any plain string. At most 256 chars. | |
| Optional sentence supporting the edge. At most 2,000 chars. | |
| Optional timing info (e.g. “since 2021”, “in Q3”). |
400. Graphs survive re-ingest: a re-upload or connector re-sync re-applies the stored graph.Related resources
- After this: Ingestion Status: always confirm sources are indexed before you query
- After this: Query: retrieve context once it is indexed
- After this: List Context: browse what you ingested
- After this: Inspect Context: read one source’s original content
- After this: Delete Context: remove sources by ID
- Guide: Context: upload files and wait for indexing
Authorizations
Body
multipart/form-data
A multipart form containing the database, collection and content to ingest.
Response
Accepted
Show child attributes
Show child attributes
Example:
{
"failed_count": 0,
"generation_started_at_ms": 1,
"message": "Success",
"results": [
{
"error": null,
"error_code": null,
"filename": "policy.pdf",
"id": "HydraDoc1234",
"infer": true,
"relations_created": 5,
"status": "queued",
"title": "Project Phoenix Overview"
}
],
"success": true,
"success_count": 2
}
Show child attributes
Show child attributes
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",
"warnings": [
{
"code": "acl_ignored_by_connector_enforcement",
"collections": ["team_docs", "engineering"],
"message": "This connector enforces ACL, so the request's acl was ignored."
}
]
}
Was this page helpful?
