Skip to main content
For real-time conversation ingestion during agent interactions, use the Python SDK which provides a more ergonomic interface with automatic authentication, retries, and async support. The REST API is best suited for server-side batch operations and administrative tasks.

​
Create Memory

Ingest a document into Synap’s memory pipeline. The document is processed asynchronously through the extraction, categorization, entity resolution, and storage stages. 
POST /v1/memories

​
Request Body

​
document
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.
​
document_type
string
required
The type of document being ingested. This determines how the ingestion pipeline processes the content.
ValueDescription
ai-chat-conversationA conversation between a user and an AI assistant
documentA generic document or report
emailAn email message or thread
pdfPDF document content (text extracted)
imageImage descriptions or OCR text
audioAudio transcriptions
meeting-transcriptMeeting transcription content
human-chat-conversationA conversation between two or more humans (coming soon)
support-ticketA customer support ticket or thread (coming soon)
knowledge-articleA structured knowledge base article (coming soon)
noteA freeform note or annotation (coming soon)
​
document_id
string
An optional external identifier for deduplication. If a document with this ID has already been ingested, the request is rejected with a 409 Conflict.
​
document_created_at
string
ISO 8601 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?”).
​
user_id
string
The user ID to scope this memory to. Memories scoped to a user are only retrievable in that user’s context.
​
customer_id
string
The customer ID to scope this memory to. Provides a broader scope than user_id — all users within a customer can access customer-scoped memories.
​
mode
string
required
The ingestion processing mode.
ValueDescription
fastOptimized for speed. Uses lighter extraction models. Best for high-volume, real-time ingestion.
long-rangeOptimized for quality. Runs the full extraction pipeline including deep entity resolution, relationship mapping, and graph storage. Best for conversations and important documents.
​
metadata
object
Arbitrary key-value pairs to attach to the memory. Useful for filtering and organizing memories.

​
Response

​
ingestion_id
string
Unique identifier for tracking this ingestion job. Use this with the Ingestion Status endpoint.
​
status
string
Initial status of the ingestion job. Always queued for new submissions.

​
Example

curl -X POST "https://api.synap.maximem.ai/v1/memories" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "User: I just moved to San Francisco and I'\''m looking for a good coffee shop.\nAssistant: Welcome to SF! There are some great options. Do you prefer light or dark roasts?\nUser: Definitely light roasts. I'\''m also a big fan of pour-over.",
    "document_type": "ai-chat-conversation",
    "user_id": "user_789",
    "customer_id": "cust_456",
    "mode": "long-range",
    "metadata": {
      "conversation_id": "conv_abc",
      "source": "web-chat"
    }
  }'
Response (201 Created)
{
  "ingestion_id": "ing_7a8b9c0d1e2f3456",
  "status": "queued"
}
Ingestion is asynchronous. A 201 response means the document has been accepted for processing, not that extraction is complete. Use the Ingestion Status endpoint or webhooks to track progress.

​
Batch Create Memories

Ingest multiple documents in a single request. This is the primary endpoint for bootstrap ingestion — loading historical conversations, backfilling knowledge bases, and migrating data from other systems. Each document is processed independently through the ingestion pipeline. 
POST /v1/memories/batch

​
Request Body

​
documents
array
required
Array of document objects. Each object has the same schema as the Create Memory request body.
​
fail_fast
boolean
If true, the entire batch is rejected if any single document fails validation. If false (default), valid documents are accepted and invalid ones are returned in the errors array.

​
Response

​
results
array
Array of successfully queued ingestion results, each containing ingestion_id and status.
​
errors
array
Array of validation errors for documents that could not be accepted. Each error includes the document index, error code, and message.

​
Example

curl -X POST "https://api.synap.maximem.ai/v1/memories/batch" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "document": "User: My favorite color is blue.\nAssistant: Noted!",
        "document_type": "ai-chat-conversation",
        "user_id": "user_789",
        "mode": "fast"
      },
      {
        "document": "User: I work at Acme Corp as a senior engineer.",
        "document_type": "ai-chat-conversation",
        "user_id": "user_789",
        "mode": "fast"
      }
    ],
    "fail_fast": false
  }'
Response
{
  "results": [
    { "ingestion_id": "ing_1a2b3c4d5e6f7890", "status": "queued" },
    { "ingestion_id": "ing_0a9b8c7d6e5f4321", "status": "queued" }
  ],
  "errors": []
}
Batch ingestion is more efficient than individual calls when you have multiple documents to process. The maximum batch size is 100 documents per request. For large-scale bootstrap operations, see the Bootstrap Ingestion guide.

​
Get Ingestion Status

Check the progress of an asynchronous ingestion job. 
GET /v1/memories/{ingestion_id}/status

​
Path Parameters

​
ingestion_id
string
required
The ingestion job ID returned from the create memory endpoint.

​
Response

