Skip to main content
REST One HTTPS request. Works in serverless functions (Python, or Node 20+ for JavaScript and TypeScript). Ingest a document into Synap’s memory pipeline. The document is processed asynchronously through the extraction, categorization, entity resolution, and storage stages. The call returns immediately with an ingestion_id you can poll via memories.status().

Key options

Only document is required. These are the options that change what happens to it:

Parameters

string
required
The raw document content to ingest. This can be a conversation transcript, a knowledge base article, a support ticket, or any text content. Must not be empty (InvalidInputError).
string
default:"ai-chat-conversation"
The type of document being ingested. This determines how the ingestion pipeline processes the content. Defaults to ai-chat-conversation.In Python, any other value raises ValueError before anything is sent.
string
Your own id for this document, returned as document_id. If you omit it, Synap generates one.It is a label, not a duplicate check. Duplicates are caught by content instead: sending the same content again for the same user and customer in the same instance within 7 days returns the first ingestion’s ingestion_id and document_id, whatever id you pass. New content sent with an id you used before is ingested as a new document.
datetime
Timestamp of when the document was originally created. Used for temporal ordering of memories. Defaults to the current time if not provided.
Always provide document_created_at when backfilling historical data. Accurate timestamps improve temporal reasoning during retrieval (e.g., “What did the user say last month?”).
string
The external user ID this memory is about. Omit for customer- or client-scope ingestion.
string
The external customer ID this memory belongs to. Required on B2B. Not accepted on B2C: passing it is rejected with HTTP 400. See B2C vs B2B. Omit for client-scope ingestion, and omit it always on a B2C instance. The effective scope is derived by the server from the IDs you pass and the instance’s user-context isolation (B2C/B2B).
dict[str, str]
The level of your scope ladder this memory belongs to, named in full: one entry per level, from the top down to it. For example {"customer": "acme", "team": "payments", "user": "dana"}.Only needed when your ladder has a level between customer and user. user_id and customer_id cannot say which of those levels a write belongs to, so on such a ladder Synap refuses the write rather than guessing. Omit it otherwise. Sending it to an instance without nested scoping is an error, not ignored: ignoring it would widen a write you asked to narrow.Python 0.4.8 and later. JavaScript and TypeScript 0.4.7 and later, as scope.
string
default:"long-range"
The ingestion mode: long-range (the default) or fast. The server accepts either value, but in the current release both run the same ingestion pipeline, so the choice does not change what is extracted or how fast. See Types and enums. It is separate from the retrieval mode (fast or accurate) on context fetches; see Retrieval modes.In Python, any other value raises ValueError before anything is sent. In JavaScript and TypeScript it raises InvalidInputError.
object
Arbitrary key-value pairs to attach to the memory. Useful for filtering and organizing memories.

Returns

CreateMemoryResponse with the ingestion job identifiers and initial status.
UUID
Unique identifier for tracking this ingestion job. Pass this to memories.status or memories.wait_for_completion.
string
The document identifier (either the one you supplied or one generated by the server).
string
Initial status of the ingestion job. Always queued for new submissions.
datetime
Server timestamp at which the job was accepted into the queue.

Example

Ingestion is asynchronous. A successful return means the document has been accepted for processing, not that extraction is complete. Use memories.status or memories.wait_for_completion to track progress.

Raises

  • AuthenticationError: the API key is missing or invalid, or (Python) initialize() has not been called. JavaScript and TypeScript resolve identity on the first call instead.
  • ValueError (Python, before anything is sent): document_type or mode is not one of the values above.
  • InvalidInputError: Synap rejected the request (HTTP 400 or 422), or the SDK refused it before sending: in JavaScript and TypeScript a document_type or mode that is not one of the values above, and in both SDKs a customer_id passed on a B2C instance (CustomerIdNotAcceptedError, a subclass).
Credit, rate-limit and network errors are the same on every call: see Error codes.

See also