Projects & Organization

Manage projects, browse the keypath tree, and list keypaths.

GET/projectsList projects

POST/projectsCreate project

GET/projects/{id}Get project

GET/treeKeypath tree

GET/keypathsList keypaths

GET/changelogProject changelog

POST/projects/deleteSoft-delete a project

GET/projects/{id}/revisionsList revisions

List Projects

GET/projects

List all projects for the authenticated user. Projects provide namespace isolation for memories.

Request

curl https://api.memstate.ai/api/v1/projects \
  -H "X-API-Key: mst_your_key"

200 OK

{
  "projects": [
    {
      "id": "my-saas",
      "name": "My SaaS Application",
      "description": "Production SaaS with billing and auth",
      "memory_count": 42,
      "git_remote": "https://github.com/user/my-saas",
      "created_at": "2026-01-15T08:00:00Z"
    }
  ],
  "total_projects": 1
}

Create or Update Project

POST/projects

Create a new project or update an existing one. If a project with the given ID already exists, its metadata will be updated.

Request Body

Parameter	Type	Required	Description
project_id	string	Required	Unique project identifier (lowercase, alphanumeric, hyphens allowed).
name	string	Optional	Human-readable project name.
description	string	Optional	Project description.
git_remote	string	Optional	Git remote URL for linking to the repository.
root_path	string	Optional	Root file path of the project on disk.

Request

curl -X POST https://api.memstate.ai/api/v1/projects \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "project_id": "my-saas",
    "name": "My SaaS Application",
    "description": "Production SaaS with billing, auth, and multi-tenancy",
    "git_remote": "https://github.com/user/my-saas"
  }'

Soft-Delete a Project

POST/projects/delete

Soft-delete an entire project and all its memories. The project is hidden from listings and every memory gets an individual tombstone version, preserving full history.

Request Body

Parameter	Type	Required	Description
project_id	string	Required	ID of the project to soft-delete.

Request

curl -X POST https://api.memstate.ai/api/v1/projects/delete \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "project_id": "old-project"
  }'

200 OK

{
  "project_id": "old-project",
  "deleted_keypaths": [
    "project.old-project.auth.provider",
    "project.old-project.config.port",
    "project.old-project.database.host"
  ],
  "deleted_count": 3,
  "message": "Soft-deleted project 'old-project' and 3 memory(ies)"
}

All memories are tombstoned

Every memory in the project receives its own tombstone version. The full version history is preserved and viewable via the /memories/history endpoint.

Keypath Tree

GET/tree

Get a hierarchical view of all keypaths organized by top-level domain. Shows the complete memory structure with counts.

Query Parameters

Parameter	Type	Required	Description
project_id	string	Optional	Filter by project.

Request

curl "https://api.memstate.ai/api/v1/tree?project_id=my-saas" \
  -H "X-API-Key: mst_your_key"

200 OK

{
  "project_id": "my-saas",
  "total_memories": 42,
  "domains": [
    {
      "name": "auth",
      "keypaths": [
        "auth.provider",
        "auth.registration",
        "auth.session",
        "auth.middleware"
      ],
      "memory_count": 4
    },
    {
      "name": "billing",
      "keypaths": [
        "billing.stripe",
        "billing.webhooks",
        "billing.pricing"
      ],
      "memory_count": 3
    },
    {
      "name": "api",
      "keypaths": [
        "api.endpoints",
        "api.rate_limiting",
        "api.versioning"
      ],
      "memory_count": 3
    }
  ]
}

List Keypaths

GET/keypaths

List all unique keypaths in memory. Useful for understanding the overall structure of stored knowledge.

Query Parameters

Parameter	Type	Required	Description
project_id	string	Optional	Filter by project.
prefix	string	Optional	Filter keypaths by prefix (e.g., "auth").

Request

curl "https://api.memstate.ai/api/v1/keypaths?project_id=my-saas&prefix=auth" \
  -H "X-API-Key: mst_your_key"

200 OK

{
  "keypaths": ["auth.provider", "auth.registration", "auth.session", "auth.middleware"],
  "total": 4,
  "project_id": "my-saas"
}

Project Changelog

GET/changelog

Get a time-ordered feed of all events across projects and memories. Useful for syncing state, building activity feeds, or tracking recent updates.

Query Parameters

Parameter	Type	Required	Description
project_id	string	Optional	Filter changelog by project.
since	string	Optional	Only return events after this ISO-8601 timestamp.
limit	integer	Default: 50	Maximum events to return.

Request

curl "https://api.memstate.ai/api/v1/changelog?project_id=my-saas&limit=2" \
  -H "X-API-Key: mst_your_key"

200 OK

{
  "events": [
    {
      "id": "evt_abc123",
      "type": "memory.versioned",
      "project_id": "my-saas",
      "memory_id": "mem_session01",
      "keypath": "auth.session",
      "occurred_at": "2026-03-20T10:30:00Z"
    },
    {
      "id": "evt_abc122",
      "type": "memory.created",
      "project_id": "my-saas",
      "memory_id": "mem_session01",
      "keypath": "auth.session",
      "occurred_at": "2026-03-20T10:15:00Z"
    }
  ],
  "has_more": true
}

Event Types

Supported event types include: memory.created, memory.versioned, memory.deleted, project.created, and project.deleted.

List Revisions

GET/projects/{id}/revisions

List the revision history for a project. Each ingestion creates a new revision, enabling time-travel queries.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	Project ID.

Query Parameters

Parameter	Type	Required	Description
limit	integer	Default: 20	Maximum revisions to return.

Request

curl "https://api.memstate.ai/api/v1/projects/my-saas/revisions?limit=5" \
  -H "X-API-Key: mst_your_key"

Using revisions for time-travel

Once you find a revision number you're interested in, use it with the Get by Keypath endpoint's at_revision parameter to see what the project's memory looked like at that point.