API Reference

Engram provides a comprehensive RESTful API for managing memories, searching, and configuring your memory system. All endpoints are secured with API key authentication.

Authentication

All API requests require authentication using an API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.engram.dev/v1/memories

Base URL

Production: https://api.engram.dev/v1
Self-hosted: https://your-domain.com/api/v1

Memory Operations

Store Memory

Store a new memory in the system.

Endpoint: POST /memories

Request Body:

{
  "content": "The content to remember",
  "metadata": {
    "category": "documentation",
    "importance": 0.8,
    "tags": ["ai", "memory"]
  },
  "user_id": "user123"
}

Response:

{
  "id": "mem_1234567890",
  "content": "The content to remember",
  "metadata": {
    "category": "documentation",
    "importance": 0.8,
    "tags": ["ai", "memory"]
  },
  "user_id": "user123",
  "created_at": "2026-03-28T10:00:00Z",
  "updated_at": "2026-03-28T10:00:00Z"
}

Get Memory

Retrieve a specific memory by ID.

Endpoint: GET /memories/{memory_id}

Response:

{
  "id": "mem_1234567890",
  "content": "The content to remember",
  "metadata": {
    "category": "documentation",
    "importance": 0.8
  },
  "user_id": "user123",
  "created_at": "2026-03-28T10:00:00Z",
  "updated_at": "2026-03-28T10:00:00Z"
}

Update Memory

Update an existing memory.

Endpoint: PUT /memories/{memory_id}

Request Body:

{
  "content": "Updated content",
  "metadata": {
    "importance": 0.9
  }
}

Delete Memory

Delete a memory permanently.

Endpoint: DELETE /memories/{memory_id}

Response: 204 No Content

Search Operations

Semantic Search

Search memories using natural language queries.

Endpoint: POST /search

Request Body:

{
  "query": "What is machine learning?",
  "limit": 10,
  "filters": {
    "category": "ai",
    "importance": {"gte": 0.5}
  },
  "user_id": "user123"
}

Response:

{
  "memories": [
    {
      "id": "mem_1234567890",
      "content": "Machine learning is a subset of AI...",
      "score": 0.95,
      "metadata": {
        "category": "ai",
        "importance": 0.8
      }
    }
  ],
  "total": 1,
  "query_time_ms": 45
}

Similar Memories

Find memories similar to a given memory.

Endpoint: GET /memories/{memory_id}/similar

Query Parameters:

• limit (optional): Number of results to return (default: 10)
• threshold (optional): Similarity threshold (default: 0.7)

Collections

Create Collection

Group related memories into collections.

Endpoint: POST /collections

Request Body:

{
  "name": "AI Research",
  "description": "Collection of AI-related memories",
  "metadata": {
    "category": "research"
  }
}

Add Memory to Collection

Endpoint: POST /collections/{collection_id}/memories

Request Body:

{
  "memory_id": "mem_1234567890"
}

Embeddings

Generate Embeddings

Generate embeddings for custom text.

Endpoint: POST /embeddings

Request Body:

{
  "text": "Text to generate embeddings for",
  "model": "text-embedding-ada-002"
}

Response:

{
  "embeddings": [0.1, 0.2, -0.1, ...],
  "model": "text-embedding-ada-002",
  "dimensions": 1536
}

User Management

Get User Stats

Get statistics about a user's memories.

Endpoint: GET /users/{user_id}/stats

Response:

{
  "user_id": "user123",
  "total_memories": 1250,
  "total_collections": 15,
  "storage_used_mb": 45.2,
  "last_activity": "2026-03-28T10:00:00Z"
}

Error Handling

All errors follow this format:

{
  "error": {
    "code": "MEMORY_NOT_FOUND",
    "message": "Memory with ID mem_1234567890 not found",
    "details": {
      "memory_id": "mem_1234567890"
    }
  }
}

Common Error Codes

• INVALID_API_KEY: API key is missing or invalid
• MEMORY_NOT_FOUND: Requested memory doesn't exist
• VALIDATION_ERROR: Request validation failed
• RATE_LIMIT_EXCEEDED: Too many requests
• INTERNAL_ERROR: Server error

Rate Limiting

API requests are rate-limited based on your plan:

• Free: 100 requests per minute
• Pro: 1,000 requests per minute
• Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

SDKs

Official SDKs are available for:

• Python: pip install engram-sdk
• Node.js: npm install @engram/sdk
• Go: go get github.com/engram/go-sdk
• Java: Maven/Gradle packages available

Webhooks

Configure webhooks to receive real-time notifications:

Endpoint: POST /webhooks

Events:

• memory.created
• memory.updated
• memory.deleted
• search.performed

See our webhooks guide for detailed setup instructions.