Spaces
MarkdownSpaces, 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
| Name | In | Type | Description |
|---|---|---|---|
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
external_id | Query | string | Only the Space with this external_id (your own id for it): zero or one result.length 1..256 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevSpace[] | The items on this page. |
next_cursor | DevCursor | Pass 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 "https://api.mirabase.dev/v2/spaces" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | Header | DevIdempotencyKey | The 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
| Field | Type | Description |
|---|---|---|
nameRequired | string | The Space's name, 1 to 512 characters.length 1..512 |
description | string | What the Space is for, 1 to 4096 characters.length 1..4096 |
external_id | string | Your 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
201application/jsonDevSpace
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 -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
{
"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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A 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
200application/jsonDevSpace
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 "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | Must 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.
| Field | Type | Description |
|---|---|---|
name | string | Name for a new Space. Defaults to the external_id.length 1..512 |
description | string | Description 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 -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
{
"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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A 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-Key | Header | DevIdempotencyKey | The 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.
| Field | Type | Description |
|---|---|---|
name | string | A new name, 1 to 512 characters.length 1..512 |
description | string | null | A new description, or null to clear it.length 1..4096 |
external_id | string | null | A 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
200application/jsonDevSpace
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 -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Example response
{
"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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A 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-Key | Header | DevIdempotencyKey | The 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
200application/jsonDevSpaceDeletion
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 -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A 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 |
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevSpaceMember[] | The items on this page. |
next_cursor | DevCursor | Pass 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 "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A 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_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | The 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
| Field | Type | Description |
|---|---|---|
roleRequired | editor | viewer | editor can write; viewer can only read. Ownership cannot be granted here. |
write_mode | DevWriteMode | Defaults to proposal for a new member; otherwise the current value stays. |
write_root | string | null | Limit 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_root | string | null | Limit 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
200application/jsonDevSpaceMember
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 -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
{
"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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A 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_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
204No 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 -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
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A 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
200application/jsonDevSpaceProcessing
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 "https://api.mirabase.dev/v2/spaces/$SPACE_ID/processing" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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"
}