# Files and versions

Write, read, edit, and organize files, compare and revert versions, and handle Agent proposals.

## Write a file

[`PUT /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-write) creates or replaces a file. The request body is the file. When it returns, the write is committed and readable. Size limits, status codes, and headers are in the reference.

curl:

```bash
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary "Mirabase keeps files, knowledge and memory in one place."
```

TypeScript:

```ts
const written = await mirabase.files.write(
  "/notes/hello.md",
  "Mirabase keeps files, knowledge and memory in one place.",
  { contentType: "text/markdown" },
);
```

Python:

```python
written = mb.files.write(
    "/notes/hello.md",
    "Mirabase keeps files, knowledge and memory in one place.",
    content_type="text/markdown",
)
```

- Check `version_created` in the response: it is `false` when the bytes and media type are unchanged, and then no version is created and no quota is used.
- Without `Content-Type`, the file is stored as `application/octet-stream`.
- To return only once this version can be searched, send [Prefer: wait=N](https://mirabase.io/developers/api/files.md#files-write.Prefer). When the key already holds 4 waiting requests, the call does not wait and the response has no `Preference-Applied`.
- With a `branch` parameter the write goes to a branch instead of main. See [Branches and mounts](https://mirabase.io/developers/branches.md#reads).

## Record the time, metadata, and memory switch

A write can also record three things: when the content happened ([occurred_at](https://mirabase.io/developers/api/files.md#files-write.occurred_at)), your own metadata ([metadata](https://mirabase.io/developers/api/files.md#files-write.metadata)), and whether memory is distilled from it ([memory_exclude](https://mirabase.io/developers/api/files.md#files-write.memory_exclude)). They are kept on the file's Entry and do not change from version to version. The body of a `PUT` is the file's bytes, so the three travel as query parameters, and `metadata` is URL-encoded JSON.

```bash
# The body is the file, so the three values ride in the query. --url-query (curl 7.87 or newer)
# URL-encodes each one; metadata is a JSON object.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files" \
  --url-query "path=/recordings/2026-11-06-standup.m4a" \
  --url-query "occurred_at=2026-11-06T09:30:00+08:00" \
  --url-query 'metadata={"device":"recorder-01","room":"3f"}' \
  --url-query "memory_exclude=true" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: audio/mp4" \
  --data-binary @standup.m4a
```

- Only what you send changes: replacing a file leaves the items you did not send as they were. They apply even when the content is unchanged: writing the same bytes again with a new `occurred_at` returns `version_created: false`, and the time is updated.
- In each item of a [batch](https://mirabase.io/developers/files.md#batch) and in the completion request of a [large file](https://mirabase.io/developers/files.md#uploads), they are body fields of the same names.
- To change them later, use [`PATCH /v2/entries/{entry_id}`](https://mirabase.io/developers/api/entries.md#entries-update).

## Avoid overwriting changes

Without a condition the last write wins, and the version chain stays intact. To avoid overwriting, send the `ETag` you read in `If-Match`; to create only, send `If-None-Match: *`. The full rules for conditional requests are in [API conventions](https://mirabase.io/developers/conventions.md#conditional).

curl:

```bash
# Fails with 412 if someone wrote a newer version since you read this one.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H 'If-Match: "ver_2b10"' \
  -H "Content-Type: text/markdown" \
  --data-binary @hello.md

# Fails with 412 if the file already exists.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/new.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "If-None-Match: *" \
  -H "Content-Type: text/markdown" \
  --data-binary @new.md
```

TypeScript:

```ts
// Fails with 412 if someone wrote a newer version since you read this one.
await mirabase.files.write("/notes/hello.md", nextText, {
  contentType: "text/markdown",
  ifMatch: written.entry.file!.etag,
});

// Fails with 412 if the file already exists.
await mirabase.files.write("/notes/new.md", newText, { contentType: "text/markdown", createOnly: true });
```

Python:

```python
# Fails with 412 if someone wrote a newer version since you read this one.
mb.files.write(
    "/notes/hello.md",
    "Mirabase keeps files, knowledge and memory in one place, with every version kept.",
    content_type="text/markdown",
    if_match=written["entry"]["file"]["etag"],
)

# Fails with 412 if the file already exists.
mb.files.write("/notes/new.md", "A new note.", content_type="text/markdown", create_only=True)
```

On 412 `precondition_failed`, `current_version_id` in the error is the version now: read the file again, reapply your change, and write with the new `ETag`.

## Edit text

[`PATCH /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-patch) replaces strings, so you do not send the whole file. It works on UTF-8 text, and each `old_text` must appear exactly once unless `replace_all` is set.

