# Mirabase Developer docs

> One API for a file system, a knowledge base, and memory. The same Entry can be reached by path, by id, or by meaning, with one set of permissions and one version chain.

Every page of these docs has a Markdown version at the page's address plus `.md`. The links below are those addresses.

- Base URL: `https://api.mirabase.dev`
- Authentication: `Authorization: Bearer mb_live_...`
- OpenAPI: https://api.mirabase.dev/v2/openapi.yaml
- Guide for Agents: https://api.mirabase.dev/llms.txt
- SDK: TypeScript: `npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgz`. Python: `pip install https://mirabase.io/sdk/mirabase-0.3.0rc1-py3-none-any.whl`

## Contents

- [5-minute quickstart](https://mirabase.io/developers/quickstart.md): 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.
- [Authentication and API keys](https://mirabase.io/developers/authentication.md): Send, create, limit, rotate, and revoke API keys.
- [SDK](https://mirabase.io/developers/sdks.md): Install and configure the TypeScript and Python clients, and learn what they handle for you: Space selection, streaming answers, errors, retries, and pagination.
- [Core concepts](https://mirabase.io/developers/concepts.md): The data model behind the API: Spaces, Entries and versions, files, knowledge, memory, branches, and access control.
- [Glossary](https://mirabase.io/developers/glossary.md): The terms these docs use, each defined in one sentence and linked to the page that explains it.
- [Files and versions](https://mirabase.io/developers/files.md): Write, read, edit, and organize files, compare and revert versions, and handle Agent proposals.
- [Processing status](https://mirabase.io/developers/processing.md): A file becomes searchable first, and memories are built afterwards: wait for a single file, track a bulk import, and check whether content is still being processed.
- [Sync, snapshots, and export](https://mirabase.io/developers/sync.md): Mirror a Space with the tree, the change feed, and webhooks, pin a moment with snapshots, and move a whole Space with export and import.
- [Retrieval and context](https://mirabase.io/developers/retrieval.md): Use `search` when you choose the sources, `context` when the service chooses and budgets them, and `answer` when you want a cited answer.
- [Memory](https://mirabase.io/developers/memory.md): Write, distill, review, correct, and forget memories, and consolidate them offline.
- [Connect an Agent (MCP)](https://mirabase.io/developers/agents.md): Connect Agents such as Claude Code and Codex to Mirabase over MCP: how to connect, protocol versions, the tools and their parameters, and the recommended call order.
- [Framework integrations (Coming soon)](https://mirabase.io/developers/integrations.md): Use Mirabase's tools, memory, and retrieval from the Vercel AI SDK, LangChain, LlamaIndex, the OpenAI Agents SDK, Mastra, and CrewAI.
- [Branches and mounts](https://mirabase.io/developers/branches.md): Copy-on-write workspaces for Agents, FUSE mounts, a sync command, and Git workspaces.
- [Permissions](https://mirabase.io/developers/permissions.md): How principals, capabilities, Space roles, read and write roots, and API key limits together decide a request.
- [API conventions](https://mirabase.io/developers/conventions.md): The rules every endpoint shares: requests and responses, request ids, versions, pagination, idempotency, conditional requests, jobs, errors, retries, and rate limits.
- [Error codes](https://mirabase.io/developers/errors.md): Every error code an API key can receive, with its HTTP status, remediation.action, meaning, and Retry-After.
- [Skills](https://mirabase.io/developers/skills.md): Mirabase's official skills tell an Agent when to call which MCP tool, in what order, and what to ask the user first. Nine skills cover the API task by task, and two cover complete scenarios: project memory and a knowledge base with cited answers.
- [Build on Mirabase](https://mirabase.io/developers/build.md): What the SDKs, MCP, skills, skills stored in a Space, webhooks, and provider plugins are each for and how they combine; the core calls of an application; and how to write and check a skill of your own.
- [All guides in one file](https://mirabase.io/developers/llms-full.txt)

## API reference

- [API overview](https://mirabase.io/developers/api.md): Every Mirabase Developer API endpoint, generated from the OpenAPI document.
- [Identity](https://mirabase.io/developers/api/identity.md): Read the current identity
- [API keys](https://mirabase.io/developers/api/api-keys.md): List keys, Create a key, Read a key, Revoke a key, Rotate a key
- [Principals](https://mirabase.io/developers/api/principals.md): List principals, Create a principal, Read a principal, Update a principal's capabilities
- [Spaces](https://mirabase.io/developers/api/spaces.md): List Spaces, Create a Space, Read a Space, Get or create a Space by your own id, Update a Space, Delete a Space, List members, Set a member, Remove a member, Read a Space's processing progress
- [Files](https://mirabase.io/developers/api/files.md): Read a file, Read a file's headers, Write a file, Edit a file's text, Delete a file, Write and delete in a batch, Get a file's download URL, Diff versions by path, Read lineage by path, Revert by path, List versions by path
- [Tree](https://mirabase.io/developers/api/tree.md): List a directory, Run tree operations
- [Uploads](https://mirabase.io/developers/api/uploads.md): Start a large upload, Abort an upload, Complete an upload, Get part upload URLs
- [Changes](https://mirabase.io/developers/api/changes.md): See who changed what recently, Read the change feed
- [Proposals](https://mirabase.io/developers/api/proposals.md): Read a proposal, Approve a proposal, Diff a proposal, Reject a proposal, Withdraw a proposal, List proposals
- [Snapshots](https://mirabase.io/developers/api/snapshots.md): Read a snapshot, Delete a snapshot, List snapshots, Take a snapshot
- [Webhooks](https://mirabase.io/developers/api/webhooks.md): List webhooks, Create a webhook, Read a webhook, Update a webhook, Delete a webhook, List deliveries, Rotate a webhook secret
- [Export and import](https://mirabase.io/developers/api/transfers.md): Get an export's archive URL, Export a Space, Fork a Space, Import an archive
- [Ingest](https://mirabase.io/developers/api/ingest.md): Ingest a URL, text, or conversation
- [Entries](https://mirabase.io/developers/api/entries.md): List Entries, Read an Entry, Update an Entry, Move an Entry to the trash, Read an Entry's content, Get an Entry's download URL, List copies, Diff versions, Read lineage, Read processing status, Erase an Entry, Reprocess an Entry, Restore an Entry, Revert to an older version, List versions, Read a version, Update a version message, Empty the trash
- [Jobs](https://mirabase.io/developers/api/jobs.md): Read a job, Cancel a job
- [Retrieval](https://mirabase.io/developers/api/retrieval.md): Answer with citations, Build context, Send context feedback, Search
- [Memories](https://mirabase.io/developers/api/memories.md): List memories, Create a memory, Read a memory, Update a memory, Forget a memory, Correct a memory, Read a memory's provenance, Review a memory, Undo a memory write
- [Memory dreaming](https://mirabase.io/developers/api/memory-dreaming.md): Read a dream's report, List a dream's actions, List a dream's judgments, Undo a dream, Read a memory proposal, Approve a memory proposal, Reject a memory proposal, List dreams, Start a dream, List memory proposals, Read the consolidation setting, Change the consolidation setting
- [Branches](https://mirabase.io/developers/api/branches.md): List branches, Open a branch, Read a branch, Rename or renew a branch, Abandon a branch, List checkpoints, Create a checkpoint, Diff a branch, Merge a branch, Read a branch object, Check a branch object, Write a branch object, Roll back to a checkpoint
- [Usage](https://mirabase.io/developers/api/usage.md): Read limits, Read the processing queue, Read usage
- [Audit](https://mirabase.io/developers/api/audit.md): Read audit events
- [Request logs](https://mirabase.io/developers/api/request-logs.md): List request logs, Read a request log, Read a retrieval trace
- [Discovery](https://mirabase.io/developers/api/discovery.md): Read llms.txt, Read the OpenAPI document
- [MCP](https://mirabase.io/developers/api/mcp.md): MCP handshake, Call MCP
- [Schemas](https://mirabase.io/developers/api/schemas.md): Every data structure used by API requests and responses.
