Skip to content
Developer docs
Docs menu

5-minute quickstart

Markdown

Write 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

The TypeScript SDK package is @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.
TypeScript
npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgz

Anywhere 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:

curl
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.

Sign-up is limited by capacity. When the day's new accounts are used up or sign-up is closed for a while, new accounts cannot be created and the console says why, so try again later. New accounts need approval: until then you can sign in and create keys, but calling the API with a key returns 403 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
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: searchable means lexical search can already find the text; it becomes indexed once 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.

curl
# -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.

curl
# 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.

curl
# 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}'
diff
--- /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.

curl
# 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
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}]}'
json
{
  "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 Code
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

  1. Learn how Entries, versions, files, knowledge, and memory fit together.
  2. Search the files, or get evidence for your own model with context.
  3. Write a memory, or ingest a conversation for the service to distill memories from.
  4. Give each end user a Space of their own, found by your own user id.
  5. Have an Agent's writes go through proposals and review, or limit the directories it can write to.
  6. Keep a Space in sync with the change feed and snapshots.