API

Programmatic access for your memory runtime.

Public runtime documentation for the tree-first Mindcache runtime: source inputs, atom memory nodes, daily writeups, topic trees, and digest maintenance.

Every runtime endpoint documented below is API-key-first. Website account, session, billing portal, and Stripe webhook flows stay outside this public surface. Topics are the primary retrieval structure; the graph endpoint remains available as a secondary atom-layer/debug view.

Authentication

Manage your API keys from Profile

You do not need to sign in to read this documentation. When you are ready to call the runtime, create and revoke your personal API keys from Profile.

Example

Authenticate requests

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Send your key as Authorization: Bearer ... or X-API-Key. Runtime requests using these keys still count toward the same user-level usage and billing totals.

Access model

API-key-only runtime surface

Public docs, private runtime

Anyone can read the docs on this page. Runtime endpoints require a valid API key on every call.

Tree-first retrieval

Topic tree search is the primary retrieval path. Source docs, atom nodes, and graph inspection remain available as supporting surfaces.

Key lifecycle

Create, expire, and revoke API keys from Profile without changing your website login session.

Runtime API

Reference

Base URLhttps://api.mindcache.co

AuthenticationBearer API key required

Playground flowworkspace → import → search/retrieve → digest

Response envelope{ ok: true, data: ... }

Error envelope{ ok: false, error: { code, message } }

Quickstart

Create a workspace and start sending memory

export MINDCACHE_API_KEY="YOUR_API_KEY"
curl -s https://api.mindcache.co/v1/demo/workspaces \
  -H "Authorization: Bearer $MINDCACHE_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{}'

curl -s https://api.mindcache.co/v1/demo/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{}'

Atom filtering

Request the leaf-layer atom surface with an importance threshold

curl -s "https://api.mindcache.co/v1/demo/workspaces/ws_123/graph?min_importance=0.5" \
  -H "Authorization: Bearer $MINDCACHE_API_KEY"

POST/v1/demo/workspaces

Create or resume a workspace

Creates a protected playground workspace for the API-key owner, or resumes the existing active one.

Body

{}

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "kind": "playground",
      "status": "active"
    }
  }
}

GET/v1/demo/workspaces/{workspace_id}

Get workspace

Returns workspace metadata for an existing playground workspace.

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "kind": "playground",
      "status": "active",
      "runtime_db_path": "/var/lib/..."
    }
  }
}

POST/v1/demo/workspaces/{workspace_id}/import/text

Import source text

Classifies raw input as snippet, resource, or writeup; extracts atom memory nodes (`fact`, `event`, `plan`); and returns the refreshed leaf-layer workspace surface.

Body

{
  "text": "Met Annie in Singapore to discuss a local-first memory runtime.",
  "client_time": "2026-03-29T11:00:00+08:00"
}

Response

{
  "ok": true,
  "data": {
    "import": {
      "source": {
        "id": "src_123",
        "classification": "snippet",
        "tags": [
          "personal",
          "project"
        ]
      },
      "deduplicated": false,
      "recognized_node_count": 1,
      "new_node_count": 1
    },
    "graph": {
      "nodes": [
        {
          "id": "node_1",
          "node_type": "fact",
          "tldr": "Met Annie in Singapore."
        }
      ],
      "edges": []
    },
    "embedding_status": {
      "mode": "vec",
      "sqlite_vec_available": true
    }
  }
}

POST/v1/demo/workspaces/{workspace_id}/import/calendar

Import calendar

Accepts multipart upload of `.ics` or Google Calendar export `.zip` and imports structured calendar events.

Body

multipart/form-data with file field `file`

Response

{
  "ok": true,
  "data": {
    "calendar_import": {
      "created": 4,
      "updated": 1,
      "skipped": 0
    },
    "graph": {
      "nodes": [],
      "edges": []
    }
  }
}

GET/v1/demo/workspaces/{workspace_id}/graph?min_importance=0.5

Fetch leaf-layer surface

