MemSync API Reference

The MemSync REST API provides programmatic access to memory management, user profiles, and integrations. This comprehensive reference covers all endpoints, request/response formats, and implementation examples.

Base URL

All API requests should be made to:

https://api.memchat.io/v1

Authentication

MemSync uses API key-based authentication. Include your API key in the X-API-Key header for all requests:

X-API-Key: YOUR_API_KEY

API keys are required for all requests. Keep your API key secure and do not share it publicly.

Quick Start

Here’s how to make your first API call:

import requests

headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Store a conversation
response = requests.post("https://api.memchat.io/v1/memories",
    headers=headers,
    json={
        "messages": [
            {"role": "user", "content": "I'm a software engineer who loves hiking"},
            {"role": "assistant", "content": "That's a great combination of technical and outdoor interests!"}
        ],
        "agent_id": "my-chatbot",
        "thread_id": "conversation-123",
        "source": "chat"
    }
)

print(response.json())

API Endpoints Overview

Memory Management

Store Memories

Extract and store memories from conversations

Search Memories

Find and retrieve memories using natural language queries

Get Memories

Retrieve paginated list of user memories

Update Memory

Modify existing memory content

User Profiles

Get Profile

Retrieve complete user profile with bio and insights

Get Bio

Get user’s auto-generated biographical summary

Update Bio

Update user’s biographical information

Integrations

Social Integration

Import data from social media platforms

File Integration

Process documents and extract information

Chat Integration

Import conversation history from chat platforms

Integration Status

Check the status of processing tasks

API Key Management

Create API Key

Generate new API keys for third-party apps

List API Keys

View all API keys for the authenticated user

Delete API Key

Revoke and delete existing API keys

Standard Response Format

All API responses follow a consistent format:

Success Response

{
  "data": {
    // Response data specific to the endpoint
  },
  "status": "success",
  "timestamp": "2024-03-20T10:00:00Z"
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request format",
    "details": {
      "field": "messages",
      "reason": "At least one message is required"
    }
  },
  "status": "error",
  "timestamp": "2024-03-20T10:00:00Z"
}

HTTP Status Codes

Status Code	Description
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request format or parameters
`401`	Unauthorized - Invalid or missing authentication
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`422`	Unprocessable Entity - Valid request but cannot be processed
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error occurred

Rate Limiting

The MemSync API implements rate limiting to ensure service quality:

Standard Rate Limit: 100 requests per minute per user
Integration Endpoints: 10 requests per minute per user
Search Endpoints: 50 requests per minute per user

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Handling Rate Limits

import time
import requests

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 429:
            # Rate limited, wait and retry
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

Error Handling

Common Error Codes

AUTHENTICATION_ERROR

Invalid or missing authentication credentials

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid API key",
    "details": {
      "reason": "Token has expired"
    }
  }
}

VALIDATION_ERROR

Request validation failed

{
  "error": {
    "code": "VALIDATION_ERROR", 
    "message": "Invalid request format",
    "details": {
      "field": "limit",
      "reason": "Must be between 1 and 100"
    }
  }
}

RESOURCE_NOT_FOUND

Requested resource does not exist

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Memory not found",
    "details": {
      "memory_id": "mem_123",
      "reason": "Memory does not exist or user lacks access"
    }
  }
}

RATE_LIMIT_EXCEEDED

Too many requests in a given time period

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "reset_time": "2024-03-20T10:01:00Z"
    }
  }
}

Pagination

Many endpoints support pagination for large datasets:

Request Parameters

{
  "page": 1,
  "page_size": 20
}

Response Format

{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 150,
    "total_pages": 8,
    "has_next": true,
    "has_previous": false
  }
}

Example Implementation

def get_all_memories(headers):
    all_memories = []
    page = 1
    
    while True:
        response = requests.get(f"https://api.memchat.io/v1/memories",
            headers=headers,
            params={"page": page, "page_size": 50}
        )
        
        data = response.json()
        all_memories.extend(data['data'])
        
        if not data['pagination']['has_next']:
            break
            
        page += 1
    
    return all_memories

SDKs and Libraries

Official SDKs

Python SDK

Coming soon - Official Python SDK with full API coverage

JavaScript SDK

Coming soon - Official JavaScript/TypeScript SDK

Go SDK

Planned - Go SDK for server-side applications

PHP SDK

Planned - PHP SDK for web applications

Community Libraries

We encourage community contributions! If you’ve built a library for MemSync, let us know and we’ll feature it here.

Webhooks (Coming Soon)

Webhooks will allow your application to receive real-time notifications about:

Memory processing completion
Integration task updates
Profile changes
System events

{
  "event": "memory.created",
  "data": {
    "memory_id": "mem_123",
    "user_id": "user_456",
    "categories": ["career", "interests"]
  },
  "timestamp": "2024-03-20T10:00:00Z"
}

OpenAPI Specification

Download the complete OpenAPI specification for the MemSync API:

OpenAPI Spec

Download the OpenAPI 3.0 specification file for code generation and testing

Support and Feedback

Getting Help

Documentation: Comprehensive guides and examples
Community: Join our Discord for community support
GitHub Issues: Report bugs and request features
Email Support: Contact us at api@memsync.ai

Status Page

Monitor API status and performance:

API Status

Check real-time API status, uptime, and incident reports

Next Steps

Ready to start building with MemSync? Here are some great places to begin:

Quickstart Guide

Get up and running with your first API calls in minutes

Memory Management

Learn how to store and retrieve user memories

User Profiles

Explore auto-generated user profiles and insights

Integrations

Import data from external sources to enrich profiles

Getting Started

Memory Management

User Profiles

Integrations

API Keys

​MemSync API Reference

​Base URL

​Authentication

​Quick Start

​API Endpoints Overview

​Memory Management

Store Memories

Search Memories

Get Memories

Update Memory

​User Profiles

Get Profile

Get Bio

Update Bio

​Integrations

Social Integration

File Integration

Chat Integration

Integration Status

​API Key Management

Create API Key

List API Keys

Delete API Key

​Standard Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Rate Limiting

​Rate Limit Headers

​Handling Rate Limits

​Error Handling

​Common Error Codes

​Pagination

​Request Parameters

​Response Format

​Example Implementation

​SDKs and Libraries

​Official SDKs

Python SDK

JavaScript SDK

Go SDK

PHP SDK

​Community Libraries

​Webhooks (Coming Soon)

​OpenAPI Specification

OpenAPI Spec

​Support and Feedback

​Getting Help

​Status Page

API Status

​Next Steps

Quickstart Guide

Memory Management

User Profiles

Integrations

MemSync API Reference

Base URL

Authentication

Quick Start

API Endpoints Overview

Memory Management

User Profiles

Integrations

API Key Management

Standard Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Error Handling

Common Error Codes

Pagination

Request Parameters

Response Format

Example Implementation

SDKs and Libraries

Official SDKs

Community Libraries

Webhooks (Coming Soon)

OpenAPI Specification

Support and Feedback

Getting Help

Status Page

Next Steps