> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> The Synap SDK provides programmatic access for **bootstrap ingestion**, **organizational and customer context retrieval**, and **data migration**. This page covers cross-cutting concerns you will encounter through the SDK: authentication, rate limits, error handling, correlation IDs, and pagination.

## Authentication

The SDK authenticates with an API key generated when you create an Instance in the [Synap Dashboard](https://synap.maximem.ai). One key per Instance; rotate or revoke at any time.

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

<Info>
  See [Authentication](/setup/authentication) for a detailed walkthrough of API key generation and the credential lifecycle.
</Info>

## 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](/resources/changelog).

## Pagination

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

<ParamField path="page" type="integer">
  Page number to retrieve. Defaults to `1`.
</ParamField>

<ParamField path="page_size" type="integer">
  Number of items per page. Defaults to `20`. Maximum `100`.
</ParamField>

Returned objects include both the data and the pagination envelope:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
result = await sdk.memories.create(...)
print(result.correlation_id)  # "req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c"
```

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

## 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:

```python theme={null}
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` for an unknown/malformed `instance_id`: currently surfaced as `InvalidInputError`; catch the parent |
| `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](/sdk/error-handling). For wire-level error codes (when interpreting the server's `code` field), see [Error Codes](/sdk-reference/errors).

## SDK installation

The official Python SDK is the primary customer interface.

<CodeGroup>
  ```bash pip theme={null}
  pip install maximem-synap
  ```

  ```bash poetry theme={null}
  poetry add maximem-synap
  ```

  ```bash uv theme={null}
  uv add maximem-synap
  # pip-compatible (existing venv): uv pip install maximem-synap
  ```
</CodeGroup>

```python theme={null}
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:

```bash theme={null}
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](/setup/installation#javascript-typescript-sdk).

<Note>
  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, Bun, 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](/setup/installation#javascript-typescript-sdk).
</Note>

<Info>
  See the [Installation](/setup/installation) guide for full setup instructions for both SDKs.
</Info>