Skip to content
Developer docs
Docs menu

Entries

Markdown

Entries reached by id: content, versions, processing, the trash, and erasure.

List Entries

GET/v2/entries

Entries visible to the caller, optionally narrowed to one Space (space_id, which also takes default or ext:<external_id>). Memories and Agent profiles are not listed here. Ordered by id, descending; the order is stable while you page. trashed=true lists the trash instead: Entries that were deleted and can still be restored, each with trash (when it was trashed, and the path a file had). q and state narrow either list. A purged Entry is in neither list. A member with a read_root sees no trashed Entries. Needs knowledge:read.

Capability knowledge:read

Guide: Files and versions

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
space_idQueryDevSpaceRefKeep the Entries of this Space. Accepts a Space id, default, or ext:<external_id>, as in a path.length 1..256
trashedQuerybooleantrue lists the trash instead of the live Entries.
metadataQuerystringKeep the Entries whose metadata has these values: a JSON object, URL-encoded, such as {"status":"final"}. Every key must match exactly; 1 to 8 keys. For a key that holds a list, the value must be one of them.
qQuerystringKeep the Entries whose title or file path contains this, ignoring case: 1 to 200 characters, a literal match for browsing, not retrieval. To find Entries by meaning, call search.length 1..200
stateQueryDevKnowledgeStateKeep the Entries whose knowledge.state is this, such as failed to list what processing gave up on.

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevEntry[]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/entries" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "title": "Launch notes",
      "latest_version_id": "<latest_version_id>",
      "metadata": {},
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z",
      "file": {
        "path": "/notes/hello.md",
        "size": 1,
        "media_type": "<media_type>",
        "etag": "<etag>"
      },
      "knowledge": {
        "state": "readable"
      },
      "memory": {
        "scope": "project",
        "kind": "<kind>",
        "pinned": false,
        "exclude": false
      },
      "memory_exclude": false,
      "access": {
        "role": "owner",
        "capabilities": [
          "knowledge:read"
        ]
      }
    }
  ]
}

Read an Entry

GET/v2/entries/{entry_id}

Read one Entry: its file (path, size, media type, and ETag) when it has a path, latest_version_id, metadata, and occurred_at. Needs knowledge:read. Returns 404 not_found if the Entry does not exist or the caller cannot see it.

Capability knowledge:read

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.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/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

Update an Entry

PATCH/v2/entries/{entry_id}

Change an Entry's title, metadata, metadata_patch, memory_exclude, or occurred_at; send at least one. A new title writes a new version; the others do not. A file's title is its name: rename or move it with tree/operations. Needs knowledge:write.

Capability knowledge:write

Guide: Files and versions

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Request body

application/json DevUpdateEntryRequest A new title is a new version: the title is part of what gets indexed, and versions do not change. The same title does nothing. A file's title is its name, so title on a file returns 422: rename it with tree/operations. Send at least one field.

FieldTypeDescription
titlestringA new title, 1 to 512 characters. Not supported on a file: rename it with tree/operations.length 1..512
metadataDevMetadataReplaces the Entry's metadata as a whole: send every key you want to keep, or {} to clear it. It does not create a version. Works on any Entry, a file included. Filters see the change once the Entry is reindexed, usually within seconds.
metadata_patchobjectChanges metadata key by key instead of replacing it: a key with a value is set, a key with null is removed, and the keys you do not mention stay. Two callers changing different keys do not overwrite each other. Not together with metadata. The result still holds at most 32 values.
memory_excludebooleantrue retires the facts distilled from this Entry and stops distilling it; search and reading are unaffected. false distills it again, without restoring facts you previously forgot or corrected.
occurred_atstring (date-time) | nullWhen the source itself happened. null clears it, and retrieval's time filter goes back to when the Entry was written. It does not make a version; filters see the change once the Entry is reindexed, usually within seconds. Memories already distilled keep the time they were given.

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/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

Move an Entry to the trash

DELETE/v2/entries/{entry_id}

Move an Entry to the trash. Requires knowledge:write and at least the editor role, the same as DELETE files; if the Entry is a file, its path moves to the trash with it. restore brings it back. A second delete returns 404 not_found.

Capability knowledge:write

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
If-MatchHeaderstringOne ETag (the version id in quotes): returns 412 unless it matches the latest version. Or *: returns 412 unless the file or Entry exists. Omit for last-write-wins.

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/entries/$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "entry_id": "<entry_id>",
  "deleted": true
}

Read an Entry's content

GET/v2/entries/{entry_id}/content

The same views as GET files, by id: view=raw (default) returns bytes, meta returns the Entry, and the rest return a content view. An Entry ingested from a URL has no raw bytes: view=raw returns 422 view_not_available; read view=text instead. With view=raw, Range, If-Range, and If-None-Match work as on GET files. Needs knowledge:read.

Capability knowledge:read

