ingestion_id you can poll via memories.status().
Key options
Onlydocument is required. These are the options that change what happens to it:
Parameters
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).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.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.Timestamp of when the document was originally created. Used for temporal ordering of memories. Defaults to the current time if not provided.
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).
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.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.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.
Unique identifier for tracking this ingestion job. Pass this to
memories.status or memories.wait_for_completion.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_typeormodeis 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 adocument_typeormodethat is not one of the values above, and in both SDKs acustomer_idpassed on a B2C instance (CustomerIdNotAcceptedError, a subclass).