Ingestion - Overview - HydraDB SDK

Lifecycle

Endpoint reference

Endpoint	Method	Purpose	Async?
`/ingestion/upload_knowledge`	`POST`	Ingest files and/or app sources	Yes
`/ingestion/verify_processing`	`POST`	Check processing status	No

For user memories, see POST /memories/add_memory.

Which endpoint should I use?

Content	Endpoint
PDFs, DOCX, CSVs, and other files HydraDB should parse	`/ingestion/upload_knowledge` (`files`)
Slack messages, Notion pages, Gmail threads, webpages with pre-extracted text	`/ingestion/upload_knowledge` (`app_knowledge`)
User preferences, conversation history, inline notes	`/memories/add_memory`

Typical call sequence

POST /ingestion/upload_knowledge   → returns source_ids, status: queued
POST /ingestion/verify_processing  → poll until status: completed
POST /recall/full_recall           → content is now retrievable

For batched uploads with mixed content:

1. POST /ingestion/upload_knowledge with files=[...] AND app_knowledge=[...]
   → single request, multiple source_ids in response
2. POST /ingestion/verify_processing with all source_ids
   → check all statuses in one call

Status pipeline

Status	Searchable?
`queued`	No
`processing`	No
`graph_creation`	Yes – via `full_recall` and `recall_preferences`
`completed`	Yes – via all recall endpoints, with full graph context
`errored`	No – inspect `error_code` and `message` on the status object (OpenAPI `ProcessingStatus`)

Items in graph_creation are already retrievable. Wait for completed only when you specifically need full graph traversal.

Key concepts

Source – Any unit of ingested content. Files become sources, app knowledge payloads become sources, memory items become sources. Each gets a unique source_id. Files vs app knowledge – Files require parsing (HydraDB extracts text, layout, metadata). App knowledge items arrive pre-parsed – you supply the text and structured metadata directly in the app_knowledge multipart field. Multipart form data – /ingestion/upload_knowledge always uses multipart/form-data, even when sending only app_knowledge (no actual files). Nested JSON fields (file_metadata, app_knowledge) must be sent as JSON-stringified form values. Upsert – By default, ingesting a source with an existing ID overwrites the previous version. Set upsert: false to fail instead. Forceful relations – At ingestion time, you can declare relationships between sources via the relations field. These are surfaced in thinking-mode recall as additional_context.

Essentials → Memories – memories vs knowledge, when to use which
Essentials → Metadata – tenant-level vs document-level metadata
Essentials → Forceful Relations – linking sources at ingestion
API Reference → Recall – retrieve ingested content

API Documentation

Tenants

Knowledge & Memories

Recall

Managing Data

Ingestion - Overview

Lifecycle

Endpoint reference

Which endpoint should I use?

Typical call sequence

Status pipeline

Key concepts

​Lifecycle

​Endpoint reference

​Which endpoint should I use?

​Typical call sequence

​Status pipeline

​Key concepts

​Related sections

Lifecycle

Endpoint reference

Which endpoint should I use?

Typical call sequence

Status pipeline

Key concepts

Related sections