```bash
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"edits": [{"old_text": "one place", "new_text": "a single place"}]}'
```

A failed edit creates no version. On `edit_no_match`, read the file again and edit; on `edit_ambiguous`, add context or set `replace_all`; when the file is too large or not text, replace it with `PUT`. Error codes and size limits are in the reference.

## Read a file

[`GET /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-read) reads by path and [`GET /v2/entries/{entry_id}/content`](https://mirabase.io/developers/api/entries.md#entries-content) reads by id. Both take the same parameters and read the latest version by default. [view](https://mirabase.io/developers/api/schemas.md#DevFileView) selects which form to return; the default is raw bytes. You can read the `text` view of a text file right after the write; the other views are available after processing finishes.

Send `version` to read an older version, `snapshot` to read through a snapshot (see [Snapshots](https://mirabase.io/developers/sync.md#snapshots)), and `Range` to read part of the bytes. The rules for each parameter are in the reference.

### Download URLs

To hand a large file to a browser or another service, sign a short-lived URL for the original bytes with [`GET /v2/spaces/{space_id}/files/content-url`](https://mirabase.io/developers/api/files.md#files-contenturl) or [`GET /v2/entries/{entry_id}/content-url`](https://mirabase.io/developers/api/entries.md#entries-contenturl). You can fetch the URL without the key.

curl:

```bash
# A signed URL for the original bytes, valid 60 to 300 seconds. Fetch it without the key.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/content-url?path=/videos/talk.mp4&expires_in=120" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
const link = await mirabase.files.contentUrl("/videos/talk.mp4", { expiresIn: 120 });
// link.url works until link.expires_at for anyone who holds it: treat it like the key.
const bytes = await fetch(link.url);
```

Python:

```python
from urllib.request import urlopen

link = mb.files.content_url("/videos/talk.mp4", expires_in=120)
# link["url"] works until link["expires_at"] for anyone who holds it: treat it like the key.
data = urlopen(link["url"]).read()
```

> **Warning:** Until it expires, anyone holding the URL can fetch the bytes, and revoking the key does not stop that, so treat the URL like the key.

## Organize directories

[`GET /v2/spaces/{space_id}/tree`](https://mirabase.io/developers/api/tree.md#tree-list) lists a directory. [`POST /v2/spaces/{space_id}/tree/operations`](https://mirabase.io/developers/api/tree.md#tree-operations) runs `mkdir`, `move`, `copy`, `delete`, and `restore` in order, and all of them apply or none do.

curl:

```bash
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operations": [
    {"op": "mkdir", "path": "/archive/2026"},
    {"op": "move", "from": "/notes/old.md", "to": "/archive/2026/old.md"},
    {"op": "copy", "from": "/templates/report.md", "to": "/reports/2026-11.md"},
    {"op": "delete", "path": "/drafts", "recursive": true}
  ]}'
```

TypeScript:

```ts
// All or none, in order. copy returns the new Entries in copies.
const done = await mirabase.tree.apply([
  { op: "mkdir", path: "/archive/2026" },
  { op: "move", from: "/notes/old.md", to: "/archive/2026/old.md" },
  { op: "copy", from: "/templates/report.md", to: "/reports/2026-11.md" },
  { op: "delete", path: "/drafts", recursive: true },
]);

// The shortcuts send one operation each.
await mirabase.tree.move("/notes/draft.md", "/notes/final.md");
```

Python:

```python
# All or none, in order. copy returns the new Entries in copies.
done = mb.tree.apply([
    {"op": "mkdir", "path": "/archive/2026"},
    {"op": "move", "from": "/notes/old.md", "to": "/archive/2026/old.md"},
    {"op": "copy", "from": "/templates/report.md", "to": "/reports/2026-11.md"},
    {"op": "delete", "path": "/drafts", "recursive": True},
])

