t6_mem0/docs/api-reference/introduction.mdx

---
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>
**Phase 2 Complete ✅** - REST API is fully functional and production-ready as of 2025-07-31
</Note>

## Base URL

For external access (Docker deployment):
```
http://YOUR_SERVER_IP:8080/v1
```

For local development:
```
http://localhost:8080/v1
```

## Authentication

All API requests require authentication using Bearer tokens. **Available API keys:**

<CodeGroup>
```bash Development Key
# Default development API key
Authorization: Bearer mem0_dev_key_123456789
```

```bash Docker Key  
# Docker deployment API key
Authorization: Bearer mem0_docker_key_987654321
```

```bash Admin Key
# Admin API key (for /v1/metrics endpoint)
Authorization: Bearer mem0_admin_key_111222333
```
</CodeGroup>

### Example Request:
```bash
curl -H "Authorization: Bearer mem0_dev_key_123456789" \
     -H "Content-Type: application/json" \
     http://YOUR_SERVER_IP:8080/v1/memories/search?query=test&user_id=demo
```

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

<Note>
**Phase 2 Complete ✅**: The REST API is fully functional and production-ready with comprehensive features.
</Note>

### Completed ✅
- **Core Infrastructure**: mem0 integration, Neo4j, Supabase, Ollama
- **REST API Endpoints**: All CRUD operations working
- **Authentication System**: Bearer token auth with API keys
- **Rate Limiting**: 100 requests/minute configurable
- **Error Handling**: Comprehensive error responses
- **Testing Suite**: Automated tests for all functionality
- **Docker Deployment**: External access configuration
- **Documentation**: Complete API reference and guides

### Available Now 🚀
- **Memory Operations**: Add, search, get, update, delete
- **User Management**: User-specific operations and statistics  
- **Health Monitoring**: Health checks and system status
- **Admin Operations**: Metrics and system administration
- **External Access**: Docker deployment for remote access

### Future Enhancements 📋
- SDK development (Python, JavaScript)
- Advanced caching mechanisms
- Metrics collection and monitoring
- Webhook support for real-time updates

## Quick Testing

Test the API from outside your machine using these working examples:

### 1. Health Check (No Authentication)
```bash
curl http://YOUR_SERVER_IP:8080/health
```

### 2. System Status (With Authentication)
```bash
curl -H "Authorization: Bearer mem0_dev_key_123456789" \
     http://YOUR_SERVER_IP:8080/status
```

### 3. Add a Memory
```bash
curl -X POST "http://YOUR_SERVER_IP:8080/v1/memories" \
  -H "Authorization: Bearer mem0_dev_key_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "I love building AI applications with FastAPI"}],
    "user_id": "test_user_123",
    "metadata": {"source": "external_test"}
  }'
```

### 4. Search Memories
```bash
curl "http://YOUR_SERVER_IP:8080/v1/memories/search?query=FastAPI&user_id=test_user_123&limit=5" \
  -H "Authorization: Bearer mem0_dev_key_123456789"
```

### 5. Interactive Documentation
Open in your browser: `http://YOUR_SERVER_IP:8080/docs`