# Spaces

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

API reference. Base URL: `https://api.mirabase.dev`

## 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](https://mirabase.io/developers/concepts.md#space)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |
| `external_id` | Query | `string` | Optional | Only the Space with this `external_id` (your own id for it): zero or one result. length 1..256 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevSpace[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/usage.md#usage-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](https://mirabase.io/developers/concepts.md#space)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | The Space's name, 1 to 512 characters. length 1..512 |
| `description` | `string` | Optional | What the Space is for, 1 to 4096 characters. length 1..4096 |
| `external_id` | `string` | Optional | 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=`](https://mirabase.io/developers/api/spaces.md#spaces-list) 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

- `201` `application/json` `DevSpace`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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](https://mirabase.io/developers/permissions.md#roots)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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

- `200` `application/json` `DevSpace`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/spaces.md#spaces-ensure); 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`](https://mirabase.io/developers/api/spaces.md#spaces-create). 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](https://mirabase.io/developers/concepts.md#space)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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 | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Optional | Name for a new Space. Defaults to the `external_id`. length 1..512 |
| `description` | `string` | Optional | Description for a new Space. length 1..4096 |

### Responses

- `200` `application/json` `DevSpace`
- `201` `application/json` `DevSpace`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Optional | A new name, 1 to 512 characters. length 1..512 |
| `description` | `string \| null` | Optional | A new description, or `null` to clear it. length 1..4096 |
| `external_id` | `string \| null` | Optional | 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

- `200` `application/json` `DevSpace`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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`](https://mirabase.io/developers/api/entries.md#entries-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](https://mirabase.io/developers/concepts.md#space)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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` | Optional | 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

- `200` `application/json` `DevSpaceDeletion`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevSpaceMember[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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](https://mirabase.io/developers/permissions.md#roles)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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 | Required | Description |
| --- | --- | --- | --- |
| `role` | `editor \| viewer` | Required | `editor` can write; `viewer` can only read. Ownership cannot be granted here. |
| `write_mode` | `DevWriteMode` | Optional | Defaults to `proposal` for a new member; otherwise the current value stays. |
| `write_root` | `string \| null` | Optional | 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` | Optional | 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

- `200` `application/json` `DevSpaceMember`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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_id` | Path | `DevId` | Required | Opaque 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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](https://mirabase.io/developers/processing.md#bulk)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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

- `200` `application/json` `DevSpaceProcessing`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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"
}
```
