Skip to content
Developer docs
Docs menu

Spaces

Markdown

Spaces, which keep one end user's or project's data apart, and their members.

List Spaces

GET/v2/spaces

Spaces the caller can see, ordered by id, descending. Needs knowledge:read. Each Space includes the caller's own write_root and read_root when they are set. With external_id the page holds the one Space with that id, or nothing when there is none or the caller cannot see it.

Capability knowledge:read

Guide: Core concepts

Parameters

NameInTypeDescription
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20
external_idQuerystringOnly the Space with this external_id (your own id for it): zero or one result.length 1..256

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevSpace[]The items on this page.
next_cursorDevCursorPass it as cursor to get the next page. Absent on the last page.

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

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

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "name": "research",
      "is_default": false,
      "access_role": "owner",
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}

Create a Space

POST/v2/spaces

Create a Space. An account holds at most tenant_spaces Spaces (GET /v2/limits); exceeding the limit returns 409 tenant_limit_reached, and deleting a Space frees its slot. Use one Space per end user or per project to keep their data apart. Needs knowledge:manage.

Capability knowledge:manage

Guide: Core concepts

Parameters

NameInTypeDescription
Idempotency-KeyHeaderDevIdempotencyKeyThe same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512

Request body

application/json DevCreateSpaceRequest

FieldTypeDescription
nameRequiredstringThe Space's name, 1 to 512 characters.length 1..512
descriptionstringWhat the Space is for, 1 to 4096 characters.length 1..4096
external_idstringYour own id for this Space, 1 to 256 characters, such as the id of the end user whose data it keeps. Find the Space later with GET /v2/spaces?external_id= or the path ext:<external_id> instead of storing its Mirabase id. It is unique among the account's Spaces: one already in use returns 409 space_external_id_taken (field: external_id). Deleting the Space frees it.length 1..256

Responses

Error statuses

400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl -X POST "https://api.mirabase.dev/v2/spaces" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","external_id":"user-42"}'

Example response

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

Read a Space

GET/v2/spaces/{space_id}

Read one Space. Returns 404 not_found if the Space does not exist or the caller cannot see it. Needs knowledge:read.

Capability knowledge:read

Guide: Permissions

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256

Responses

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

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

Example response

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

Get or create a Space by your own id

PUT/v2/spaces/{space_id}

Return the Space that carries your own id for it, creating it when there is none. The path must be ext:<external_id>, such as PUT /v2/spaces/ext:user-42; any other value returns 422. One call before the first write for a new end user is enough: there is no need to create, catch 409, and look up. When a Space you can see has that external_id, returns 200 with the Space and ignores the request body; this requires knowledge:read. When none has it, creates the Space and returns 201; this requires knowledge:manage and counts toward tenant_spaces, like POST /v2/spaces. Two concurrent calls create one Space and both receive it. If a Space you cannot see holds the id, returns 409 space_external_id_taken. The body is optional. Sending the request again is safe.

Capability Depends on the request, as the description above says.

Guide: Core concepts

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefMust be ext:<external_id>, such as ext:user-42; any other value returns 422 validation_error.length 1..256

Request body

application/json DevEnsureSpaceRequest Used only when the Space is created; an existing Space is returned as it is.

FieldTypeDescription
namestringName for a new Space. Defaults to the external_id.length 1..512
descriptionstringDescription for a new Space.length 1..4096

Responses

Error statuses

400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
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":"Ada Lovelace"}'

Example response

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

Update a Space

PATCH/v2/spaces/{space_id}

Change a Space's name, description, or external_id; send at least one, and pass null to clear description or external_id. An external_id already in use returns 409 space_external_id_taken. Needs knowledge:manage. The change is written to the audit log.

Capability knowledge:manage

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512

Request body

application/json DevUpdateSpaceRequest At least one field is required. null clears the description or the external_id.

FieldTypeDescription
namestringA new name, 1 to 512 characters.length 1..512
descriptionstring | nullA new description, or null to clear it.length 1..4096
external_idstring | nullA new external_id, 1 to 256 characters, or null to clear it. A value already in use returns 409 space_external_id_taken.length 1..256

Responses

Error statuses

400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

Delete a Space

DELETE/v2/spaces/{space_id}

