Skip to content
Developer docs
Docs menu

Core concepts

Markdown

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

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

curl
# 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, and answer without space_ids read 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 by external_id, returns at most one, and never creates one (spaces.findByExternalId and spaces.find_by_external_id in the SDKs).
  • Deleting a Space frees its external_id for 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_id is the newest committed version. Reads use it by default, so you can read what you just wrote.
  • current_version_id is the version search and context read from. It equals latest_version_id once 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:

StateMeaningWhat works
readableCommittedRead the original by path or id
searchableText up to 64 KiB from the request body is in the freshness bufferLexical search
indexedProcessing finishedFull-text, vector, and reranked search
failedProcessing failed; the bytes remain readableRead 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