---
title: 'API Reference'
description: 'Complete API documentation for the Mem0 Memory System'
---

## Overview

The Mem0 Memory System provides a comprehensive REST API for memory operations, built on top of the mem0 framework with enhanced local-first capabilities.

<Note>
**Current Status**: Phase 1 Complete - Core infrastructure ready for API development
</Note>

## Base URL

```
http://localhost:8080/v1
```

## Authentication

All API requests require authentication using API keys:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     http://localhost:8080/v1/memories
```

## Core Endpoints

### Memory Operations

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/memories` | Add new memory |
| `GET` | `/memories/search` | Search memories |
| `GET` | `/memories/{id}` | Get specific memory |
| `PUT` | `/memories/{id}` | Update memory |
| `DELETE` | `/memories/{id}` | Delete memory |
| `GET` | `/memories/user/{user_id}` | Get user memories |

### Health & Status

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | System health check |
| `GET` | `/status` | Detailed system status |
| `GET` | `/metrics` | Performance metrics |

## Request/Response Format

### Standard Response Structure

```json
{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully",
  "timestamp": "2025-07-30T20:15:00Z"
}
```

### Error Response Structure

```json
{
  "success": false,
  "error": {
    "code": "MEMORY_NOT_FOUND",
    "message": "Memory with ID 'abc123' not found",
    "details": {}
  },
  "timestamp": "2025-07-30T20:15:00Z"
}
```

## Memory Object

```json
{
  "id": "mem_abc123def456",
  "content": "User loves building AI applications with local models",
  "user_id": "user_789",
  "metadata": {
    "source": "chat",
    "timestamp": "2025-07-30T20:15:00Z",
    "entities": ["AI", "applications", "local models"]
  },
  "embedding": [0.1, 0.2, 0.3, ...],
  "relationships": [
    {
      "type": "mentions",
      "entity": "AI applications",
      "confidence": 0.95
    }
  ]
}
```

## Configuration

The API behavior can be configured through environment variables:

```bash
# API Configuration
API_PORT=8080
API_HOST=localhost
API_KEY=your_secure_api_key

# Memory Configuration  
MAX_MEMORY_SIZE=1000000
SEARCH_LIMIT=50
DEFAULT_USER_ID=default
```

## Rate Limiting

The API implements rate limiting to ensure fair usage:

- **Default**: 100 requests per minute per API key
- **Burst**: Up to 20 requests in 10 seconds
- **Headers**: Rate limit info included in response headers

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1627849200
```

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `INVALID_REQUEST` | 400 | Malformed request |
| `UNAUTHORIZED` | 401 | Invalid or missing API key |
| `FORBIDDEN` | 403 | Insufficient permissions |
| `MEMORY_NOT_FOUND` | 404 | Memory does not exist |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `INTERNAL_ERROR` | 500 | Server error |

## SDK Support

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python">
    ```python
    from mem0_client import MemoryClient
    client = MemoryClient(api_key="your_key")
    ```
  </Card>
  <Card title="JavaScript SDK" icon="js">
    ```javascript
    import { MemoryClient } from '@mem0/client';
    const client = new MemoryClient({ apiKey: 'your_key' });
    ```
  </Card>
  <Card title="cURL Examples" icon="terminal">
    Complete cURL examples for all endpoints
  </Card>
  <Card title="Postman Collection" icon="api">
    Import ready-to-use Postman collection
  </Card>
</CardGroup>

## Development Status

<Warning>
**In Development**: The API is currently in Phase 2 development. Core infrastructure (Phase 1) is complete and ready for API implementation.
</Warning>

### Completed ✅
- Core mem0 integration
- Database connections (Neo4j, Qdrant)
- LLM provider support (Ollama, OpenAI)
- Configuration management

### In Progress 🚧
- REST API endpoints
- Authentication system
- Rate limiting
- Error handling

### Planned 📋
- SDK development
- API documentation
- Performance optimization
- Monitoring and logging