Delete a Space and everything in it: files with all their versions, ingested Entries, memories, branches, snapshots, webhooks, and memberships. It cannot be undone. Only the Space owner can, with knowledge:manage. The Space is removed immediately: it disappears from every read, stops counting toward tenant_spaces, and its storage is deducted from the account's total. The content itself is erased in the background, each Entry in the same way as POST /v2/entries/{id}/purge; entries reports how many Entries were in the Space. Deleting the default Space returns 409 default_space_protected. While a job (a tree job, an export, an import, or a merge) is queued or running in the Space, the request returns 409 job_in_flight with its job_id; wait for the job to finish. With Idempotency-Key, repeating the request returns the first response; without it, a second delete returns 404 not_found.

Capability knowledge:manage

Guide: Core concepts

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512

Responses

Error statuses

400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "space_id": "<space_id>",
  "deleted": true,
  "entries": 1
}

List members

GET/v2/spaces/{space_id}/members

Members of a Space with their role, write_mode, write_root, and read_root, ordered by principal id. Needs knowledge:read and a Space the caller can see. A caller limited to a read_root does not see other members' roots that lie outside it.

Capability knowledge:read

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevSpaceMember[]The items on this page.
next_cursorDevCursorPass it as cursor to get the next page. Absent on the last page.

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "principal_id": "<principal_id>",
      "role": "owner",
      "write_mode": "proposal"
    }
  ]
}

Set a member

PUT/v2/spaces/{space_id}/members/{principal_id}

Grant a Space role, write mode, write root, and read root. Only the Space owner can set members; changing the owner's own membership returns 409 owner_membership_immutable. Needs knowledge:manage.

Capability knowledge:manage

Guide: Permissions

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256
principal_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512

Request body

application/json DevSetSpaceMemberRequest

FieldTypeDescription
roleRequirededitor | viewereditor can write; viewer can only read. Ownership cannot be granted here.
write_modeDevWriteModeDefaults to proposal for a new member; otherwise the current value stays.
write_rootstring | nullLimit this member's writes to the subtree under an existing directory. It only narrows: role, capabilities, and API key bounds still apply, reads are unchanged, and the directory itself cannot be renamed, moved, or deleted by the member. Absent keeps the current value; null or / removes the limit. A missing directory returns 404 not_found and a file returns 409 not_a_directory, both with field: write_root. Writes outside it return 403 outside_write_root, as do writes to Entries without a path, except the member's own Agent memory.length 1..8192
read_rootstring | nullLimit what this member can read to an existing directory and everything under it. It only narrows: role, capabilities, and API key bounds still apply. Absent keeps the current value; null or / removes the limit. A missing directory returns 404 not_found and a file returns 409 not_a_directory, both with field: read_root. Outside it, reads return 404 as if nothing were there, Entries without a path are outside it except the member's own Agent memory, and branches in this Space return 403 outside_read_root. Without a write_root the member writes under its read_root; a write_root must be the read_root or below it, or the request returns 422 write_root_outside_read_root (field: write_root), including when a new read_root leaves the current write_root outside.length 1..8192

Responses

Error statuses

400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"editor"}'

Example response

json
{
  "principal_id": "<principal_id>",
  "role": "owner",
  "write_mode": "proposal"
}

Remove a member

DELETE/v2/spaces/{space_id}/members/{principal_id}

Remove a member. Only the Space owner can remove a member. Removing a principal who is not a member returns 404 not_found. The owner's own membership cannot be removed: that returns 409 owner_membership_immutable. Needs knowledge:manage.

Capability knowledge:manage

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256
principal_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

  • 204 No response body

Error statuses

400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Read a Space's processing progress

GET/v2/spaces/{space_id}/processing

Processing progress of a Space: how many Entries are queued, being processed, searchable, ready and failed, the rate at which they become searchable, and an estimate of when the rest will be. Poll this during a bulk import instead of reading every Entry. Counts only Entries the caller can see. Needs knowledge:read.

Capability knowledge:read

Guide: Processing status

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256

Responses

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "space_id": "col_01JD2M7QK3",
  "counts": {
    "queued": 48,
    "processing": 4,
    "searchable": 60,
    "ready": 8,
    "failed": 0
  },
  "stages": {
    "queued": 48,
    "extracting": 1,
    "indexing": 3,
    "enriching": 60
  },
  "searchable_per_minute": 42.5,
  "eta_seconds": 74,
  "oldest_queued_seconds": 21,
  "waiting_for_capacity": true,
  "queue_position": 0,
  "memory": {
    "pending": 60,
    "eta_seconds": 90,
    "files": "index_only"
  },
  "as_of": "2026-11-17T08:00:00Z"
}