# The shortcuts send one operation each.
mb.tree.move("/notes/draft.md", "/notes/final.md")
```

- `to` in a `move` or `copy` is the complete new path. When the target is occupied, the call returns 409 `path_conflict` and nothing is overwritten or merged.
- Keep the response's `delete_batch_id`: it restores everything that request deleted.
- Each copied file is a new Entry, listed in the response's `copies`. Its history is not copied, and it is processed like a new file.
- A subtree over the synchronous limit returns 409 `subtree_too_large`: run it as a job; see [Run large tree operations as jobs](https://mirabase.io/developers/files.md#jobs).

### Path rules

Paths are absolute: they start with `/` and have no trailing `/`. Names compare by NFKC and case folding, so `/Docs` and `/docs` are one directory. The full rules for length and characters are in [DevPath](https://mirabase.io/developers/api/schemas.md#DevPath).

`/.mirabase/` is reserved: writing there returns 403 `reserved_path`. The exception is `/.mirabase/skills/<name>/...`, which holds your skill files, and `context` reads their `SKILL.md`. `/.mirabase/memory/MEMORY.md` is a generated read-only view; see [Memory](https://mirabase.io/developers/memory.md#memory-md). On deployments with offline consolidation, so is `/.mirabase/memory/RECENT.md`; see [the index layout](https://mirabase.io/developers/memory.md#memory-index).

## Run large tree operations as jobs

A single `move`, `copy`, recursive `delete`, or `restore` by `delete_batch_id` over the synchronous limit runs as a job when you send `Prefer: respond-async`, and returns 202 with `job_id` and `Location: /v2/jobs/{job_id}`. Follow the job as described in [API conventions](https://mirabase.io/developers/conventions.md#jobs).

curl:

```bash
# One operation over the synchronous limit runs as a job: 202 with job_id.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d '{"operations": [{"op": "delete", "path": "/old-exports", "recursive": true}]}'

# Poll until status is succeeded or failed.
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
// Under the limit it runs right away; over it, the result is a JobReceipt.
const started = await mirabase.tree.start({ op: "delete", path: "/old-exports", recursive: true });
if ("job_id" in started) {
  let job = await mirabase.jobs.get(started.job_id);
  while (job.status === "queued" || job.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    job = await mirabase.jobs.get(started.job_id);
  }
  // A failed delete keeps what it did: restore it with job.result?.delete_batch_id.
}
```

Python:

```python
# Under the limit it runs right away; over it, the result is a JobReceipt.
started = mb.tree.start({"op": "delete", "path": "/old-exports", "recursive": True})
if "job_id" in started:
    # Polls until status is succeeded, failed, or cancelled.
    job = mb.jobs.wait(started["job_id"])
    # A failed delete keeps what it did: restore it with job["result"]["delete_batch_id"].
```

> **Warning:** A job `move` is one transaction, but `delete`, `restore`, and `copy` run in chunks and are not atomic: a failed delete job leaves a partly deleted tree, and `result.delete_batch_id` restores it.

## Write in a batch

[`POST /v2/spaces/{space_id}/files/batch`](https://mirabase.io/developers/api/files.md#files-batch) writes and deletes several small text files in one request. Each item commits on its own, and one failing does not stop the rest; each result has its own `status` and matches its item by position.

```bash
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/batch" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Idempotency-Key: import-2026-11-06" \
  -H "Content-Type: application/json" \
  -d '{"items": [
    {"op": "put", "path": "/notes/a.md", "content": "First note", "media_type": "text/markdown"},
    {"op": "delete", "path": "/notes/old.md"}
  ]}'
```

Sending the same `Idempotency-Key` again finishes a batch that was cut short: committed items replay and the rest run. A single `DELETE` returns 404 the second time, so use this endpoint when a retry must tell "done" from "never existed".

## Upload a large file

Files over 16 MiB go through a multipart upload: start it, get part URLs, `PUT` each part, then complete it. The path is resolved on completion, and from there it behaves like `PUT`, including `If-Match` and `If-None-Match: *`.

```bash
# 1. Start the upload. checksum_sha256 is the Base64 SHA-256 of the whole file.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/uploads" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/videos/talk.mp4", "size": 734003200, "media_type": "video/mp4",
       "checksum_sha256": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="}'

# 2. Ask for part URLs, at most 128 at a time. Each one lasts five minutes.
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"part_numbers": [1, 2, 3]}'

# 3. PUT each part to its URL with the returned required_headers, and keep each ETag.

