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. The exception carries the server’s Retry-After:

try:
    await sdk.memories.create(...)
except RateLimitError as e:
    print(e.retry_after_seconds)   # seconds to wait, or None

Correlation IDs

Every SDK call records a correlation ID: a unique identifier propagated through the full request lifecycle, including background jobs like ingestion. Read it from a context response’s metadata, or from any Synap error:

context = await sdk.user.context.fetch(user_id="user_123")
print(context.metadata.correlation_id)  # "req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c"

const context = await sdk.user.context.fetch({
  user_id: 'user_123',
});
console.log(context.metadata?.correlation_id);  // "req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c"

const context = await sdk.user.context.fetch({
  user_id: 'user_123',
});
console.log(context.metadata?.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)                  # human-readable description
    print(e.correlation_id)   # server-side request id, for support

import { AuthenticationError, ContextNotFoundError, InvalidInputError, RateLimitError, ServiceUnavailableError, SynapError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.memories.get('mem_nonexistent');
} catch (e) {
  if (!(e instanceof ContextNotFoundError)) throw e;
  console.log(e.code);           // stable machine-readable code
  console.log(e.message);        // human-readable description
  console.log(e.correlationId);  // server-side request id, for support
}

import { AuthenticationError, ContextNotFoundError, InvalidInputError, RateLimitError, ServiceUnavailableError, SynapError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.memories.get('mem_nonexistent');
} catch (e) {
  if (!(e instanceof ContextNotFoundError)) throw e;
  console.log(e.code);           // stable machine-readable code
  console.log(e.message);        // human-readable description
  console.log(e.correlationId);  // server-side request id, for support
}

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
`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"]
)

import { randomUUID } from 'node:crypto';
import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient({ apiKey: 'synap_your_key_here' });

await sdk.initialize();

// All SDK methods are async
// conversation_id must be a valid UUID
const context = await sdk.conversation.context.fetch({
  conversation_id: randomUUID(),
  search_query: ['user preferences'],
});

import { randomUUID } from 'node:crypto';
import { SynapClient } from '@maximem/synap-js-sdk';

const sdk = new SynapClient({ apiKey: 'synap_your_key_here' });

await sdk.initialize();

// All SDK methods are async
// conversation_id must be a valid UUID
const context = await sdk.conversation.context.fetch({
  conversation_id: randomUUID(),
  search_query: ['user preferences'],
});

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

npm install @maximem/synap-js-sdk

The JavaScript client mirrors this namespaced API one to one, and keeps a flat JavaScript-idiomatic surface alongside it. See JavaScript and TypeScript SDK.

Reading these examples in JavaScript or TypeScript

The examples throughout this reference are written in Python. They translate mechanically, because the two SDKs share namespaces, method names and field names exactly. Two differences, and that is all:

Python passes keyword arguments; JavaScript passes one options object.
Python’s MaximemSynapSDK() is JavaScript’s new SynapClient(), and its initialize() / shutdown() are spelled the same.

sdk = MaximemSynapSDK(api_key=API_KEY)
await sdk.initialize()

await sdk.memories.create(
    document="The customer prefers window seats.",
    user_id="user-123",
    customer_id="customer-456",
)

context = await sdk.user.context.fetch(
    user_id="user-123",
    search_query=["seat preference"],
    max_results=10,
)

const synap = new SynapClient({ apiKey: API_KEY });
await synap.initialize();

await synap.memories.create({
  document: "The customer prefers window seats.",
  user_id: "user-123",
  customer_id: "customer-456",
});

const context = await synap.user.context.fetch({
  user_id: "user-123",
  search_query: ["seat preference"],
  max_results: 10,
});

Field names stay snake_case in JavaScript on the namespaced surface, so a Python example’s argument names can be copied across unchanged. The flat surface (fetchUserContext, searchMemory) is the exception: it returns the normalised camelCase shape. Pick one style per codebase.

The JavaScript SDK is a native Node.js client requiring Node.js 20+. Context and memory operations run on Node, Vercel Edge, Cloudflare Workers and the browser. The optional anticipation stream needs raw TCP and so is Node only. See Installation → JavaScript and 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

Reading these examples in JavaScript or TypeScript

​Authentication

​SDK versioning

​Pagination

​Rate Limiting

​Correlation IDs

​Error handling

​SDK installation

​Reading these examples in JavaScript or TypeScript

Authentication

SDK versioning

Pagination

Rate Limiting

Correlation IDs

Error handling

SDK installation

Reading these examples in JavaScript or TypeScript