5-minute quickstart
MarkdownWrite and read a file by path, edit it and see its versions, compare and revert; let an Agent change files on a branch and merge; get an answer that cites the file version; connect an Agent over MCP.
Before you begin
@mirabase/sdk. The examples import it from @mirabase/sdk/developer; it requires Node.js 20.3 or newer and ships as ES modules only, so add each step's example to quickstart.mjs in order and run it with node quickstart.mjs. The Python SDK package is mirabase and requires Python 3.11 or newer. Both are 0.x releases, so method names may still change before 1.0. The versions currently served are release candidates; see SDK. Each step's example continues the one before it and reuses its variables. mirabase (TypeScript) and mb (Python) are the clients created in step 1, and the examples on the other pages use them too.npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgzAnywhere a Space id goes you can write default: it means your own default Space, or the only Space the key can see. The SDKs use the default Space when you name none. The curl examples require bash or zsh, where $'…' converts \n into a newline.
Step 1: Sign up and create an API key
Open the console, sign in, and accept the terms. The sign-in methods are whichever the sign-in page actually offers, and the same verified email reaches the same account through any of them. Your first sign-in automatically creates your tenant and a default Space. Then create a key on the API keys page. The console shows the secret only once, so store it now. Put it in an environment variable and check that it works:
export MIRABASE_API_KEY="mb_live_..."
curl https://api.mirabase.dev/v2/whoami \
-H "Authorization: Bearer $MIRABASE_API_KEY"effective_capabilities in the response is what this key can do right now. See Authentication and API keys.
account_pending_approval. After approval every key works at once, with no need to create new ones.Step 2: Write a file by path
The body of PUT /v2/spaces/{space_id}/files is the file. You do not need to create parent directories first. When the response returns, the write is committed and readable:
curl -s -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary $'The launch is on March 14.\nTina owns the checklist.\n' \
| tee v1.json | jq '{version_id, entry_id: .entry.id, state: .entry.knowledge.state}'
# Save the id of this first version for steps 4 and 5.
export V1=$(jq -r .version_id v1.json)entry.id: the file's stable identity, which does not change across renames and moves.version_id: the immutable version this write created. Later steps use it to compare and revert.entry.knowledge.state:searchablemeans lexical search can already find the text; it becomesindexedonce processing finishes.
Step 3: Read the file
Read the same path to get back the raw bytes you wrote. The ETag is the version you read; the next step uses it for a conditional write.
# -i prints the headers too: ETag and Mirabase-Version-Id identify the version you read.
curl -i "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Step 4: Edit the file and see its versions
PATCH replaces exact text and creates a new version. With If-Match, the request fails with 412 if another caller or Agent wrote to the file in the meantime, so their change is not overwritten. The version list is ordered from newest to oldest, and updated_from points to the previous version.
# If-Match: the edit fails with 412 if the file changed after version 1.
curl -s -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "If-Match: \"$V1\"" \
-H "Content-Type: application/json" \
-d '{"edits": [{"old_text": "March 14", "new_text": "March 21"}]}' \
| jq '{version_id, previous_version_id}'
# List the file's versions, newest first.
curl -s "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/versions?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
| jq '.data[] | {id, updated_from, created_at}'Step 5: Compare and revert
Compare version 1 with the latest version to get a unified diff. A revert writes the old version's content as a new version; all earlier versions are kept, so a revert can be reverted too.
# Compare version 1 with the latest version.
curl -s "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/launch.md&from=$V1" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
| jq -r .unified_diff
# Write version 1's content back as a new version.
curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/revert?path=/notes/launch.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"version_id": "'$V1'"}' \
| jq '{latest_version_id}'--- /notes/launch.md@ver_eba2c457e8456f97
+++ /notes/launch.md@ver_5e7d2e469ac6c42a
@@ -1,2 +1,2 @@
-The launch is on March 14.
+The launch is on March 21.
Tina owns the checklist.Step 6: Let an Agent work on a branch
An Agent's changes are written to a branch first, while main remains unchanged. A checkpoint records the current state of the branch, and the branch can roll back to it. Review the branch's diff against main before you merge; with on_conflict: "abort", the merge does not take effect if the same path was modified on main. In practice, issue the Agent its own narrowly scoped API key.
# 1. Create a branch for the Agent. Main does not change until the merge.
export BRANCH_ID=$(curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "agent/checklist"}' | jq -r .id)
# 2. The Agent writes to the branch.
curl -s -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/checklist.md&branch=$BRANCH_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary $'- [ ] Freeze the API\n- [ ] Publish the SDK\n' \
| jq '{path, changed}'
# 3. Create a checkpoint that the branch can roll back to.
curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/checkpoints" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "draft-1"}' | jq '{id, name}'
# 4. Compare the branch with main.
curl -s "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/diff" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
| jq -r '.data[] | "\(.change) \(.path)\n\(.unified_diff)"'
# 5. Merge into main. Idempotency-Key is required so a retry cannot merge twice.
curl -s -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/merge" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: merge-$BRANCH_ID" \
-H "Content-Type: application/json" \
-d '{"message": "Add the launch checklist", "on_conflict": "abort"}' \
| jq '{state, merged}'For branch expiry, rollback, and large merges, see Branches and checkpoints.
Step 7: Ask about the files and get citations
POST /v2/retrieval/answer selects evidence from files, knowledge, and memory, uses a model to generate an answer, and marks citations in the body text as [cN]. Each citation points to a specific version of an Entry: here version_id is the version created by the revert in step 5. When evidence is insufficient, it returns abstained instead of fabricating an answer.
curl -s -X POST https://api.mirabase.dev/v2/retrieval/answer \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "When is the launch, and who owns the checklist?"}' \
| jq '{status, answer, reason, citations: [.citations[] | {citation_id, path, version_id}]}'{
"status": "answered",
"answer": "The launch is on March 14, and Tina owns the checklist [c1].",
"citations": [
{
"citation_id": "c1",
"entry_id": "ent_cecf61d9d54a1dbb",
"version_id": "ver_0b611ffa8bd0b060",
"space_id": "col_91f8c425c93c2f99",
"path": "/notes/launch.md",
"modified_at": "2026-11-17T05:19:34.078Z",
"title": "launch.md",
"source": "knowledge",
"text": "The launch is on March 14.\nTina owns the checklist.\n"
}
],
"evidence_count": 2,
"pack_id": "trc_b67b4d4494102309",
"partial": false
}Step 8: Connect an Agent over MCP
Over MCP, an Agent reads and writes the same files and sees the same versions returned by the API and the SDKs. Add Mirabase to Claude Code or Codex, or add the JSON configuration to any client that supports remote MCP:
claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \
--header "Authorization: Bearer $MIRABASE_API_KEY"After connecting, ask the Agent: “Read /notes/launch.md and /notes/checklist.md in Mirabase and list what is left before the launch.” The MCP tools list, read, write, edit, and delete files, and cover search, answers, and memory; versions and branches are currently available through the API and the SDKs. For the tool list, see Connect an Agent (MCP).
Next steps
- Learn how Entries, versions, files, knowledge, and memory fit together.
- Search the files, or get evidence for your own model with context.
- Write a memory, or ingest a conversation for the service to distill memories from.
- Give each end user a Space of their own, found by your own user id.
- Have an Agent's writes go through proposals and review, or limit the directories it can write to.
- Keep a Space in sync with the change feed and snapshots.