# 4. Finish. The file appears at its path now.
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts": [{"part_number": 1, "etag": "\"9b2c\""}, {"part_number": 2, "etag": "\"71fd\""}]}'
```

- After an interruption, call [`POST /v2/uploads/{upload_id}/parts`](https://mirabase.io/developers/api/uploads.md#uploads-parts) again: it leaves out the parts already received, so the upload resumes.
- Part URLs and the upload session both expire, and after that you must start a new upload. The time limits are in the reference.

## Add a source without a path

[`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/developers/api/ingest.md#ingest-ingest) adds a URL, text, or a conversation (see [Memory](https://mirabase.io/developers/memory.md#conversation)) and returns 202 with `entry_id`, `version_id`, and `job_id`. One call makes one Entry, and the same content twice makes two, so send `Idempotency-Key` when retrying. A URL is fetched after the response, so a bad one shows up as a failed job.

```bash
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Idempotency-Key: article-2026-11-06" \
  -H "Content-Type: application/json" \
  -d '{"kind": "url", "url": "https://example.com/article"}'
```

Text and conversations take [redact_secrets](https://mirabase.io/developers/api/schemas.md#DevIngestText.redact_secrets), which replaces whatever looks like a credential before anything is stored. It only recognizes credentials with a clear shape, so it is no substitute for your own scrubbing. Conversations also take [memory_instructions](https://mirabase.io/developers/api/schemas.md#DevIngestConversation.memory_instructions), which tells distillation what matters in your app.

## Compare and revert versions

[`GET /v2/entries/{entry_id}/versions`](https://mirabase.io/developers/api/entries.md#entries-listversions) lists the chain, newest first. [`POST /v2/entries/{entry_id}/revert`](https://mirabase.io/developers/api/entries.md#entries-revert) writes an older version's content as a new version, without rewriting history.

```bash
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/versions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

curl -X POST "https://api.mirabase.dev/v2/entries/$ENTRY_ID/revert" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version_id": "ver_1a07"}'
```

[`GET /v2/entries/{entry_id}/diff?from=&to=`](https://mirabase.io/developers/api/entries.md#entries-diff) compares two versions, and [`GET /v2/entries/{entry_id}/lineage`](https://mirabase.io/developers/api/entries.md#entries-lineage) tells where the Entry came from and how each version came about. By path, use [`GET /v2/spaces/{space_id}/files/diff`](https://mirabase.io/developers/api/files.md#files-diff) and [`GET /v2/spaces/{space_id}/files/lineage`](https://mirabase.io/developers/api/files.md#files-lineage).

curl:

```bash
# Compare an older version with the latest.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/diff?path=/notes/hello.md&from=ver_1a07" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Where the file came from, and how each version came about.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files/lineage?path=/notes/hello.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
// An Entry by id, or by the path of its file.
const diff = await mirabase.versions.diff({ path: "/notes/hello.md" }, "ver_1a07");
if (!diff.identical) console.log(diff.unified_diff ?? diff.diff_omitted);

const lineage = await mirabase.versions.lineage({ path: "/notes/hello.md" });
console.log(lineage.origin.kind, lineage.data.map((version) => version.kind));
```

Python:

```python
# An Entry by id, or by the path of its file. The older version here is the quickstart's write.
diff = mb.versions.diff({"path": "/notes/hello.md"}, written["version_id"])
if not diff["identical"]:
    print(diff.get("unified_diff") or diff.get("diff_omitted"))

lineage = mb.versions.lineage({"path": "/notes/hello.md"})
print(lineage["origin"]["kind"], [version["kind"] for version in lineage["data"]])
```

An Agent editing a file can record which conversation the change came from: send [session_id](https://mirabase.io/developers/api/files.md#files-write.session_id) on `PUT` and `PATCH` writes on main, with the same value the conversation was ingested with. `lineage` shows it on that version, and [`GET /v2/entries?metadata={"session_id":"…"}`](https://mirabase.io/developers/api/entries.md#entries-list) finds the conversation later.

> **Warning:** If processing a replaced file's new version fails for good, the path falls back to the last version that worked, and `changes` reports it, so a `200` does not promise the path keeps those bytes. The failed version stays in `versions` as `discarded`: read its bytes with `version` or bring it back with `revert`. Check `knowledge.state` when you need to know the new version took.

## Check processing status

[`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/developers/api/entries.md#entries-processing) and [`GET /v2/jobs/{job_id}`](https://mirabase.io/developers/api/jobs.md#jobs-read) report processing progress. [`POST /v2/entries/{entry_id}/reprocess`](https://mirabase.io/developers/api/entries.md#entries-reprocess) retries a failed version or processes the latest one again. To wait until a file is searchable or follow a bulk import, see [Processing status](https://mirabase.io/developers/processing.md).

## Delete and erase

| Operation | Effect | Requires | Undo |
| --- | --- | --- | --- |
| `DELETE` a file or Entry | Moves to the trash and leaves search at once | `knowledge:write` and editor | Yes, with `restore` |
| [`POST /v2/entries/{entry_id}/purge`](https://mirabase.io/developers/api/entries.md#entries-purge) | Erases the Entry, every version, and its path | `knowledge:manage` and the Space owner | No |

> **Note:** Erasure is not charged against quota, so it still works when the quota is used up.

## Handle Agent proposals

When an Agent changes a file it does not own, the call returns 403 `proposal_required` by default, and nothing is created. It can write directly once the Space owner sets its `write_mode` to `direct`; see [Permissions](https://mirabase.io/developers/permissions.md#write-mode). Otherwise, the Agent can send `Prefer: handling=proposal` to turn the write into a proposal: the file stays as it is, the call returns 202 with `proposal_id`, and a reviewer decides. File `PUT` and `PATCH`, `files/batch`, the completion of a multipart upload, and branch merges all take this header.

curl:

```bash
# As the Agent: propose instead of failing with 403 proposal_required.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/plan.md" \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Prefer: handling=proposal" \
  -H "Content-Type: text/markdown" \
  --data-binary @plan.md

# As a reviewer: open proposals, what each one changes, then decide.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/proposals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

curl "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/diff" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

curl -X POST "https://api.mirabase.dev/v2/proposals/$PROPOSAL_ID/approve" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Agreed plan"}'
```

TypeScript:

```ts
// As the Agent. On its own files and new files this is an ordinary write.
const agent = new Mirabase({ apiKey: process.env.AGENT_KEY });
const submitted = await agent.proposals.submit("/notes/plan.md", nextPlan, { contentType: "text/markdown" });
if ("proposal_id" in submitted) {
  // Poll until a reviewer acts: status leaves "open".
  const proposal = await agent.proposals.get(submitted.proposal_id);
}

// As a reviewer.
for await (const proposal of mirabase.proposals.list()) {
  const change = await mirabase.proposals.diff(proposal.id);
  if (change.unified_diff?.includes("Thursday")) {
    await mirabase.proposals.approve(proposal.id, { message: "Agreed plan" });
  } else {
    await mirabase.proposals.reject(proposal.id);
  }
}
```

Python:

```python
import os

# As the Agent. On its own files and new files this is an ordinary write.
agent = Mirabase(api_key=os.environ["AGENT_KEY"])
submitted = agent.proposals.submit(
    "/notes/plan.md",
    "Releases move to Thursday.",
    content_type="text/markdown",
)
if "proposal_id" in submitted:
    # Poll until a reviewer acts: status leaves "open".
    proposal = agent.proposals.get(submitted["proposal_id"])

# As a reviewer.
for proposal in mb.proposals.list():
    change = mb.proposals.diff(proposal["id"])
    if "Thursday" in change.get("unified_diff", ""):
        mb.proposals.approve(proposal["id"], message="Agreed plan")
    else:
        mb.proposals.reject(proposal["id"])
```

- It only acts when the write would otherwise return 403: your own files and new files are written directly.
- Moving, deleting, and restoring other people's files, `revert`, and memory writes cannot be proposed and still return 403.
- Reviewers are the Space owner and editors who can change the file directly: people, and Agents in `direct` mode with the file inside their `write_root`.
- A proposal is not a version: only its author and the Space owner see the proposed content in `versions`, and search never returns it.

## Next steps

- [Sync, snapshots, and export](https://mirabase.io/developers/sync.md): keep up with changes to files.
- [Retrieval and context](https://mirabase.io/developers/retrieval.md): search what you wrote.
- [API conventions](https://mirabase.io/developers/conventions.md#conditional): the general rules for conditional requests and idempotency.
