Skip to main content
The Projects API allows you to manage multiple knowledge graph projects, each with its own entities, search index, and configuration.

​
List Projects

Retrieve all configured projects. 
curl https://api.basicmemory.com/v2/projects/ \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
projects
array
Array of project objects
​
default_project
string
Name of the default project

​
Example Response

{
  "projects": [
    {
      "id": 1,
      "external_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "personal",
      "path": "/Users/username/Notes",
      "is_default": true
    },
    {
      "id": 2,
      "external_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "work",
      "path": "/Users/username/Work/Notes",
      "is_default": false
    }
  ],
  "default_project": "personal"
}

​
Get Project by ID

Retrieve a specific project by its external UUID. 
curl https://api.basicmemory.com/v2/projects/{project_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path Parameters

​
project_id
string
required
Project external UUID

​
Response

Returns a single project object (see List Projects for schema).

​
Resolve Project Identifier

Resolve a project identifier (name, permalink, or external_id) to project info. 
curl -X POST https://api.basicmemory.com/v2/projects/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "personal"}'

​
Request Body

​
identifier
string
required
Project name, permalink, or external UUID to resolve

​
Response

​
external_id
string
Project external UUID
​
project_id
integer
Internal project ID
​
name
string
Project name
​
permalink
string
Project permalink (kebab-case name)
​
path
string
Absolute path to project directory
​
is_active
boolean
Whether project is active
​
is_default
boolean
Whether this is the default project
​
resolution_method
string
How the project was resolved: external_id, permalink, or name

​
Add Project

Add a new project to the configuration. 
curl -X POST https://api.basicmemory.com/v2/projects/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research",
    "path": "/Users/username/Research",
    "set_default": false
  }'

​
Request Body

​
name
string
required
Project name (must be unique)
​
path
string
required
Absolute path to project directory
​
set_default
boolean
default:"false"
Whether to set this as the default project

​
Response

​
message
string
Success message
​
status
string
Always “success”
​
default
boolean
Whether this project is now the default
​
new_project
object
The created project object

​
Update Project

Update a project’s path or active status. 
curl -X PATCH https://api.basicmemory.com/v2/projects/{project_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/username/NewPath"}'

​
Request Body

​
path
string
New absolute path for the project
​
is_active
boolean
Active status of the project

​
Response

​
message
string
Success message
​
status
string
Always “success”
​
old_project
object
Project state before update
​
new_project
object
Project state after update

​
Delete Project

Delete a project from the configuration. 
curl -X DELETE "https://api.basicmemory.com/v2/projects/{project_id}?delete_notes=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

​
delete_notes
boolean
default:"false"
If true, also delete the project directory from the filesystem
Setting delete_notes=true permanently deletes all files in the project directory. This cannot be undone.

​
Response

​
message
string
Success message
​
status
string
Always “success”
​
old_project
object
The deleted project object

​
Set Default Project

Set a project as the default. 
curl -X PUT https://api.basicmemory.com/v2/projects/{project_id}/default \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
message
string
Success message
​
status
string
Always “success”
​
old_project
object
Previously default project
​
new_project
object
New default project

​
Sync Project

Force synchronization between filesystem and database. 
curl -X POST "https://api.basicmemory.com/v2/projects/{project_id}/sync?force_full=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

​
force_full
boolean
default:"false"
Force full scan instead of incremental sync
​
run_in_background
boolean
default:"true"
Run sync in background (returns immediately)

​
Response (Background)

​
status
string
“sync_started”
​
message
string
Status message

​
Response (Foreground)

​
files_created
integer
Number of new files indexed
​
files_updated
integer
Number of updated files reindexed
​
files_deleted
integer
Number of deleted files removed from index
​
files_unchanged
integer
Number of unchanged files skipped
​
total_time_seconds
number
Total sync duration in seconds

​
Get Project Status

Get detailed sync status for a project (dry-run scan). 
curl -X POST "https://api.basicmemory.com/v2/projects/{project_id}/status?force_full=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

​
force_full
boolean
default:"false"
Force full scan instead of incremental check

​
Response

Same as Sync Project foreground response.

​
Synchronize Configuration

Sync projects between configuration file and database. 
curl -X POST https://api.basicmemory.com/v2/projects/config/sync \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
message
string
Success message
​
status
string
Always “success”
This endpoint is primarily used internally during startup and after configuration changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us