Skip to main content
The API Reference covers operations typically used during setup, bulk loading, and administrative tasks. For real-time agent interactions (conversation ingestion, context fetch, compaction), use the Python SDK which handles authentication, retries, streaming, and the full agent loop automatically.

​
Authentication

Synap uses API key authentication for all REST API calls. Your API key is generated when you create an instance in the Synap Dashboard.
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 the bootstrap flow and credential lifecycle.

​
API Versioning

Synap uses URL-path versioning for SDK-facing endpoints and a separate namespace for dashboard operations:
PrefixPurposeExample
/v1/SDK and programmatic accessPOST /v1/memories
/dashboard/Dashboard and admin operationsGET /dashboard/instances
/instances/Instance-scoped configurationPOST /instances/{id}/memory-architecture/init
Breaking changes are introduced only in new API versions. Non-breaking additions (new fields, new optional parameters) may be added to existing versions without notice.

​
Request Format

All request bodies must be JSON with the Content-Type: application/json header.

​
Pagination

All list endpoints support cursor-based pagination with the following query parameters:
​
page
integer
Page number to retrieve. Defaults to 1.
​
page_size
integer
Number of items per page. Defaults to 20. Maximum 100.
Paginated responses include metadata alongside the data array: 
{
  "data": [
    { "id": "inst_a1b2c3d4", "name": "Production Agent", "status": "active" }
  ],
  "page": 1,
  "page_size": 20,
  "total": 42,
  "total_pages": 3
}

​
Rate Limiting

API requests are rate-limited per API key. When you exceed the limit, the API returns a 429 Too Many Requests response.
TierRequests per minuteBurst
Free6010
Pro60050
EnterpriseCustomCustom
Rate limit headers are included in every response:
HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait before retrying (only on 429)
Implement exponential backoff with jitter when handling 429 responses. The SDK handles this automatically.

​
Correlation IDs

Every API response includes an X-Correlation-Id header containing a unique identifier for that request. This ID is propagated through the entire request lifecycle, including background jobs like ingestion. 
X-Correlation-Id: req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c
Always include the X-Correlation-Id when contacting support. It allows the team to trace the exact request path and identify issues quickly.

​
Response Format

​
Success Responses

Single resource responses return the resource directly: 
{
  "id": "mem_abc123",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00Z"
}
List responses use the paginated envelope: 
{
  "data": [...],
  "page": 1,
  "page_size": 20,
  "total": 42,
  "total_pages": 3
}

​
Error Responses

All errors follow a consistent format: 
{
  "error": "Instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "instance_id": "inst_nonexistent"
  }
}
The error field contains a human-readable message. The code field contains a machine-readable error code suitable for programmatic handling. The details object provides additional context specific to the error. See the Error Codes reference for a complete list.

​
HTTP Status Codes

StatusMeaning
200 OKRequest succeeded. Response body contains the requested resource.
201 CreatedResource was created successfully.
400 Bad RequestThe request body or parameters are invalid. Check the details field.
401 UnauthorizedMissing or invalid authentication credentials.
403 ForbiddenValid credentials but insufficient permissions for this operation.
404 Not FoundThe requested resource does not exist.
409 ConflictThe request conflicts with the current state (e.g., applying an already-active config).
429 Too Many RequestsRate limit exceeded. Retry after the Retry-After period.
500 Internal Server ErrorAn unexpected error occurred on Synap’s side. Contact support with the correlation ID.
503 Service UnavailableSynap is temporarily unavailable. Retry with exponential backoff.

​
SDKs

The official Python SDK wraps all API endpoints and handles authentication, retries, and streaming automatically. 
pip install maximem-synap

from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(
    instance_id="inst_a1b2c3d4e5f67890",
    bootstrap_token="your-bootstrap-token"
)

await sdk.initialize()

# All SDK methods are async
context = await sdk.conversation.context.fetch(
    conversation_id="conv_456",
    search_query=["user preferences"]
)
A JavaScript/TypeScript SDK is also available for Node.js environments: 
npm install @maximem/synap-js-sdk
See the Installation guide for full setup instructions for both SDKs.