API Reference

Complete reference for the MemSync REST API

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.memsync.ai/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:

Python

import requests

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

# Store a conversation
response = requests.post("https://api.memsync.ai/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.memsync.ai/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 [e-mail]

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