Guide: Files and versions

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
viewQueryDevFileViewWhich form of the content to return: raw (the default) for its bytes, meta for the Entry, or text, table, or recognized for a processed view.
versionQueryDevIdThe id of a version of this Entry to read instead of the latest. Not supported with view=meta (returns 422).length 1..256
RangeHeaderstringOne range: bytes=0-99, bytes=100-, or bytes=-100. Applies to view=raw only; other views ignore it.
If-RangeHeaderstringAn ETag. If the content has changed, returns the full new content (200) instead of a range (206).
If-None-MatchHeaderstringAn ETag you already hold. With view=raw, returns 304 with no body if the bytes have not changed.

Responses

Response headers

  • ETag
  • Mirabase-Entry-Id
  • Mirabase-Version-Id
  • Mirabase-Knowledge-State
  • Last-Modified When the content last changed, as an HTTP date. Only when the latest version is served.
  • Content-Range
  • Accept-Ranges

Error statuses

400 401 403 404 416 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/entries/$ENTRY_ID/content" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

Get an Entry's download URL

GET/v2/entries/{entry_id}/content-url

A signed URL for the original bytes of version (default: the latest), valid for expires_in seconds (60 to 300, default 300). Same checks as view=raw; an Entry ingested from a URL returns 422 view_not_available. The access is audited before the URL is signed. An original kept on the server instead of in object storage returns 409 content_url_unavailable; read view=raw instead. 503 original_unavailable means the URL could not be signed right now: retry later. Needs knowledge:read.

Capability knowledge:read

Guide: Files and versions

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
versionQueryDevIdThe id of the version to sign a URL for. Defaults to the latest.length 1..256
expires_inQueryintegerHow long the URL stays valid, in seconds: 60 to 300, 300 by default.60..300, default: 300

Responses

Error statuses

400 401 403 404 409 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/entries/$ENTRY_ID/content-url" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "url": "https://example.com/article",
  "method": "GET",
  "expires_at": "2026-11-06T00:00:00Z",
  "entry_id": "<entry_id>",
  "version_id": "<version_id>",
  "size_bytes": 1,
  "media_type": "<media_type>"
}

List copiesComing soon

GET/v2/entries/{entry_id}/copies

This is not live yet. Endpoints and fields may change.

Planned: the Entries copied from this one that you can see, newest first.

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.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
dataRequiredDevEntryCopy[]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/entries/$ENTRY_ID/copies" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "entry_id": "<entry_id>",
      "source_version_id": "<source_version_id>",
      "space_id": "<space_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

Diff versions

GET/v2/entries/{entry_id}/diff

Compare two versions of this Entry. to defaults to the latest. Returns 404 not_found if the version does not exist or you cannot see it. Needs knowledge:read.

Capability knowledge:read

Guide: Files and versions

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
fromRequiredQueryDevIdThe id of the version to compare from.length 1..256
toQueryDevIdThe id of the version to compare to. Defaults to the latest.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/entries/$ENTRY_ID/diff?from=<from>" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "entry_id": "<entry_id>",
  "from_version_id": "<from_version_id>",
  "to_version_id": "<to_version_id>",
  "identical": false,
  "basis": "original"
}

Read lineage

GET/v2/entries/{entry_id}/lineage

Return where this Entry came from (created, copied, or merged from a branch) and how each version was created, newest first. Needs knowledge:read.

Capability knowledge:read

Guide: Files and versions

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.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

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/entries/$ENTRY_ID/lineage" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "entry_id": "<entry_id>",
  "origin": {
    "kind": "created"
  },
  "data": [
    {
      "version_id": "<version_id>",
      "parent_version_ids": [
        "<parent_version_ids>"
      ],
      "created_at": "2026-11-06T00:00:00Z",
      "kind": "create"
    }
  ]
}

Read processing status

GET/v2/entries/{entry_id}/processing

Return the processing progress of the Entry's latest version: status, knowledge_state, the current stage with progress and, while it waits, queue; when it failed, error. Search finds the version once stage is enriching or ready. Poll this after a 202 from ingest, or send Prefer: wait on the write instead. For many files at once, poll GET /v2/spaces/{space_id}/processing. POST .../reprocess retries a failed version. Needs knowledge:read.

Capability knowledge:read

Guide: Files and versions

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.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/entries/$ENTRY_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "entry_id": "<entry_id>",
  "version_id": "<version_id>",
  "status": "accepted",
  "knowledge_state": "readable",
  "stage": "queued",
  "progress": {
    "done": 1,
    "total": 1
  }
}

Erase an Entry

POST/v2/entries/{entry_id}/purge

Erase an Entry, live or trashed, with every version and its path. Cannot be undone. Needs knowledge:manage and the Space owner role. Storage quota is freed immediately; the job finishes the erasure.

Capability knowledge:manage

Guide: Files and versions

Parameters

NameInTypeDescription
entry_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

Responses

