# 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](/docs/eventsourcingdb/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`](/docs/eventsourcingdb/errors/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:

```shell
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](/docs/eventsourcingdb/cloud-events)** 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](#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:

```json
{
  "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`](/docs/eventsourcingdb/errors/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](/docs/eventsourcingdb/api#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.