Core concepts
MarkdownThe data model behind the API: Spaces, Entries and versions, files, knowledge, memory, branches, and access control.
The source layer in Mirabase has one kind of data: an Entry with immutable versions. A file is how you locate an Entry, knowledge is what processing produces from it, and part of memory comes from it.
Entry
├─ id, space_id, title, metadata
├─ latest_version_id newest committed version
├─ current_version_id version serving search
├─ file { path, size, media_type, etag } or null
├─ knowledge { state, indexed_version_id }
├─ memory { scope, kind, pinned, exclude } or null
├─ memory_exclude kept out of memory distillation
└─ access { role, capabilities }Space
A Space is the boundary for permissions and paths. Every account has a default Space, and POST /v2/spaces creates more. Members, roles, and the file tree are all per Space.
An account can hold many Spaces (up to tenant_spaces, see Rate limits and quotas), so you can give each end user or each project its own. Deleting a Space deletes everything in it and cannot be undone, and the default Space cannot be deleted: see DELETE /v2/spaces/{space_id}.
One Space per end user
When end users must be kept strictly apart, give each one a Space: files, knowledge, and memory are all kept per Space, which metadata cannot do. Set your own user id as the Space's external_id, then write ext:<external_id>, such as ext:user-42, wherever a Space id goes: in a path, in ?space_id=, and in space_ids in a request body. There is no mapping table to keep.
PUT /v2/spaces/ext:<external_id> returns the Space or creates it. Two requests that arrive together create one Space, and calling it again is safe, so one call before the first write for a new user is enough. In the SDKs this is spaces.ensure, and spaceFor (space_for in Python) also returns a client pinned to that Space.
# Returns the Space whose external_id is user-42 (200), or creates it (201).
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "User 42"}'
# ext:user-42 works wherever a Space id does.
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42/files?path=/notes/plan.md" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: text/markdown" \
--data-binary "We ship on Friday."search,context, andanswerwithoutspace_idsread every Space the key can read, not only the default Space. When a request is about one user, name that user's Space. In the SDKs, a client pinned to a Space reads that Space only.GET /v2/spaces?external_id=looks a Space up byexternal_id, returns at most one, and never creates one (spaces.findByExternalIdandspaces.find_by_external_idin the SDKs).- Deleting a Space frees its
external_idfor reuse.
Entries and versions
An Entry is the stable identity of a source: a file, a URL, or a piece of text. Each change of content makes a version. Versions are immutable, and the service keeps the chain.
latest_version_idis the newest committed version. Reads use it by default, so you can read what you just wrote.current_version_idis the versionsearchandcontextread from. It equalslatest_version_idonce that version is indexed, and stays on the earlier version while a newer one is still processing. It is absent until the first version finishes processing.- A new title is also a new version, because the title is indexed. The only thing you can change on a version is its
message.
You can reach an Entry by path, by id, or by meaning through search. All these access methods share the same identity, permissions, and version chain.
Files
An Entry with a path is a file. The path is the identity: the same bytes at two paths are two files. Renames and moves keep the Entry id. An Entry can also have no path, such as a URL or text added through ingest: its file is null.
Use `files` when you have a path and `entries` when you have an id. Both take the same read parameters. See Files and versions.
Knowledge
Knowledge is not a separate resource. It is the processing state of an Entry. After a write commits, the service parses, chunks, and indexes it, and knowledge.state reports progress:
| State | Meaning | What works |
|---|---|---|
readable | Committed | Read the original by path or id |
searchable | Text up to 64 KiB from the request body is in the freshness buffer | Lexical search |
indexed | Processing finished | Full-text, vector, and reranked search |
failed | Processing failed; the bytes remain readable | Read the original, or call reprocess |
A write is committed before processing finishes. To wait for processing, send Prefer: wait=N on the write; see PUT /v2/spaces/{space_id}/files.
Memory
A memory is a statement with a scope, a status, and a source: an account memory, a memory written as an Entry, or a fact distilled from an Entry. A distilled fact is not an Entry, and its id is not an Entry id. For scopes, statuses, and validity, see The memory model.
Branches
A branch is a copy-on-write layer over a Space's main line, used as an Agent's workspace. Content on it creates no versions and is not processed. Each path becomes a new version only when merged into main. See Branches and mounts.
Access control
Every request acts as a principal, a person or an Agent, carried by an API key. What a request may do depends on the capabilities the principal and the key both hold, the principal's role in the Space, and the read and write roots the Space owner set for the member. See Permissions.
Next steps
- Files and versions: start by writing a file.
- Retrieval and context: search, context, and answers with citations.
- Memory: distill facts from conversations, then review, correct, and forget them.