Response headers

  • Location /v2/jobs/{job_id}: poll it until status is succeeded or failed.

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/entries/$ENTRY_ID/purge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "job_id": "<job_id>"
}

Reprocess an Entry

POST/v2/entries/{entry_id}/reprocess

Retry the latest version if it failed; otherwise, process it again. If processing is already in flight, returns 409 job_in_flight with its job_id. Needs knowledge:write.

Capability knowledge:write

Guide: Files and versions

Parameters

NameInTypeDescription
entry_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

Responses

Response headers

  • Location /v2/jobs/{job_id}: poll it until status is succeeded or failed.

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/entries/$ENTRY_ID/reprocess" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "job_id": "<job_id>"
}

Restore an Entry

POST/v2/entries/{entry_id}/restore

Restore a trashed Entry and its path. If the path is occupied, returns 409 path_conflict without renaming anything. A purged Entry returns 409. An Entry that is not in the trash is returned unchanged. Needs knowledge:write.

Capability knowledge:write

Guide: Connect an Agent (MCP)

Parameters

NameInTypeDescription
entry_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

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/entries/$ENTRY_ID/restore" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

Revert to an older version

POST/v2/entries/{entry_id}/revert

Write the content of an older version as a new version. Without If-Match the last write wins. Reverting to the latest version does nothing. The response carries the new version's ETag, as a file write does. Needs knowledge:write.

Capability knowledge:write

Guide: Files and versions

Parameters

NameInTypeDescription
entry_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
If-MatchHeaderstringOne ETag (the version id in quotes): returns 412 unless it matches the latest version. Or *: returns 412 unless the file or Entry exists. Omit for last-write-wins.

Request body

application/json DevRevertRequest

FieldTypeDescription
version_idRequiredDevIdThe id of the version to revert to; its content becomes the new latest version.

Responses

Response headers

  • ETag The ETag of what was just written: send it in If-Match on the next write without reading it again.

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/entries/$ENTRY_ID/revert" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version_id":"<version_id>"}'

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "title": "Launch notes",
  "latest_version_id": "<latest_version_id>",
  "metadata": {},
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z",
  "file": {
    "path": "/notes/hello.md",
    "size": 1,
    "media_type": "<media_type>",
    "etag": "<etag>"
  },
  "knowledge": {
    "state": "readable"
  },
  "memory": {
    "scope": "project",
    "kind": "<kind>",
    "pinned": false,
    "exclude": false
  },
  "memory_exclude": false,
  "access": {
    "role": "owner",
    "capabilities": [
      "knowledge:read"
    ]
  }
}

List versions

GET/v2/entries/{entry_id}/versions

List the versions of an Entry, newest first. Needs knowledge:read.

Capability knowledge:read

Guide: Files and versions

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.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
dataRequiredDevVersion[]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/entries/$ENTRY_ID/versions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "entry_id": "<entry_id>",
      "status": "accepted",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

Read a version

GET/v2/entries/{entry_id}/versions/{version_id}

Read one version of an Entry. A version's content never changes; its status does while it is processed. Returns 404 not_found if the version does not exist, belongs to another Entry, or cannot be seen by the caller. Needs knowledge:read.

Capability knowledge:read

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
version_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.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/entries/$ENTRY_ID/versions/$VERSION_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "entry_id": "<entry_id>",
  "status": "accepted",
  "created_at": "2026-11-06T00:00:00Z"
}

Update a version message

PATCH/v2/entries/{entry_id}/versions/{version_id}/message

Replace the message of one version, at most 120 characters. The message is the only part of a version you can change. Only the Space owner can do this. Needs knowledge:write.

Capability knowledge:write

Parameters

NameInTypeDescription
entry_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
version_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Request body

application/json DevUpdateVersionMessageRequest

FieldTypeDescription
messageRequiredstringThe version's new message, at most 120 characters.max length 120

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/entries/$ENTRY_ID/versions/$VERSION_ID/message" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Move the launch date"}'

Example response

json
{
  "id": "<id>",
  "entry_id": "<entry_id>",
  "status": "accepted",
  "created_at": "2026-11-06T00:00:00Z"
}

Empty the trash

POST/v2/spaces/{space_id}/trash/purge

Erase what is in this Space's trash: the same as POST /v2/entries/{id}/purge for each trashed Entry you can see, so it needs knowledge:manage and the Space owner role, cannot be undone, and frees storage quota immediately. At most 100 Entries a call; has_more says to call again, and calling again is always safe. delete_batch_id erases only what one delete removed. List the trash first with GET /v2/entries?trashed=true.

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

Request body

application/json DevPurgeTrashRequest

FieldTypeDescription
delete_batch_idDevIdErase only what this one delete removed. Without it, everything in the Space's trash that you can see.

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/$SPACE_ID/trash/purge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "purged": [
    {
      "entry_id": "<entry_id>",
      "job_id": "<job_id>"
    }
  ],
  "has_more": false
}