Skip to main content
POST
When context is of type=knowledge:
  1. Documents - Use the documents field for binary uploads (PDF, DOCX, CSV, MD, TXT) that HydraDB should parse.
  2. App Sources - Use app_knowledge for pre-extracted JSON content (Slack threads, Notion pages, emails, tickets). Read more about ingesting knowledge from your apps.
When context is of type=memory Use memories for per-user content, scoped with collection. Set infer: true to let HydraDB extract preferences from raw signals, or infer: false to store the text verbatim. Read more about ingesting memories.
database and collection are the current field names (formerly tenant_id and sub_tenant_id). The old names remain accepted as deprecated aliases for full backward compatibility.

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.

Important form fields

  1. id must not contain a comma (,). The comma is reserved as the id separator on Ingestion Status (GET /context/status?ids=a,b), so an id containing a comma cannot be looked up unambiguously. This applies to every id you supply — document_metadata, app_knowledge, and memories items. Ingesting an item whose id contains a comma is rejected with a 400.
  2. 202 Accepted means queued, not indexed. Ingestion is asynchronous. A successful response only confirms your sources were accepted, not that they are ready to query. Before querying, poll GET /context/status with the returned IDs until each source reaches completed or errored. Alternatively, register a webhook for indexing.status_changed events (see Webhooks).

Common use-cases and their configurations

Document metadata

Per-document metadata (id, metadata, additional_metadata, title, etc.) can be passed alongside each uploaded document to control indexing, filtering, and display. See the field reference below.
graph_payload is a map of source id → graph that replaces LLM graph extraction for each keyed source. For type=knowledge, the key is a document_metadata id or an app_knowledge item id; for type=memory, the key is a memory id. Keyed sources are still chunked and embedded, so they stay searchable. See Bring Your Own Graph for the full guide.
Per-source replace mode. Each top-level key must match a document_metadata id or app_knowledge item id for type=knowledge, or a memory id for type=memory, in the same request; attach graphs to multiple sources at once. Extraction is skipped for keyed sources. Caps per graph: ≤ 5,000 entities, ≤ 10,000 relations, ≤ 500 relations per entity; over-cap returns 400. Graphs survive re-ingest (re-upload or connector re-sync re-applies the stored graph).

Some important notes

  • Async indexing. 202 Accepted means HydraDB queued the work, not that content is searchable. Poll Ingestion Status until indexing_status reaches graph_creation (searchable) or completed (graph-ready).
  • Multipart, not JSON. This endpoint uses multipart/form-data. Stringify all JSON arrays (metadata, app_knowledge, memories) before placing them in the form field.
  • Declare hot schema fields upfront. Put frequently filtered fields in metadata, define them in database_metadata_schema with enable_match: true, and use additional_metadata for free-form display/bookkeeping fields. Define filterable fields when creating the database via Create Database. Additive schema updates exist, but newly added dense/sparse metadata lanes are not backfilled into existing Milvus collections.
  • Memory vs knowledge. Use type: "memory" for memory ingestion, listing, and deletion. Use type: "all" on POST /query when results should combine both. The multipart field name for memories is always memories.
  • Collection defaulting. Omitting collection writes to the default collection. List available collections with List Collections.
Related Resources

Authorizations

Authorization
string
header
required

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

Body

multipart/form-data

Content type: 'knowledge' or 'memory' | Database (canonical name for the tenant scope) | Collection (canonical name for the sub-tenant scope) | Deprecated alias for database | Deprecated alias for collection | Upsert existing content (true/false/1/0) | Knowledge files to ingest (repeatable; type=knowledge) | Per-document metadata as a JSON array (type=knowledge) | App-knowledge items as a JSON array (type=knowledge) | Memory items as a JSON array (type=memory) | Optional bring-your-own-graph payload as JSON

database
string
required
app_knowledge
string
collection
string
document_metadata
string
documents
file
graph_payload
string
memories
string
sub_tenant_id
string
deprecated
tenant_id
string
deprecated
type
enum<string>
default:knowledge
Available options:
knowledge,
memory
upsert
string
default:true

Response

Accepted

data
object
Example:
error
object

Error message, empty string on success.

Example:
meta
object
Example:
success
boolean

Whether the request succeeded.

Example:

true