Documentation

REST API Reference

Complete API reference for integrating Maple Memory into your applications. All endpoints use JSON for request and response bodies.

Base URL

https://api.heymaple.app

5-Minute Quickstart

Our Memory API is fully asynchronous. When you send a message, we return a task_id instantly so your web server is never blocked waiting for the AI to organise your contextual memory graph.

Here is how to add structured, long-term memory to your AI application in just a few lines of code.

Step 1: Authentication

Get your secret Maple Memory API Key from your Developer Dashboard. You will use this key to authenticate your requests.

import requests

API_URL = "https://api.yourdomain.com"
API_KEY = "heymaple_live_your_secret_heymaple_api_key_here"

HEADERS = {
    "Authorization": "Bearer " + API_KEY,
    "Content-Type": "application/json"
}

Step 2: Send a User Message

Send the user's chat to the /chat endpoint. We will instantly return a tracking ID while our background workers generate the vector embeddings and update the memory relationships.

# 1. Send the chat message
chat_payload = {
    "content": "I'm starting a new project to build a Docker API for tabular queries."
}

response = requests.post(API_URL + "/chat", json=chat_payload, headers=HEADERS)
task_data = response.json()

print("Task Started: " + task_data['task_id'])

Expected Output:

Task Started: 550e8400-e29b-41d4-a716-446655440000

Step 3: Retrieve the Structured Memory

Because we process memories intelligently in the background (mapping relationships and preventing duplicates), you simply poll the task endpoint to get the updated memory node. Note: Background tasks usually complete in under 2 seconds.

import time

task_id = task_data['task_id']
status = "pending"
attempts = 0

# 2. Poll the task status (with a 10-second timeout safety)
while status in ["pending", "processing"] and attempts < 10:
    time.sleep(1)
    task_response = requests.get(API_URL + "/task/" + task_id, headers=HEADERS)
    result_data = task_response.json()
    status = result_data["status"]
    attempts += 1

# 3. View your structured memory!
if status == "completed":
    memory_node = result_data["result"]["memory"]

    print("Action Taken: " + result_data["result"]["action"])
    print("Theme: " + memory_node['theme'])
    print("Summary: " + memory_node['summary'])
    print("Entities Found: " + str(memory_node['entities']))
elif status == "failed":
    print("Task failed:", result_data.get("error"))
else:
    print("Task timed out.")

Expected Output:

Action Taken: NEW
Theme: Docker API Project
Summary: User is initiating a new software project focused on building an API using Docker specifically for handling tabular queries.
Entities Found: ['Docker', 'API', 'tabular queries']

Autonomous Memory Routing

When you send a message, our semantic engine evaluates the new context against the user's historical memory graph. To prevent database bloat and preserve accurate recall, it dynamically takes one of three actions behind the scenes:

  • Isolate - Creates a new, independent memory node
  • Branch - Links to related memories while maintaining distinct context
  • Merge - Combines with existing similar memories to prevent duplication

Step 4: Search Your Memories

Use semantic search to retrieve the most relevant contextual memories when your user asks a question.

search_payload = {
    "query": "What projects am I working on?",
    "limit": 5
}

response = requests.post(API_URL + "/memories/search", json=search_payload, headers=HEADERS)
results = response.json()

for memory in results["memories"]:
    print("[" + str(memory['similarity']) + "] " + memory['theme'] + ": " + memory['summary'])

Expected Output:

[0.94] Docker API Project: User is initiating a new software project focused on building an API using Docker...
[0.78] Previous Docker Experience: User has experience with Docker containerization from previous projects...
[0.72] API Development Skills: User prefers FastAPI framework for building REST APIs...
i
Advanced: Hybrid Search (Keywords + Semantic)
For queries with highly specific technical terms, custom IDs, or jargon, use Hybrid Search. By setting the mode to "hybrid", our engine automatically balances exact keyword extraction with semantic intent to ensure maximum accuracy, no manual tuning required. 
hybrid_payload = {
    "query": "Docker API deployment",
    "limit": 5,
    "mode": "hybrid"
}
i
Advanced: Batch Process Conversations
Import historical conversation logs in a single API call. Our system will automatically chunk, cluster, and map them into a clean relational graph. 
batch_payload = {
    "conversations": [
        {
            "input": "What's the best way to containerize a Python app?",
            "output": "Docker is great for Python apps."
        },
        {
            "input": "I prefer FastAPI over Flask",
            "output": "FastAPI is excellent!"
        }
    ]
}

Memory Graph (Linked Memories)

Explore related memories as a connected graph to trace how a user's topics shift over time:

# Get a memory's graph (all connected memories)
memory_id = 42
response = requests.get(API_URL + "/memories/" + str(memory_id) + "/graph", headers=HEADERS)
graph = response.json()

print("Main Memory: " + graph['memory']['theme'])
print("Linked Memories: " + str(len(graph['linked_memories'])))

Expected Output:

Main Memory: Docker API Project
Linked Memories: 3
→ [0.85] FastAPI Framework Preference
→ [0.78] Previous Docker Experience

Authentication

All API requests require authentication using your organisation API key and user token. Include these in your request headers:

Authorization: Bearer YOUR_ORG_API_KEY
X-User-Token: USER_TOKEN_HERE
⚠
Security Notice
Never expose your API keys in client-side code. All API calls should be made from your backend server.