Returns the current leaf-layer atom surface used for debug and inspection. Tree-first retrieval should usually go through topics; this endpoint is the secondary atom view and supports an importance threshold.

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "kind": "playground",
      "status": "active"
    },
    "graph": {
      "nodes": [
        {
          "id": "node_1",
          "node_type": "fact",
          "tldr": "Met Annie in Singapore."
        }
      ],
      "edges": []
    },
    "embedding_status": {
      "mode": "vec",
      "sqlite_vec_available": true
    }
  }
}

GET/v1/demo/workspaces/{workspace_id}/sources

List sources

Returns original source inputs and material-layer metadata. This is the raw/source view, not the extracted atom view.

Response

{
  "ok": true,
  "data": {
    "sources": [
      {
        "id": "src_123",
        "source_type": "text",
        "classification": "resource",
        "tags": [
          "research",
          "memory"
        ],
        "raw_text": "Memory systems should separate source materials from atom nodes...",
        "source_summary": "Essay arguing for topic-tree-first memory architecture.",
        "search_keywords": [
          "memory",
          "topic tree",
          "retrieval"
        ],
        "suggested_topics": [
          "memory architecture",
          "topic tree retrieval"
        ],
        "published_at": "2026-04-11T08:00:00Z",
        "written_from": null,
        "created_at": "2026-04-11T09:15:00Z"
      }
    ]
  }
}

GET/v1/demo/workspaces/{workspace_id}/nodes/{node_id}

Fetch node detail

Returns the full atom detail together with connected leaf-layer neighbor references. Resource metadata is returned when available, but the main payload is atom-centric.

Response

{
  "ok": true,
  "data": {
    "detail": {
      "node": {
        "id": "node_1",
        "node_type": "fact",
        "tldr": "Met Annie in Singapore.",
        "importance": 0.78,
        "confidence": 0.91
      },
      "document": null,
      "connected_node_ids": [
        "node_2",
        "node_3"
      ],
      "neighbors": [
        {
          "edge_id": "edge_1",
          "from_node_id": "node_1",
          "to_node_id": "node_2",
          "relation_type": "mentions",
          "node_id": "node_2",
          "node_type": "fact"
        }
      ]
    }
  }
}

DELETE/v1/demo/workspaces/{workspace_id}/nodes/{node_id}

Delete memory node

Deletes a memory node plus its edges, source links, embeddings, and any topics left empty by that removal.

Response

{
  "ok": true,
  "data": {
    "deleted_node_id": "node_1",
    "graph": {
      "nodes": [],
      "edges": []
    },
    "topics": {
      "topics": []
    },
    "sources": [],
    "embedding_status": {
      "mode": "vec"
    }
  }
}

PUT/v1/demo/workspaces/{workspace_id}/sources/{source_id}

Update source text

Replaces an editable text source by running delete plus create, then returns the refreshed graph, topics, and sources.

Body

{
  "text": "Updated note about the memory runtime roadmap.",
  "client_time": "2026-03-29T11:05:00+08:00"
}

Response

{
  "ok": true,
  "data": {
    "import": {
      "source": {
        "id": "src_456",
        "classification": "writeup",
        "tags": [
          "work",
          "project"
        ]
      }
    },
    "graph": {
      "nodes": [],
      "edges": []
    },
    "topics": {
      "topics": []
    },
    "sources": []
  }
}

DELETE/v1/demo/workspaces/{workspace_id}/sources/{source_id}

Delete source

Deletes a source and cleans up any nodes or topics that are no longer backed by another source.

Response

{
  "ok": true,
  "data": {
    "deleted_source_id": "src_123",
    "graph": {
      "nodes": [],
      "edges": []
    },
    "topics": {
      "topics": []
    },
    "sources": []
  }
}

POST/v1/demo/workspaces/{workspace_id}/search/exact

Exact search

Performs exact lexical retrieval over the workspace atom and topic surfaces.

Body

{
  "query": "Singapore",
  "limit": 10
}

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "kind": "playground",
      "status": "active"
    },
    "search": {
      "mode": "exact",
      "query": "Singapore",
      "results": [
        {
          "node_id": "node_1",
          "node_type": "fact",
          "score": 1,
          "matched_by": "exact",
          "source_ref": "src_123"
        }
      ]
    }
  }
}

POST/v1/demo/workspaces/{workspace_id}/search/semantic

Semantic search

