nips/86.md

NIP-86
======

Relay Management API
--------------------

`draft` `optional`

Relays may provide an API for performing management tasks. This is made available as a JSON-RPC-like request-response protocol over HTTP, on the same URI as the relay's websocket.

When a relay receives an HTTP(s) request with a `Content-Type` header of `application/nostr+json+rpc` to a URI supporting WebSocket upgrades, it should parse the request as a JSON document with the following fields:

```json
{
  "method": "<method-name>",
  "params": ["<array>", "<of>", "<parameters>"]
}
```

Then it should return a response in the below format:

```json
{
  "result": {"<arbitrary>": "<value>"},
  "error": "<optional error message, if the call has errored>"
}
```

## Standard Methods

Here is a list of **methods** that MAY be supported:

* `supported_methods`: 
  - **params:** `[]`
  - **result:** `["<method-name>", "<method-name>", /* rest of method names... */ ]`

Extra fields MAY be sent from the relay depending on implementation.

---

* `stats`: 
  - **params:** `[]`
  - **result:**
    ```jsonc
    [
      {
        "num_connections": <number>,
        "uptime": <uptime-in-seconds>,
        "bytes_received": <number>,
        "bytes_sent": <number>,
        "num_events": <number>,
        "event_bytes": <number>,
        "num_files": <number>,
        "file_bytes": <number>
        // and more...
      }
    ]
    ```

Extra fields MAY be sent from the relay depending on implementation.

---

* `set_nip11`: 
  - **params:** 
    ```jsonc
    [
      {
        "name": "new name",
        "description": "new description",
        "icon": null // remove icon. 
        // and more...
      }
    ]
    ```
  - **result:** `true` (a boolean always set to `true`)

The provided input is a potentially incomplete json object of [NIP-11](./11.md) document. 
Relay SHOULD replace provided fields with new ones, add non-existing fields, and remove fields set to null.

---

* `list_events_needing_moderation`: 
  - **params:** `[]`
  - **result:** `[{ "id": "<32-byte-hex>", "reason": "<optional-reason>" }, ...]` (Relay MAY return reported, muted profiles and similar events as a result.)

---

* `ban_pubkey`: 
  - **params:** `["<32-byte-hex-public-key>", "<optional-reason>"]`
  - **result:** `true` (a boolean always set to `true`)

The relay MAY remove events sent by `pubkey` and prevent new events from being written.

---

* `list_banned_pubkeys`: 
  - **params:** `[]`
  - **result:** `[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]` (an array of objects)

---

* `allow_pubkey`: 
  - **params:** `["<32-byte-hex-public-key>", "<optional-reason>"]`
  - **result:** `true` (a boolean always set to `true`)

---

* `list_allowed_pubkeys`: 
  - **params:** `[]`
  - **result:** `[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]` (an array of objects)

---

* `ban_event`: 
  - **params:** `["<32-byte-hex-event-id>", "<optional-reason>"]`
  - **result:** `true` (a boolean always set to `true`)

Relay SHOULD delete and prevent re-broadcasting of event.

---

* `list_banned_events`: 
  - **params:** `[]`
  - **result:** `[{"id": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]` (an array of objects)

---

* `allow_event`: 
  - **params:** `["<32-byte-hex-event-id>", "<optional-reason>"]`
  - **result:** `true` (a boolean always set to `true`)

---

* `list_allowed_events`: 
  - **params:** `[]`
  - **result:** `[{"id": "<32-byte-hex>", "reason": "<optional-reason>"}, ...]` (an array of objects)

---

* `allow_kinds`: 
  - **params:** `(<kind-number>, <another-kind-number>, /* and more... */)`
  - **result:** `true` (a boolean always set to `true`)

---

* `disallow_kinds`: 
  - **params:** `(<kind-number>, <another-kind-number>, /* and more... */)`
  - **result:** `true` (a boolean always set to `true`)

---

* `list_disallow_kinds`: 
  - **params:** `[]`
  - **result:** `(<kind-number>, <another-kind-number>, /* and more... */)` (an array of objects)

---

* `list_allowed_kinds`: 
  - **params:** `[]`
  - **result:** `(<kind-number>, <another-kind-number>, /* and more... */)` (an array of objects)

---

* `block_ip`: 
  - **params:** `["<ip-address>", "<optional-reason>"]`
  - **result:** `true` (a boolean always set to `true`)

---

* `unblock_ip`: 
  - **params:** `["<ip-address>"]`
  - **result:** `true` (a boolean always set to `true`)

---

* `list_blocked_ips`: 
  - **params:** `[]`
  - **result:** `[{"ip": "<ip-address>", "reason": "<optional-reason>"}, ...]` (an array of objects)

---

* `grant_admin`: 
  - **params:** `["<32-byte-hex-public-key>", { "allowed_methods": [...]}]`
  - **result:** `true` (a boolean always set to `true`)

If the admin right is already granted, the allowed methods list must be rewritten.

---

* `revoke_admin`: 
  - **params:** `["<32-byte-hex-public-key>", { "disallowed_methods": [...]}]`
  - **result:** `true` (a boolean always set to `true`)

If the resulting `allowed_methods` list for admin was empty, admin can be removed.

---

### Authorization

The request MUST contain an `Authorization` header with a valid [NIP-98](./98.md) event, except the `payload` tag is REQUIRED. The `u` tag is the relay URL.

If `Authorization` is not provided or is invalid, the endpoint should return a response with a 401 status code.