Skip to main content
POST
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:

Form 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 returns 415.
  • 202 Accepted means queued, not indexed: 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 graph_creation (searchable), completed, or errored. Alternatively, register a webhook for indexing.status_changed events (see Webhooks).
  • Memory and knowledge: Use type: "memory" for memory ingestion, listing, and deletion. Use type: "all" on POST /query when results should combine both.

Supported file formats

Each file in documents 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.
HydraDB accepts these formats through documents:What HydraDB extracts differs by type:Files with no readable text fail with E2002. Upload a version containing text.

Unsupported formats

Use the file’s real extension. When the filename has no extension, HydraDB uses the part’s 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 returns 202 as usual. The rejected file comes back with status: "failed" and error_code: "E1002", and every other file is queued normally:
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 in document_metadata, app_knowledge, and memories share three fields. The per-type tables under Examples and item fields list only what differs. See Metadata Filters for choosing metadata fields and filtering on them, and metadata size limits for how HydraDB measures the caps.

Examples and item fields

Those seven, plus the deprecated aliases 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.
If you already have text in memory, create a file-like object and upload it through documents as a text/plain .txt file.
Sources keyed in graph_payload are still chunked and embedded, so they stay searchable. See Bring Your Own Graph for the full guide.
Caps per graph: at most 5,000 entities, 10,000 relations, and 500 relations per entity; over-cap returns 400. Graphs survive re-ingest: a re-upload or connector re-sync re-applies the stored graph.
  • 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

Authorization
string
header
required

Send your API key as Authorization: Bearer <your_api_key>.

Body

multipart/form-data

A multipart form containing the database, collection and content to ingest.

database
string
required

Database to write to. Required.

collection
string

Collection to write to. Omit it to use the database's default collection.

document_metadata
string

Per-file metadata for uploaded documents, encoded as JSON.

documents
file[]

Files to ingest into the knowledge corpus.

graph_payload
string

Your own graph, encoded as JSON and keyed by source ID.

memories
string

Memories to ingest, encoded as a JSON array. Use type=memory.

sub_tenant_id
string
deprecated

Deprecated: use collection.

tenant_id
string
deprecated

Deprecated: use database.

type
enum<string>

Corpus to ingest into, knowledge or memory.

Available options:
knowledge,
memory
upsert
string
default:true

Default upsert for every context: replace an existing context with the same context_id. One of true, false, 1 or 0; default true.

Response

Accepted

data
IngestionV2IngestResponse · object
Example:
error
HandlerApiError · object | null

Error details on failure, or null on success.

Example:

null

meta
HandlerResponseMeta · object
Example:
success
boolean

Whether the request succeeded.

Example:

true