Skip to main content
REST One HTTPS upload. Works in any Python or Node 20+ process, including serverless functions. Ingest a file or raw text into the memory pipeline. Use this when you want Synap to upload and parse a document (PDF, text file, transcript, etc.) rather than passing a string directly. Exactly one of file_path, file, or text must be provided.

Parameters

string
required
The user this memory is about.
string
The customer this memory belongs to. Optional in the signature, but required on B2B: an upload without it is refused with InvalidInputError (HTTP 400). Not accepted on B2C: leave it out, and the SDK sends no customer field. Passing one there raises CustomerIdNotAcceptedError, a subclass of InvalidInputError, before anything is sent (TypeScript SDK 0.5.14 and earlier sent a customer field even when you left it out; use 0.5.15 or later). See B2C vs B2B.
string
Scope hint for the upload. One of "b2c" (default) or "b2b".
string
Path on disk to read and upload. Mutually exclusive with file and text.
IO[bytes]
An open binary file-like object. When using this, you must also pass filename. Mutually exclusive with file_path and text.
string
Name to use for the upload. Required when passing file=.
string
Raw text content to ingest instead of a file. Mutually exclusive with file_path and file.
string
Override the auto-detected document type (for example, "pdf", "email", "meeting-transcript").
string
Ingestion mode: "long-range" (default) or "fast". Neither SDK nor the server checks the value, and both run the same pipeline today. See Types and enums.
object
Additional metadata to attach to the memory. Serialized to JSON before upload.
object
Only for a scope ladder with a level between customer and user: the full path down to the user, as a flat map of level key to id, for example {"customer": "acme", "team": "payments", "user": "user_123"}. Omit it on the default ladder. Sent as a JSON form field. Requires Python SDK 0.5.16 or later and TypeScript SDK 0.5.15 or later. See Scope paths.

Returns

CreateMemoryResponse with the ingestion job identifiers and initial status.
UUID
Unique identifier for tracking this ingestion job.
string
The document identifier assigned to the upload.
string
Initial status of the ingestion job. Typically queued.
datetime
Timestamp at which the job was accepted into the queue.

Example

Raises

  • InvalidInputError, before anything is sent: none, or more than one, of file_path, file and text, or no user_id (Python 0.5.22 and later; earlier Python raised ValueError).
  • CustomerIdNotAcceptedError, a subclass of InvalidInputError, before anything is sent: a customer_id on a B2C instance.
  • AuthenticationError: the API key is missing or invalid, or (Python) initialize() has not been called.
  • InvalidInputError: Synap rejected the upload (HTTP 400 or 422), for example a B2B upload without customer_id.

See also