Chat Endpoint

Send Message

POST /v1/chat

Send a message to the AI agent with persistent memory context.

Request Body

{
  "user_message": "What did we discuss about Python yesterday?",
  "user_token": "user_123",
  "org_email": "your-org@example.com"
}

Response

{
  "response": "Yesterday we discussed Python's async/await syntax...",
  "memories_used": ["mem_abc123", "mem_def456"],
  "timestamp": "2026-03-18T10:30:00Z"
}

Memory Management

Create Memory

POST /v1/memories

Manually create a new memory in the user's graph.

Request Body

{
  "user_token": "user_123",
  "org_email": "your-org@example.com",
  "content": "User prefers dark mode in all applications",
  "metadata": {
    "category": "preferences",
    "priority": "high"
  }
}

Response

{
  "memory_id": "mem_xyz789",
  "content": "User prefers dark mode in all applications",
  "created_at": "2026-03-18T10:30:00Z",
  "status": "success"
}

List Memories

GET /v1/memories

Retrieve all memories for a specific user with optional filtering.

Query Parameters

  • user_token (required) - The user's unique identifier
  • limit (optional) - Maximum number of memories to return (default: 50)
  • offset (optional) - Number of memories to skip (default: 0)
  • category (optional) - Filter by metadata category
GET /v1/memories?user_token=user_123&limit=10&category=preferences

Response

{
  "memories": [
    {
      "memory_id": "mem_xyz789",
      "content": "User prefers dark mode",
      "created_at": "2026-03-18T10:30:00Z",
      "metadata": {
        "category": "preferences"
      }
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get Memory by ID

GET /v1/memories/:memory_id

Retrieve a specific memory by its ID.

GET /v1/memories/mem_xyz789

Response

{
  "memory_id": "mem_xyz789",
  "content": "User prefers dark mode in all applications",
  "created_at": "2026-03-18T10:30:00Z",
  "updated_at": "2026-03-18T10:30:00Z",
  "metadata": {
    "category": "preferences",
    "priority": "high"
  }
}

Update Memory

PUT /v1/memories/:memory_id

Update an existing memory's content or metadata.

Request Body

{
  "content": "User prefers dark mode and high contrast",
  "metadata": {
    "category": "preferences",
    "priority": "critical"
  }
}

Response

{
  "memory_id": "mem_xyz789",
  "content": "User prefers dark mode and high contrast",
  "updated_at": "2026-03-18T11:00:00Z",
  "status": "success"
}

Delete Memory

DELETE /v1/memories/:memory_id

Permanently delete a memory from the user's graph.

DELETE /v1/memories/mem_xyz789

Response

{
  "memory_id": "mem_xyz789",
  "status": "deleted",
  "deleted_at": "2026-03-18T11:30:00Z"
}

Search & Retrieval

Search Memories

POST /v1/search

Search through a user's memories using semantic search.

Request Body

{
  "query": "user interface preferences",
  "user_token": "user_123",
  "org_email": "your-org@example.com",
  "limit": 5
}

Response

{
  "results": [
    {
      "memory_id": "mem_xyz789",
      "content": "User prefers dark mode",
      "relevance_score": 0.92,
      "metadata": {
        "category": "preferences"
      }
    }
  ],
  "query": "user interface preferences",
  "total_results": 1
}

User Management

Register User

POST /v1/users/register

Register a new user and generate their unique token.

Request Body

{
  "org_email": "your-org@example.com",
  "user_identifier": "user_123"
}

Response

{
  "user_token": "hm_live_user_abc123xyz",
  "status": "registered",
  "created_at": "2026-03-18T10:00:00Z"
}

Health & Status

Health Check

GET /v1/health

Check the API service status.

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-03-18T10:00:00Z"
}

Get Metrics

GET /v1/metrics

Retrieve usage metrics for your organisation.

Response

{
  "total_memories": 1250,
  "api_calls_this_month": 3420,
  "active_users": 45,
  "avg_response_time_ms": 206
}

Error Responses

All error responses follow a consistent format:

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided user token is invalid or expired",
    "status": 401
  }
}

Common Error Codes

  • 400 - Bad Request: Invalid request parameters
  • 401 - Unauthorized: Invalid or missing authentication
  • 403 - Forbidden: Insufficient permissions
  • 404 - Not Found: Resource does not exist
  • 429 - Too Many Requests: Rate limit exceeded
  • 500 - Internal Server Error: Server-side error
ℹ
Rate Limits
All API endpoints are subject to rate limiting. Check the Rate Limits documentation for tier-specific limits.

SDKs & Libraries

We provide official SDKs to make integration easier:

  • Python: pip install zymemory
  • JavaScript/TypeScript: Coming soon
  • Go: Coming soon

For SDK documentation, see the SDK Reference.

Rate Limits & Monitoring

Default Rate Limit

60 requests/minute per user.

Monitoring

Check your API usage, error rates, and response times anytime by hitting the /metrics endpoint or visiting your dashboard.

⚠
Rate Limit Exceeded
If you hit the rate limit, you will receive a 429 Too Many Requests status code: 
{
  "detail": "Rate limit exceeded. Try again in 30 seconds."
}