# Snapshots

Read-only, point-in-time views of a whole Space.

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

## Read a snapshot

`GET /v2/snapshots/{snapshot_id}`

Read one snapshot's record. To read the files it holds, pass `snapshot=<id>` to `tree`, `files`, and `files/content-url`. Needs `knowledge:read`.

**Capability** `knowledge:read`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `snapshot_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

- `200` `application/json` `DevSnapshot`

### 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/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "file_count": 1,
  "changes_cursor": "<cursor>",
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z"
}
```

## Delete a snapshot

`DELETE /v2/snapshots/{snapshot_id}`

Delete a snapshot. Only its creator or the Space owner can, with `knowledge:write`. The versions it pinned stay. A second delete returns 404 `snapshot_not_found`.

**Capability** `knowledge:write`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `snapshot_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/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

## List snapshots

`GET /v2/spaces/{space_id}/snapshots`

List the snapshots of a Space, newest first. Needs `knowledge:read`.

**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` | `DevSnapshot[]` | 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/snapshots" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "name": "research",
      "file_count": 1,
      "changes_cursor": "<cursor>",
      "created_by_principal_id": "<created_by_principal_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```

## Take a snapshot

`POST /v2/spaces/{space_id}/snapshots`

Take a snapshot of the whole Space. Needs `knowledge:write` and editor; an Agent's `write_mode` does not apply, since nothing changes. Counts one write and no bytes. A Space holds at most 100 snapshots (409 `too_many_snapshots`) and a snapshot at most 10,000 files (409 `snapshot_too_large`, nothing is kept); a name in use returns 409 `snapshot_name_taken`. A busy Space returns 409 `space_busy`.

**Capability** `knowledge:write`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#snapshots)

### 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` `DevCreateSnapshotRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required | 1 to 255 bytes, unique in the Space, no control characters, not starting with `snp_`. length 1..255 |

### Responses

- `201` `application/json` `DevSnapshot`

### 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/$SPACE_ID/snapshots" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research"}'
```

### Example response

```json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "name": "research",
  "file_count": 1,
  "changes_cursor": "<cursor>",
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z"
}
```
