API Reference

Authentication

The SDK authenticates with an API key generated when you create an Instance in the Synap Dashboard. One key per Instance; rotate or revoke at any time.

Never expose your API key in client-side code, public repositories, or browser requests. API keys should only be used in server-side environments.

See Authentication for a detailed walkthrough of API key generation and the credential lifecycle.

SDK versioning

The SDK and the underlying wire protocol are versioned. Non-breaking additions (new fields, new optional parameters) may be added within a major version without notice. Breaking changes ship in new major versions of the SDK; the upgrade path is documented in the Changelog.

Pagination

List methods on the SDK return paginated results. Pass page and page_size to control the window:

integer

Page number to retrieve. Defaults to 1.

integer

Number of items per page. Defaults to 20. Maximum 100.

Returned objects include both the data and the pagination envelope:

result = await sdk.memories.list(page=1, page_size=20)

result.data          # list of memory records
result.page          # 1
result.page_size     # 20
result.total         # 42
result.total_pages   # 3

Rate Limiting

Requests are rate-limited per API key. When the limit is exceeded, the SDK raises RateLimitError. Tier limits:

Tier	Requests per minute	Burst
Free	60	10
Pro	600	50
Enterprise	Custom	Custom

The SDK automatically retries with exponential backoff on rate-limit errors. You can read the limits from the exception:

try:
    await sdk.memories.create(...)
except RateLimitError as e:
    print(e.limit)         # 60
    print(e.remaining)     # 0
    print(e.retry_after)   # seconds to wait

Correlation IDs

Every SDK call records a correlation ID: a unique identifier propagated through the full request lifecycle, including background jobs like ingestion. Access it from any SDK response:

result = await sdk.memories.create(...)
print(result.correlation_id)  # "req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c"

Always include the correlation_id when contacting support. It allows the team to trace the exact request path and identify issues quickly.

Error handling

The SDK raises typed exceptions for different failure classes. Each exception exposes a code (machine-readable), a message (human-readable), and a details object with context:

from maximem_synap import (
    SynapError,
    AuthenticationError,
    InvalidInputError,
    ContextNotFoundError,
    RateLimitError,
    ServiceUnavailableError,
)

try:
    await sdk.memories.get("mem_nonexistent")
except ContextNotFoundError as e:
    print(e.code)      # machine-readable code from the server
    print(e.message)   # human-readable description
    print(e.details)   # additional context (e.g., the missing id)

All SDK exceptions inherit from SynapError and split into two branches: SynapTransientError (the SDK auto-retries) and SynapPermanentError (your code must handle). Common exceptions:

Exception	Branch	When raised
`AuthenticationError`	Permanent	API key missing, invalid, or revoked
`InvalidInputError`	Permanent	Request parameters invalid or missing required fields (see `details`)
`InvalidInstanceIdError`	Permanent	Subtype of `InvalidInputError`. A malformed `instance_id` (not `inst_` + 16 hex) is raised by the constructor, client-side; an unknown one comes back as `InvalidInputError` from the server. Catching the parent handles both
`InvalidConversationIdError`	Permanent	Subtype of `InvalidInputError` for a malformed `conversation_id`: currently surfaced as `InvalidInputError`; catch the parent
`ContextNotFoundError`	Permanent	Requested instance, conversation, or memory does not exist
`SessionExpiredError`	Permanent	Session expired; re-authenticate
`InsufficientCreditsError`	Permanent	Wallet has insufficient credits for this operation
`ListeningAlreadyActiveError`	Permanent	`instance.listen()` called while another stream is open
`ListeningNotActiveError`	Permanent	`instance.send_message()` called without an active stream
`RateLimitError`	Transient	Rate limit exceeded: SDK auto-retries with backoff
`NetworkTimeoutError`	Transient	Request timed out: SDK auto-retries with backoff
`ServiceUnavailableError`	Transient	Synap temporarily unavailable: SDK auto-retries with backoff
`AgentUnavailableError`	Transient	Internal agent unavailable: SDK auto-retries with backoff

For the full hierarchy and per-exception handling guidance, see Error Handling. For wire-level error codes (when interpreting the server’s code field), see Error Codes.

SDK installation

The official Python SDK is the primary customer interface.

pip install maximem-synap

poetry add maximem-synap

uv add maximem-synap
# pip-compatible (existing venv): uv pip install maximem-synap

import uuid
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(
    api_key="synap_your_key_here"
)

await sdk.initialize()

# All SDK methods are async
# conversation_id must be a valid UUID
context = await sdk.conversation.context.fetch(
    conversation_id=str(uuid.uuid4()),
    search_query=["user preferences"]
)

A JavaScript/TypeScript SDK is also available for Node.js environments:

npm install @maximem/synap-js-sdk

From @maximem/synap-js-sdk 0.3.0 the JavaScript client mirrors this namespaced API one-to-one (sdk.conversation.record_message(), sdk.conversation.context.get_context_for_prompt(), sdk.memories.create(), sdk.fetch(), and sdk.{user,customer,client}.context.fetch()) while keeping the flat methods (sdk.addMemory(), sdk.fetchUserContext()) alongside them. See JavaScript / TypeScript SDK.

The JavaScript SDK is a thin Node.js wrapper around the Python SDK and requires a Python 3.11+ runtime on the host. Edge Runtime, Cloudflare Workers, Deno Deploy, and AWS Lambda Node-only runtimes are not supported on the JS SDK. Those platforms need a separate backend with Python 3.11+. See Installation → JavaScript / TypeScript SDK.

See the Installation guide for full setup instructions for both SDKs.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

User profile

Real-time streaming

Cache management

Credits & billing

Reference

Limits & Pricing

Authentication

SDK versioning

Rate Limiting

Correlation IDs

Error handling

SDK installation

​Authentication

​SDK versioning

​Pagination

​Rate Limiting

​Correlation IDs

​Error handling

​SDK installation

Authentication

SDK versioning

Pagination

Rate Limiting

Correlation IDs

Error handling

SDK installation