​
ingestion_id
string
The ingestion job identifier.
​
status
string
Current status of the ingestion job.
ValueDescription
queuedDocument is waiting to be processed
processingDocument is currently being processed through the pipeline
completedAll extraction and storage stages completed successfully
failedProcessing failed. Check the errors field for details.
partial_successSome extractions succeeded but others failed. Check errors for details.
​
progress
object
Progress details for each pipeline stage.
​
errors
array
Array of error objects if any stage failed. Each contains stage, code, and message.

​
Example

curl -X GET "https://api.synap.maximem.ai/v1/memories/ing_7a8b9c0d1e2f3456/status" \
  -H "Authorization: Bearer synap_your_key_here"
Response
{
  "ingestion_id": "ing_7a8b9c0d1e2f3456",
  "status": "completed",
  "progress": {
    "extraction": "completed",
    "categorization": "completed",
    "entity_resolution": "completed",
    "storage": "completed"
  },
  "errors": []
}

​
Get Memory

Retrieve a specific memory by its ID. 
GET /v1/memories/{memory_id}

​
Path Parameters

​
memory_id
string
required
The memory ID. Format: mem_<hex>.

​
Response

​
id
string
Unique memory identifier.
​
type
string
Memory type: fact, preference, episode, emotion, temporal_event.
​
content
string
The extracted memory content.
​
confidence
number
Confidence score of the extraction, between 0.0 and 1.0.
​
entities
array
Array of resolved entities referenced in this memory.
​
scope
object
Scope information including user_id, customer_id, and client_id.
​
source
object
Source document information including ingestion_id, document_type, and document_created_at.
​
metadata
object
Metadata inherited from the source document.
​
created_at
string
ISO 8601 timestamp of when this memory was created.
​
updated_at
string
ISO 8601 timestamp of the last update. null if never updated.

​
Example

Response
{
  "id": "mem_a1b2c3d4e5f67890",
  "type": "preference",
  "content": "Prefers light roast coffee, especially pour-over method",
  "confidence": 0.92,
  "entities": [
    {
      "canonical_name": "San Francisco",
      "type": "location",
      "entity_id": "ent_sf001"
    }
  ],
  "scope": {
    "user_id": "user_789",
    "customer_id": "cust_456",
    "client_id": "cli_a1b2c3d4e5f67890"
  },
  "source": {
    "ingestion_id": "ing_7a8b9c0d1e2f3456",
    "document_type": "ai-chat-conversation",
    "document_created_at": "2025-01-15T10:30:00Z"
  },
  "metadata": {
    "conversation_id": "conv_abc",
    "source": "web-chat"
  },
  "created_at": "2025-01-15T10:31:00Z",
  "updated_at": null
}

​
Update Memory

Update an existing memory. The update behavior depends on the merge strategy. 
PATCH /v1/memories/{memory_id}

​
Path Parameters

​
memory_id
string
required
The memory ID to update.

​
Request Body

​
content
string
Updated memory content. Behavior depends on merge_strategy.
​
merge_strategy
string
How the update should be applied.
ValueDescription
replaceFully replace the existing memory content with the new content.
appendAppend the new content to the existing memory, preserving the original.
smart-mergeIntelligently merge new information with existing content, deduplicating and resolving conflicts by preferring the newer version.
​
confidence
number
Updated confidence score, between 0.0 and 1.0.
​
metadata
object
Updated metadata. Merged with existing metadata.

​
Response

Returns the updated memory object.

​
Example

curl -X PATCH "https://api.synap.maximem.ai/v1/memories/mem_a1b2c3d4e5f67890" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Prefers light roast coffee, especially pour-over method. Also enjoys cold brew in summer.",
    "merge_strategy": "smart-merge",
    "confidence": 0.95
  }'
Response
{
  "id": "mem_a1b2c3d4e5f67890",
  "type": "preference",
  "content": "Prefers light roast coffee, especially pour-over method. Also enjoys cold brew in summer.",
  "confidence": 0.95,
  "entities": [
    {
      "canonical_name": "San Francisco",
      "type": "location",
      "entity_id": "ent_sf001"
    }
  ],
  "scope": {
    "user_id": "user_789",
    "customer_id": "cust_456",
    "client_id": "cli_a1b2c3d4e5f67890"
  },
  "source": {
    "ingestion_id": "ing_7a8b9c0d1e2f3456",
    "document_type": "ai-chat-conversation",
    "document_created_at": "2025-01-15T10:30:00Z"
  },
  "metadata": {
    "conversation_id": "conv_abc",
    "source": "web-chat"
  },
  "created_at": "2025-01-15T10:31:00Z",
  "updated_at": "2025-01-15T16:45:00Z"
}

​
Delete Memory

Permanently delete a specific memory. 
DELETE /v1/memories/{memory_id}

​
Path Parameters

​
memory_id
string
required
The memory ID to delete.

​
Response

Returns 204 No Content on success with an empty body.

​
Example

curl -X DELETE "https://api.synap.maximem.ai/v1/memories/mem_a1b2c3d4e5f67890" \
  -H "Authorization: Bearer synap_your_key_here"
Memory deletion is permanent and cannot be undone. The memory is removed from both the vector store and graph store. Associated entity references are updated but not deleted.