Skip to main content
  1. Content Organization
    • Use containerTags for grouping/partitioning
      • Optional tags (array of strings) to group memories.
      • Can be a user ID, project ID, or any other identifier.
      • Allows filtering for memories that share specific tags.
      • Example: ["user_123", "project_alpha"]
    Read more about filtering
  2. Performance Tips
    • Batch Operations
      • You can add multiple items in parallel
      • Use different containerTags for different spaces
      • Don’t wait for processing to complete unless needed
    • Search Optimization 
      {
  "q": "error logs",
  "documentThreshold": 0.7, // Higher = more precise
  "limit": 5, // Keep it small
  "onlyMatchingChunks": true // Skip extra context if not needed
}
  3. URL Content
    • Send clean URLs without tracking parameters
    • Use article URLs, not homepage URLs
    • Check URL accessibility before sending

​
Basic Usage

To add a memory, send a POST request to /add with your content: 
curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  --data '{
  "customId": "xyz-my-db-id",
  "content": "This is the content of my memory",
  "metadata": {
    "category": "technology",
    "tag_1": "ai",
    "tag_2": "machine-learning",
  },
  "containerTags": ["user_123", "project_xyz"]
}'
The API will return a response with an ID and initial status: 
{
  "id": "mem_abc123",
  "status": "queued"
}

curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  -d '{
    "content": "https://example.com/article",
    "metadata": {
      "source": "web",			# Just example metadata
      "category": "technology"	# NOT required
    },
    "containerTags": ["user_456", "research_papers"]
  }'

​
Metadata and Organization

You can add rich metadata to organize your content: 
{
  "metadata": {
    "source": "string", // String
    "priority": 1234, // Custom numeric field
    "custom_field": "any" // Any custom field
  }
}

​
Partitioning by user

You can attribute and partition your data by providing a userId: 
curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  -d '{
    "content": "This is space-specific content",
    "userId": "space_123",
    "metadata": {
      "category": "space-content"
    }
  }'
When searching, if you provide a userId, only memories from that space will be returned.

​
Grouping

You can group memories by providing an array of containerTags: 
curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  -d '{
    "content": "This is space-specific content",
    "containerTags": ["user_123", "project_xyz"]
  }'

​
Checking Status

Check status using the memory ID: 
curl https://api.supermemory.ai/v3/documents/mem_abc123 \
  --request GET \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY'
Memories are deleted after 2 minutes if an irrecoverable error occurs.

​
File Uploads

For file uploads, use the dedicated file upload endpoint. You can include containerTags directly in the form data: 
curl https://api.supermemory.ai/v3/documents/file \
  --request POST \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  --form 'file=@/path/to/your/file.pdf' \
  --form 'containerTags=["user_123", "project_xyz"]'

​
Adding Additional Metadata to Files

If you need to add additional metadata (like title or description) after upload, you can use the PATCH endpoint: 
curl https://api.supermemory.ai/v3/documents/MEMORY_ID \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \
  --data '{
    "metadata": {
      "title": "My Document",
      "description": "Important project document"
    }
  }'
The file upload endpoint returns immediately with a memory ID and processing status. The file will be processed asynchronously, and you can check its status using the GET endpoint.

​
Next Steps

Explore more advanced features in our API Reference tab.