# 5-minute quickstart

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

> **Note:** 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](https://mirabase.io/developers/sdks.md#install). 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:

```bash
npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgz
```

Python:

```bash
pip install https://mirabase.io/sdk/mirabase-0.3.0rc1-py3-none-any.whl
```

curl:

```bash
# The curl examples read fields with jq, for example:
# macOS: brew install jq
# Debian or Ubuntu: sudo apt-get install jq

# The curl examples use $SPACE_ID; default stands for your default Space.
export SPACE_ID=default
```

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](https://console.mirabase.dev), 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:

```bash
export MIRABASE_API_KEY="mb_live_..."

curl https://api.mirabase.dev/v2/whoami \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
import { Mirabase } from "@mirabase/sdk/developer";

// Reads MIRABASE_API_KEY when apiKey is omitted.
const mirabase = new Mirabase({ apiKey: process.env.MIRABASE_API_KEY });

const me = await mirabase.whoami();
```

Python:

```python
from mirabase import Mirabase

# Reads MIRABASE_API_KEY when api_key is omitted.
mb = Mirabase()

me = mb.whoami()
```

`effective_capabilities` in the response is what this key can do right now. See [Authentication and API keys](https://mirabase.io/developers/authentication.md).

> **Note:** 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`](https://mirabase.io/developers/api/files.md#files-write) is the file. You do not need to create parent directories first. When the response returns, the write is committed and readable:

curl:

```bash
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)
```

TypeScript:

```ts
const path = "/notes/launch.md";

const v1 = await mirabase.files.write(path, "The launch is on March 14.\nTina owns the checklist.\n", {
  contentType: "text/markdown",
});
console.log(v1.version_id, v1.entry.id, v1.entry.knowledge.state);
```

Python:

```python
path = "/notes/launch.md"

v1 = mb.files.write(path, "The launch is on March 14.\nTina owns the checklist.\n", content_type="text/markdown")
print(v1["version_id"], v1["entry"]["id"], v1["entry"]["knowledge"]["state"])
```

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

```bash
# -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"
```

TypeScript:

```ts
const file = await mirabase.files.read(path);
console.log(file.text());
console.log(file.etag); // the version you read
```

Python:

```python
file = mb.files.read(path)
print(file.text())
print(file.etag)  # the version you read
```

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

```bash
# 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}'
```

TypeScript:

```ts
// Fails with 412 if the file changed after you read it.
const v2 = await mirabase.files.edit(path, { old_text: "March 14", new_text: "March 21" }, { ifMatch: file.etag });
console.log(v2.version_id, v2.previous_version_id);

// List the file's versions, newest first.
for await (const version of mirabase.files.versions(path)) {
  console.log(version.id, version.updated_from ?? null, version.created_at);
}
```

Python:

```python
# Fails with 412 if the file changed after you read it.
v2 = mb.files.edit(path, {"old_text": "March 14", "new_text": "March 21"}, if_match=file.etag)
print(v2["version_id"], v2.get("previous_version_id"))

# List the file's versions, newest first.
for version in mb.files.versions(path):
    print(version["id"], version.get("updated_from"), version["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:

```bash
# 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}'
```

TypeScript:

```ts
// Compare version 1 with the latest version.
const diff = await mirabase.versions.diff({ path }, v1.version_id);
console.log(diff.unified_diff);

// Write version 1's content back as a new version.
const reverted = await mirabase.files.revert(path, v1.version_id);
console.log(reverted.latest_version_id);
```

Python:

```python
# Compare version 1 with the latest version.
diff = mb.versions.diff({"path": path}, v1["version_id"])
print(diff.get("unified_diff"))

# Write version 1's content back as a new version.
reverted = mb.files.revert(path, v1["version_id"])
print(reverted["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](https://mirabase.io/developers/permissions.md#agents).

curl:

```bash
# 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}'
```

TypeScript:

```ts
// 1. Create a branch for the Agent. Main does not change until the merge.
const branch = await mirabase.branches.create({ name: "agent/checklist" });

// 2. The Agent writes to the branch.
await mirabase.files.write("/notes/checklist.md", "- [ ] Freeze the API\n- [ ] Publish the SDK\n", {
  branch: branch.id,
  contentType: "text/markdown",
});

// 3. Create a checkpoint that the branch can roll back to.
const checkpoint = await mirabase.branches.checkpoints.create(branch.id, "draft-1");
console.log(checkpoint.id);

// 4. Compare the branch with main.
for await (const change of mirabase.branches.diff(branch.id)) {
  console.log(change.change, change.path);
  console.log(change.unified_diff);
}

// 5. Merge into main. The SDK sends the Idempotency-Key automatically.
const merged = await mirabase.branches.merge(branch.id, { message: "Add the launch checklist", on_conflict: "abort" });
console.log(merged.state, merged.merged);
```

Python:

```python
# 1. Create a branch for the Agent. Main does not change until the merge.
branch = mb.branches.create({"name": "agent/checklist"})

# 2. The Agent writes to the branch.
mb.files.write(
    "/notes/checklist.md",
    "- [ ] Freeze the API\n- [ ] Publish the SDK\n",
    branch=branch["id"],
    content_type="text/markdown",
)

# 3. Create a checkpoint that the branch can roll back to.
checkpoint = mb.branches.checkpoints.create(branch["id"], "draft-1")
print(checkpoint["id"])

# 4. Compare the branch with main.
for change in mb.branches.diff(branch["id"]):
    print(change["change"], change["path"])
    print(change.get("unified_diff"))

# 5. Merge into main. The SDK sends the Idempotency-Key automatically.
merged = mb.branches.merge(branch["id"], {"message": "Add the launch checklist", "on_conflict": "abort"})
print(merged["state"], merged["merged"])
```

For branch expiry, rollback, and large merges, see [Branches and checkpoints](https://mirabase.io/developers/branches.md).

## Step 7: Ask about the files and get citations

[`POST /v2/retrieval/answer`](https://mirabase.io/developers/api/retrieval.md#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:

```bash
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}]}'
```

TypeScript:

```ts
const reply = await mirabase.answer("When is the launch, and who owns the checklist?");
if (reply.status === "answered") console.log(reply.answer, reply.citations);
else console.log("abstained:", reply.reason);
```

Python:

```python
reply = mb.answer("When is the launch, and who owns the checklist?")
if reply["status"] == "answered":
    print(reply["answer"], reply["citations"])
