Upload Knowledge

Ingest documents (files) and/or app-generated content (app knowledge) into a tenant.

POST /ingestion/upload_knowledge

Upload Knowledge

Python

import requests

url = "https://api.hydradb.com/ingestion/upload_knowledge"

files = { "files.items": ("example-file", open("example-file", "rb")) }
payload = {
    "tenant_id": "tenant_1234",
    "sub_tenant_id": "sub_tenant_4567",
    "upsert": "true",
    "file_metadata": "<string>",
    "app_knowledge": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

200

{
  "success": true,
  "message": "Upload initiated successfully",
  "results": [],
  "success_count": 1,
  "failed_count": 1
}

When to use it

Use this endpoint to add knowledge that your agents will recall later:

• Files – PDFs, DOCX, Markdown, CSVs, and other documents you want HydraDB to parse and chunk
• App knowledge – structured content from connected apps (Slack messages, Notion pages, Gmail threads, tickets, CRM records, etc.) where you already have the text, IDs, metadata, and relations, sent as the app_knowledge multipart field (JSON string)

For user-specific context (preferences, conversations), use POST /memories/add_memory instead.

Endpoint

• Auth: Bearer token
• Content type: multipart/form-data (always – even when sending only app_knowledge)
• Idempotency: Controlled by upsert (default true – overwrites existing items with the same ID)
• Async: Yes – returns 200 with a JSON body (SourceUploadResponse in OpenAPI) including one source_id per queued item. Use POST /ingestion/verify_processing to check status.

The interactive Try it panel is generated from api-reference/openapi.json and uses the multipart field name app_knowledge, matching the OpenAPI spec.

Two ingestion paths

This endpoint accepts two content formats in one request. Send either or both:

Path	Form field	Content type
Files	files (binary) + optional file_metadata (JSON string)	Documents to be parsed
App sources	app_knowledge (JSON string)	Pre-parsed app content with metadata

Example: Upload files

cURL

curl -X POST 'https://api.hydradb.com/ingestion/upload_knowledge' \
  -H "Authorization: Bearer <your_api_key>" \
  -F "tenant_id=my_first_tenant" \
  -F "files=@/path/to/contract.pdf" \
  -F "files=@/path/to/policy.pdf" \
  -F 'file_metadata=[
    { "file_id": "contract_q4", "metadata": { "category": "legal" } },
    { "file_id": "policy_2025", "metadata": { "category": "legal" } }
  ]'

Example: Upload app knowledge

cURL

curl -X POST 'https://api.hydradb.com/ingestion/upload_knowledge' \
  -H "Authorization: Bearer <your_api_key>" \
  -F "tenant_id=my_first_tenant" \
  -F 'app_knowledge=[
    {
      "tenant_id": "my_first_tenant",
      "sub_tenant_id": "my_first_tenant",
      "id": "slack_msg_12345",
      "title": "Q4 planning standup notes",
      "type": "slack",
      "url": "https://acme.slack.com/archives/C01/p1234567890",
      "timestamp": "2025-10-15T14:30:00Z",
      "kind": "message",
      "provider": "slack",
      "external_id": "1234567890.000100",
      "fields": {
        "kind": "message",
        "body": "Today we discussed the Q4 roadmap...",
        "author": "alex",
        "thread_id": "1234567890.000100",
        "url": "https://acme.slack.com/archives/C01/p1234567890"
      },
      "metadata": {
        "container_type": "channel",
        "container_id": "C01",
        "container_name": "planning",
        "category": "engineering"
      },
      "attachments": [
        {
          "id": "att-1",
          "title": "roadmap-notes.txt",
          "content_type": "text/plain",
          "content": { "text": "Attached notes mention owners for the Q4 roadmap." }
        }
      ]
    }
  ]'

Form fields

Name	Type	Required	Default	Description
tenant_id	string	Yes	–	The tenant to ingest into.
files	binary[]	One of	[]	One or more files to upload.
file_metadata	JSON string	No	–	Array of metadata objects, one per file. Length must match files. See File metadata.
app_knowledge	JSON string	One of	–	A single app source object or an array. Each item must include tenant_id and sub_tenant_id. See App knowledge.
app_sources	JSON string	-	–	Deprecated alias for app_knowledge. Use app_knowledge instead.
sub_tenant_id	string	No	the tenant_id value	Sub-tenant scope. When omitted, content is stored under the default sub-tenant, which is the tenant_id value - not the literal string "default".
upsert	boolean	No	true	If true, existing sources with the same ID are overwritten.

You must provide at least one of files or app_knowledge. You can send both in the same request.

File metadata

Each entry in file_metadata corresponds to the file at the same index in files:

Field	Type	Description
file_id	string	Optional. Server-generated if omitted. Use this to reference the file later (e.g., for verify_processing).
metadata	object	Tenant-level metadata. Pre-filterable in recall via top-level keys in metadata_filters (fast). Each key must be declared in tenant_metadata_schema with enable_match: true.
additional_metadata	object	Document-level metadata. Filterable in recall by nesting under "additional_metadata" (canonical) or "document_metadata" (legacy alias) inside metadata_filters. Post-retrieval, so slower than tenant-level filters (engine over-fetches ~3x to compensate). See Full recall → Metadata filters.
relations	object	Forcefully connect this file to other sources. See Forceful relations.

App knowledge

Each item in the app_knowledge JSON array represents a single piece of pre-parsed content. tenant_id and sub_tenant_id are required inside each item.

