enable-read-only-mode

Enables read-only mode, which refuses every write until the server is next started.

Route: POST /api/v2/management/enable-read-only-mode
Category: management
Authentication: required, with the API token
Answer: a single JSON envelope

In read-only mode, reading, observing, and querying events go on, while writing events, registering event schemas, and restoring backups are refused with store-read-only. Writes that are pending when the mode is enabled are stored before the answer, so that the stored events no longer change once it arrives. The mode cannot be switched off while the server runs, and any restart ends it, including one you did not plan; to keep writes refused across restarts, start the server with the --read-only flag instead.

Request#

The route takes no body, and ignores one that is sent. To enable read-only mode:

curl \
  -X POST \
  -H "authorization: Bearer secret" \
  http://localhost:3000/api/v2/management/enable-read-only-mode

Answer#

The answer is a single envelope, rather than a stream, so it has neither heartbeats nor an end item:

Type	Data	When
`event`	a CloudEvent of the type `io.eventsourcingdb.api.read-only-mode-enabled`, with an empty object as its `data`	When the request enabled read-only mode.
`error`	`code`, `description`, and `details`	When read-only mode was on already, see Errors.

The event only answers the request and is not stored in the database. Its id is a UUID, its source is https://www.eventsourcingdb.io, and its subject is the path of the route.

The request above is answered with:

{
  "type": "event",
  "data": {
    "specversion": "1.0",
    "id": "01a180c8-399b-71f4-a704-75d6eceb4d0c",
    "source": "https://www.eventsourcingdb.io",
    "type": "io.eventsourcingdb.api.read-only-mode-enabled",
    "subject": "/api/v2/management/enable-read-only-mode",
    "time": "2026-10-28T04:32:48.027113Z",
    "datacontenttype": "application/json",
    "data": {}
  }
}

Errors#

The route reports this error as an envelope of the type error, in place of the event:

read-only-mode-already-enabled: Read-only mode was on already, through the --read-only flag or an earlier request, so nothing changes. A client that only wants the database to be read-only can take it as success.

Status Codes#

The server answers with a status code other than 200 where it cannot take the request at all, as described in Errors:

401: The API token is missing or wrong.
429: Too many requests were sent; the answer says when to try again.
500: The server failed unexpectedly.
503: The server is shutting down.