else:
    print("abstained:", reply.get("reason"))
```

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

```bash
claude mcp add --transport http mirabase https://api.mirabase.dev/mcp \
  --header "Authorization: Bearer $MIRABASE_API_KEY"
```

Codex:

```bash
codex mcp add mirabase --url https://api.mirabase.dev/mcp \
  --bearer-token-env-var MIRABASE_API_KEY
```

JSON:

```json
{
  "mcpServers": {
    "mirabase": {
      "type": "http",
      "url": "https://api.mirabase.dev/mcp",
      "headers": {
        "Authorization": "Bearer mb_live_..."
      }
    }
  }
}
```

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)](https://mirabase.io/developers/agents.md#tools).

## Next steps

1. Learn how [Entries, versions, files, knowledge, and memory](https://mirabase.io/developers/concepts.md) fit together.
2. [Search](https://mirabase.io/developers/retrieval.md#search) the files, or get evidence for your own model with [context](https://mirabase.io/developers/retrieval.md#context).
3. [Write a memory](https://mirabase.io/developers/memory.md#create), or [ingest a conversation](https://mirabase.io/developers/memory.md#conversation) for the service to distill memories from.
4. Give each end user [a Space of their own](https://mirabase.io/developers/concepts.md#space-per-user), found by your own user id.
5. Have an Agent's writes [go through proposals and review](https://mirabase.io/developers/files.md#proposals), or [limit the directories it can write to](https://mirabase.io/developers/permissions.md#roots).
6. Keep a Space in sync with the [change feed and snapshots](https://mirabase.io/developers/sync.md).