For app-aware retrieval, include the typed app-source fields below. See App Sources for field-by-field guidance, relation examples, and search behavior.

Field	Type	Description
tenant_id	string	Required. The tenant to ingest into.
sub_tenant_id	string	Required. Sub-tenant scope. If not partitioning by user, use the same value as tenant_id - that is the default sub-tenant an omitted sub_tenant_id resolves to on queries. Do not use the literal string "default"; it creates a separate scope that omitted-scope queries will never match.
id	string	Required. Unique identifier for the source.
title	string	Short title or subject.
type	string	Source category (e.g., slack, notion, gmail, webpage).
description	string	Optional long-form description.
url	string	Canonical URL or reference link.
timestamp	string	ISO-8601 timestamp (creation or last-updated).
content	object	Legacy/generic content payload. For typed app sources, prefer fields for item text. See Content formats.
metadata	object	Tenant-level or app-specific metadata. Use this for category, channel, project, space, workspace, or other provider context. Filterable at recall via top-level keys in metadata_filters.
additional_metadata	object	Document-level metadata. Stored per-source. Filterable at recall by nesting under "additional_metadata" (canonical) or "document_metadata" (legacy alias) in metadata_filters. Post-retrieval (the engine over-fetches and filters). See Full recall → Metadata filters.
relations	array	Typed app-source relations such as reply_to, child_of, linked_to, or blocks.
kind	string	App object kind: email, message, ticket, knowledge_base, or custom.
provider	string	Provider namespace such as slack, gmail, jira, notion, or salesforce.
external_id	string	Stable provider ID for this source. Used for exact ID search and relation resolution.
fields	object	Kind-specific structured fields. Include kind inside this object.
attachments	array	Attachments connected to this app source. Include content.text or content.markdown when you already have extracted attachment text.
comments	array	Comments connected to this app source.

If your data comes from an app, prefer the typed app-source fields over flattening everything into Markdown. Structured IDs and relations let search_apps: true use graph expansion and exact provider IDs during Recall.

Content formats

For typed app sources, primary searchable text belongs in fields, such as fields.body for messages/emails or fields.description for tickets. The top-level content object remains available for legacy or untyped app knowledge payloads.

The content object supports multiple content types. Use the field that matches your source - only one needs to be set:

Field	Use for
text	Plain text content
markdown	Markdown-formatted content
html_base64	Base64-encoded HTML
csv_base64	Base64-encoded CSV

{ "content": { "text": "Plain text content." } }

Attachment objects can also include a content object. HydraDB indexes attachments[].content.text and, when text is omitted, attachments[].content.markdown; attachment URLs and titles are metadata and are not fetched or parsed automatically.

Response

{
  "success": true,
  "message": "Upload initiated successfully",
  "results": [
    {
      "source_id": "ef3ea754019855e2b39e9ab5c2d26096",
      "filename": "contract.pdf",
      "status": "queued",
      "error": null
    },
    {
      "source_id": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
      "filename": "policy.pdf",
      "status": "queued",
      "error": null
    }
  ],
  "success_count": 2,
  "failed_count": 0
}

Field	Description
success	true if at least one item was queued.
message	Human-readable status.
results[]	Per-item upload result.
results[].source_id	The ID assigned to this source. Use this for verify_processing and downstream operations.
results[].filename	Original filename (for files) or null (for app knowledge payloads).
results[].status	Initial status. Always queued on a successful response.
success_count / failed_count	Aggregate counts across the request.

Behavior notes

Processing is asynchronous. This endpoint returns once items are queued. Use POST /ingestion/verify_processing with the returned source_ids to check when content is fully indexed.

Always use multipart form data. Even if you’re sending only app_knowledge (no files), the endpoint expects multipart/form-data. Sending JSON directly will return 422 VALIDATION_ERROR.

file_metadata and app_knowledge are JSON strings. Both must be serialized before being sent as form fields. Most HTTP libraries don’t auto-stringify nested JSON in multipart bodies.

Related endpoints

• Next: Verify processing – poll for ingestion status
• Next: Full recall – retrieve ingested content
• Alternative: Add memory – for user memories instead of knowledge
• Related: Delete knowledge – remove sources

Errors

Common codes: 400 INVALID_PARAMETERS, 404 TENANT_NOT_FOUND, 422 VALIDATION_ERROR. See Error Responses for the full list.

Read more: Essentials → Memories · Essentials → Metadata

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

tenant_id · string · required

Unique identifier for the tenant/organization

Example:

"tenant_1234"

sub_tenant_id · string · default: ""

Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.

Example:

"sub_tenant_4567"

upsert · boolean · default: true

If true, update existing sources with the same id.

Example:

true

files · file[]

Files to upload (documents). Omit or leave empty when only sending app_knowledge.

file_metadata · string | null

JSON array of file metadata objects; length must match files when provided. Each object may include: file_id (optional), metadata, additional_metadata, and relations (forceful relations to other HydraDB source IDs).

app_knowledge · string | null

JSON: single source object or array of app-generated sources to index. Omit when only uploading files.

Response

200

application/json

Successful Response

success · boolean · default: true

Example:

true

message · string · default: Upload initiated successfully

results · SourceUploadResultItem · object[]

List of upload results for each source.

Show child attributes

Example:

[]

success_count · integer · default: 0

Number of sources successfully queued.

Example:

1

failed_count · integer · default: 0

Number of sources that failed to upload.

Example:

1