Skip to main content
The Basic Memory REST API provides programmatic access to your knowledge graph, enabling CRUD operations on entities, search functionality, and project management.

​
Base URL

The API base URL depends on your deployment mode:

​
Local Mode

When running Basic Memory locally, the API is available at: 
http://localhost:8000
The local API server starts automatically when you use MCP tools or can be started manually: 
basic-memory api

​
Cloud Mode

For cloud deployments, the API is available at: 
https://api.basicmemory.com
Cloud mode requires authentication with an API key (see Authentication).

​
API Versioning

Basic Memory uses versioned API endpoints to ensure stability:
  • v2 (Current): Uses external UUIDs for stable references across renames and moves
  • v1 (Legacy): Uses string-based project names (deprecated)

​
V2 Endpoint Structure

All v2 endpoints follow this pattern: 
/v2/projects/{project_id}/{resource}
Where:
  • {project_id} - Project external UUID (stable identifier)
  • {resource} - The resource type (knowledge, search, etc.)
Example: 
GET /v2/projects/550e8400-e29b-41d4-a716-446655440000/knowledge/entities/abc-123

​
Response Format

All API responses use JSON format with consistent structure:

​
Success Response

{
  "external_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "My Note",
  "permalink": "my-note",
  "file_path": "my-note.md",
  "note_type": "note",
  "content_type": "text/markdown",
  "created_at": "2026-02-28T14:30:00Z",
  "updated_at": "2026-02-28T14:30:00Z"
}

​
Error Response

{
  "detail": "Entity not found: 'invalid-id'"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescription
200Success
201Created
400Bad Request
401Unauthorized
404Not Found
409Conflict (entity already exists)
500Internal Server Error

​
Rate Limiting

​
Local Mode

No rate limiting is applied when running locally.

​
Cloud Mode

Rate limits apply based on your subscription tier:
  • Free tier: 100 requests per minute
  • Pro tier: 1,000 requests per minute
  • Enterprise: Custom limits
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709136000

​
Content Types

The API supports multiple content types:
Content TypeDescription
text/markdownMarkdown files (default)
text/plainPlain text files
application/pdfPDF documents
image/jpegJPEG images
image/pngPNG images
image/svg+xmlSVG images

​
Pagination

Endpoints that return lists support pagination via query parameters: 
GET /v2/projects/{project_id}/search?page=2&page_size=20
​
page
integer
default:"1"
Page number (1-indexed)
​
page_size
integer
default:"10"
Number of results per page (max 100)
Paginated responses include: 
{
  "results": [...],
  "current_page": 2,
  "page_size": 20,
  "has_more": true
}

​
Next Steps

Authentication

Learn how to authenticate API requests

Entities

CRUD operations for knowledge entities

Search

Search across your knowledge graph

Projects

Manage multiple projects

Build docs developers (and LLMs) love

Get started for freeTalk to us