# API reference

This reference is generated from the OpenAPI document. Endpoints marked Coming soon do not exist yet, are not a stable contract, and may change before launch. Endpoints marked Deployment option are optional: where a deployment does not enable them, they return 404.

- Base URL: `https://api.mirabase.dev`
- OpenAPI: https://api.mirabase.dev/v2/openapi.yaml
- Spec version: `2.0.0` (33c172f77f2c)
- Status: 115 implemented by default, 12 implemented as a deployment option, 3 coming soon

## Common headers

Every endpoint accepts the headers below. Authenticated responses carry `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`: see [Rate limits and quotas](https://mirabase.io/developers/conventions.md#rate-limits). The rules for pagination, idempotency, conditional requests, jobs, and errors are in [API conventions](https://mirabase.io/developers/conventions.md), and every error code is listed in [Error codes](https://mirabase.io/developers/errors.md).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Mirabase-Contract-Version` | `string` | Optional | Explicit contract version to negotiate. Omit to use the current compatible contract. |
| `X-Request-Id` | `string` | Optional | Caller correlation id. The service replaces an invalid value with one it issues. |

## Endpoint groups

### [Identity](https://mirabase.io/developers/api/identity.md)

- `GET /v2/whoami` Read the current identity

### [API keys](https://mirabase.io/developers/api/api-keys.md)

- `GET /v2/api-keys` List keys
- `POST /v2/api-keys` Create a key
- `GET /v2/api-keys/{key_id}` Read a key
- `DELETE /v2/api-keys/{key_id}` Revoke a key
- `POST /v2/api-keys/{key_id}/rotate` Rotate a key

### [Principals](https://mirabase.io/developers/api/principals.md)

- `GET /v2/principals` List principals
- `POST /v2/principals` Create a principal
- `GET /v2/principals/{principal_id}` Read a principal
- `PATCH /v2/principals/{principal_id}` Update a principal's capabilities

### [Spaces](https://mirabase.io/developers/api/spaces.md)

- `GET /v2/spaces` List Spaces
- `POST /v2/spaces` Create a Space
- `GET /v2/spaces/{space_id}` Read a Space
- `PUT /v2/spaces/{space_id}` Get or create a Space by your own id
- `PATCH /v2/spaces/{space_id}` Update a Space
- `DELETE /v2/spaces/{space_id}` Delete a Space
- `GET /v2/spaces/{space_id}/members` List members
- `PUT /v2/spaces/{space_id}/members/{principal_id}` Set a member
- `DELETE /v2/spaces/{space_id}/members/{principal_id}` Remove a member
- `GET /v2/spaces/{space_id}/processing` Read a Space's processing progress

### [Files](https://mirabase.io/developers/api/files.md)

- `GET /v2/spaces/{space_id}/files` Read a file
- `HEAD /v2/spaces/{space_id}/files` Read a file's headers
- `PUT /v2/spaces/{space_id}/files` Write a file
- `PATCH /v2/spaces/{space_id}/files` Edit a file's text
- `DELETE /v2/spaces/{space_id}/files` Delete a file
- `POST /v2/spaces/{space_id}/files/batch` Write and delete in a batch
- `GET /v2/spaces/{space_id}/files/content-url` Get a file's download URL
- `GET /v2/spaces/{space_id}/files/diff` Diff versions by path
- `GET /v2/spaces/{space_id}/files/lineage` Read lineage by path
- `POST /v2/spaces/{space_id}/files/revert` Revert by path
- `GET /v2/spaces/{space_id}/files/versions` List versions by path

### [Tree](https://mirabase.io/developers/api/tree.md)

- `GET /v2/spaces/{space_id}/tree` List a directory
- `POST /v2/spaces/{space_id}/tree/operations` Run tree operations

### [Uploads](https://mirabase.io/developers/api/uploads.md)

- `POST /v2/spaces/{space_id}/uploads` Start a large upload
- `POST /v2/uploads/{upload_id}/abort` Abort an upload
- `POST /v2/uploads/{upload_id}/complete` Complete an upload
- `POST /v2/uploads/{upload_id}/parts` Get part upload URLs

### [Changes](https://mirabase.io/developers/api/changes.md)

- `GET /v2/spaces/{space_id}/activity` See who changed what recently
- `GET /v2/spaces/{space_id}/changes` Read the change feed

### [Proposals](https://mirabase.io/developers/api/proposals.md)

- `GET /v2/proposals/{proposal_id}` Read a proposal
- `POST /v2/proposals/{proposal_id}/approve` Approve a proposal
- `GET /v2/proposals/{proposal_id}/diff` Diff a proposal
- `POST /v2/proposals/{proposal_id}/reject` Reject a proposal
- `POST /v2/proposals/{proposal_id}/withdraw` Withdraw a proposal
- `GET /v2/spaces/{space_id}/proposals` List proposals

### [Snapshots](https://mirabase.io/developers/api/snapshots.md)

- `GET /v2/snapshots/{snapshot_id}` Read a snapshot
- `DELETE /v2/snapshots/{snapshot_id}` Delete a snapshot
- `GET /v2/spaces/{space_id}/snapshots` List snapshots
- `POST /v2/spaces/{space_id}/snapshots` Take a snapshot

### [Webhooks](https://mirabase.io/developers/api/webhooks.md)

- `GET /v2/spaces/{space_id}/webhooks` List webhooks
- `POST /v2/spaces/{space_id}/webhooks` Create a webhook
- `GET /v2/webhooks/{webhook_id}` Read a webhook
- `PATCH /v2/webhooks/{webhook_id}` Update a webhook
- `DELETE /v2/webhooks/{webhook_id}` Delete a webhook
- `GET /v2/webhooks/{webhook_id}/deliveries` List deliveries
- `POST /v2/webhooks/{webhook_id}/rotate-secret` Rotate a webhook secret

### [Export and import](https://mirabase.io/developers/api/transfers.md)

- `GET /v2/jobs/{job_id}/content-url` Get an export's archive URL
- `POST /v2/spaces/{space_id}/exports` Export a Space
- `POST /v2/spaces/{space_id}/forks` Fork a Space (Coming soon)
- `POST /v2/spaces/{space_id}/imports` Import an archive

### [Ingest](https://mirabase.io/developers/api/ingest.md)

- `POST /v2/spaces/{space_id}/ingest` Ingest a URL, text, or conversation

### [Entries](https://mirabase.io/developers/api/entries.md)

- `GET /v2/entries` List Entries
- `GET /v2/entries/{entry_id}` Read an Entry
- `PATCH /v2/entries/{entry_id}` Update an Entry
- `DELETE /v2/entries/{entry_id}` Move an Entry to the trash
- `GET /v2/entries/{entry_id}/content` Read an Entry's content
- `GET /v2/entries/{entry_id}/content-url` Get an Entry's download URL
- `GET /v2/entries/{entry_id}/copies` List copies (Coming soon)
- `GET /v2/entries/{entry_id}/diff` Diff versions
- `GET /v2/entries/{entry_id}/lineage` Read lineage
- `GET /v2/entries/{entry_id}/processing` Read processing status
- `POST /v2/entries/{entry_id}/purge` Erase an Entry
- `POST /v2/entries/{entry_id}/reprocess` Reprocess an Entry
- `POST /v2/entries/{entry_id}/restore` Restore an Entry
- `POST /v2/entries/{entry_id}/revert` Revert to an older version
- `GET /v2/entries/{entry_id}/versions` List versions
- `GET /v2/entries/{entry_id}/versions/{version_id}` Read a version
- `PATCH /v2/entries/{entry_id}/versions/{version_id}/message` Update a version message
- `POST /v2/spaces/{space_id}/trash/purge` Empty the trash

### [Jobs](https://mirabase.io/developers/api/jobs.md)

- `GET /v2/jobs/{job_id}` Read a job
- `POST /v2/jobs/{job_id}/cancel` Cancel a job (Coming soon)

### [Retrieval](https://mirabase.io/developers/api/retrieval.md)

- `POST /v2/retrieval/answer` Answer with citations
- `POST /v2/retrieval/context` Build context
- `POST /v2/retrieval/context/{pack_id}/feedback` Send context feedback
- `POST /v2/retrieval/search` Search

### [Memories](https://mirabase.io/developers/api/memories.md)

- `GET /v2/memories` List memories
- `POST /v2/memories` Create a memory
- `GET /v2/memories/{memory_id}` Read a memory
- `PATCH /v2/memories/{memory_id}` Update a memory
- `DELETE /v2/memories/{memory_id}` Forget a memory
- `POST /v2/memories/{memory_id}/correct` Correct a memory
- `GET /v2/memories/{memory_id}/provenance` Read a memory's provenance
- `POST /v2/memories/{memory_id}/review` Review a memory
- `POST /v2/memories/{memory_id}/undo` Undo a memory write

### [Memory dreaming](https://mirabase.io/developers/api/memory-dreaming.md)

- `GET /v2/memory/dreams/{dream_id}` Read a dream's report (Deployment option)
- `GET /v2/memory/dreams/{dream_id}/actions` List a dream's actions (Deployment option)
- `GET /v2/memory/dreams/{dream_id}/judgments` List a dream's judgments (Deployment option)
- `POST /v2/memory/dreams/{dream_id}/undo` Undo a dream (Deployment option)
- `GET /v2/memory/proposals/{proposal_id}` Read a memory proposal (Deployment option)
- `POST /v2/memory/proposals/{proposal_id}/approve` Approve a memory proposal (Deployment option)
- `POST /v2/memory/proposals/{proposal_id}/reject` Reject a memory proposal (Deployment option)
- `GET /v2/spaces/{space_id}/memory/dreams` List dreams (Deployment option)
- `POST /v2/spaces/{space_id}/memory/dreams` Start a dream (Deployment option)
- `GET /v2/spaces/{space_id}/memory/proposals` List memory proposals (Deployment option)
- `GET /v2/spaces/{space_id}/memory/settings` Read the consolidation setting (Deployment option)
- `PATCH /v2/spaces/{space_id}/memory/settings` Change the consolidation setting (Deployment option)

### [Branches](https://mirabase.io/developers/api/branches.md)

- `GET /v2/spaces/{space_id}/branches` List branches
- `POST /v2/spaces/{space_id}/branches` Open a branch
- `GET /v2/spaces/{space_id}/branches/{branch_id}` Read a branch
- `PATCH /v2/spaces/{space_id}/branches/{branch_id}` Rename or renew a branch
- `DELETE /v2/spaces/{space_id}/branches/{branch_id}` Abandon a branch
- `GET /v2/spaces/{space_id}/branches/{branch_id}/checkpoints` List checkpoints
- `POST /v2/spaces/{space_id}/branches/{branch_id}/checkpoints` Create a checkpoint
- `GET /v2/spaces/{space_id}/branches/{branch_id}/diff` Diff a branch
- `POST /v2/spaces/{space_id}/branches/{branch_id}/merge` Merge a branch
- `GET /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}` Read a branch object
- `HEAD /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}` Check a branch object
- `PUT /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}` Write a branch object
- `POST /v2/spaces/{space_id}/branches/{branch_id}/rollback` Roll back to a checkpoint

### [Usage](https://mirabase.io/developers/api/usage.md)

- `GET /v2/limits` Read limits
- `GET /v2/queue` Read the processing queue
- `GET /v2/usage` Read usage

### [Audit](https://mirabase.io/developers/api/audit.md)

- `GET /v2/audit/events` Read audit events

### [Request logs](https://mirabase.io/developers/api/request-logs.md)

- `GET /v2/request-logs` List request logs
- `GET /v2/request-logs/{log_id}` Read a request log
- `GET /v2/retrieval/traces/{trace_id}` Read a retrieval trace

### [Discovery](https://mirabase.io/developers/api/discovery.md)

- `GET /llms.txt` Read llms.txt
- `GET /v2/openapi.yaml` Read the OpenAPI document

### [MCP](https://mirabase.io/developers/api/mcp.md)

- `GET /mcp` MCP handshake
- `POST /mcp` Call MCP

### [Schemas](https://mirabase.io/developers/api/schemas.md)

Every data structure used by API requests and responses.