Runs semantic retrieval over the workspace atoms using sqlite-vec when available, then payload cosine fallback.

Body

{
  "query": "local-first memory runtime",
  "limit": 10
}

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "kind": "playground",
      "status": "active"
    },
    "search": {
      "mode": "semantic",
      "query": "local-first memory runtime",
      "results": [
        {
          "node_id": "node_2",
          "node_type": "event",
          "score": 0.93,
          "matched_by": "vec",
          "source_ref": "src_456"
        }
      ]
    }
  }
}

POST/v1/demo/workspaces/{workspace_id}/search/topics

Topic search

Searches the topic tree surface for fast recall paths and topic-first routing.

Body

{
  "query": "memory runtime",
  "limit": 10
}

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "kind": "playground",
      "status": "active"
    },
    "search": {
      "mode": "topics",
      "query": "memory runtime",
      "results": [
        {
          "node_id": "topic_1",
          "node_type": "topic",
          "score": 0.89,
          "matched_by": "topics",
          "source_ref": "topic_1"
        }
      ]
    }
  }
}

GET/v1/demo/workspaces/{workspace_id}/daily-writeups

List daily writeups

Returns persisted daily writeups. These are daily refinement artifacts used to reconcile atom memory nodes and drive the date view.

Response

{
  "ok": true,
  "data": {
    "daily_writeups": [
      {
        "id": "dw_123",
        "day_key": "2026-04-11",
        "summary": "Reviewed topic-tree search ideas, refined atom ontology, and recorded implementation follow-ups.",
        "source_ids": [
          "src_123",
          "src_456"
        ],
        "node_ids": [
          "node_1",
          "node_2",
          "node_3"
        ],
        "created_at": "2026-04-11T20:00:00Z",
        "updated_at": "2026-04-11T20:04:00Z"
      }
    ]
  }
}

POST/v1/demo/workspaces/{workspace_id}/digest/daily

Run digest

Runs the tree-first daily digest: daily writeup refinement and atom reconciliation first, then either cold-start topic rebuild or post-cold-start local topic maintenance.

Response

{
  "ok": true,
  "data": {
    "digest": {
      "mode": "local_update",
      "atom_count": 143,
      "reconciled_atom_count": 6,
      "isolated_atom_count": 3,
      "topic_update_count": 2,
      "attached_atom_count": 2,
      "revised_topic_count": 1,
      "split_topic_count": 0
    },
    "graph": {
      "nodes": [],
      "edges": []
    }
  }
}

GET/v1/demo/workspaces/{workspace_id}/topics

List topics

Returns the current topic tree view with searchable topic metadata and anchor membership.

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "kind": "playground",
      "status": "active"
    },
    "topics": {
      "topics": [
        {
          "topic": {
            "id": "topic_1",
            "title": "Memory runtime architecture",
            "summary": "Topic-tree-first memory architecture, digest reconciliation, and retrieval design.",
            "keywords": [
              "memory",
              "topic tree",
              "digest"
            ],
            "aliases": [
              "runtime memory",
              "memory architecture"
            ],
            "parent_topic_id": null,
            "status": "warm",
            "first_seen": "2026-04-11T09:15:00Z",
            "last_updated": "2026-04-11T21:00:00Z",
            "importance": 0.88
          },
          "anchors": [
            {
              "topic_id": "topic_1",
              "node_id": "node_1",
              "anchor_score": 0.94,
              "anchor_role": "representative"
            }
          ]
        }
      ]
    }
  }
}

DELETE/v1/demo/workspaces/{workspace_id}/topics/{topic_id}

Delete topic

Deletes a topic subtree, including topic anchors and source-topic provenance links for that branch.

Response

{
  "ok": true,
  "data": {
    "deleted_topic_id": "topic_1",
    "graph": {
      "nodes": [],
      "edges": []
    },
    "topics": {
      "topics": []
    },
    "sources": []
  }
}

POST/v1/demo/workspaces/{workspace_id}/reset

Clear workspace

Deletes current workspace memory and reinitializes an empty runtime database.

Response

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "ws_123",
      "status": "active"
    },
    "graph": {
      "nodes": [],
      "edges": []
    }
  }
}