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:

### System

* Supported methods

**name:** `supported_methods`

**params:** `[]`

**result:**

```json
["<method-name>", "<method-name>", /* rest of method names... */ ] 
```

---

* Stats

**name:** `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 relay depending on implementation.

---

* Set NIP11

**name:** `set_nip11`

**params:** 

```jsonc
[
  {
    "name": "new name",
    "description": "new description",
    "icon": null // removes icon. 
    // and more...
  }
]
```

**result:**

```jsonc
true
```

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

---

* List Events Needing Moderation

**name:** `list_events_needing_moderation`

**params:** `[]`

**result:**

```json
[{"id": "<32-byte-hex>", "reason": "<optional-reason>"}]
```

Relay MAY return reported, muted profiles and similar events as result.

* Write Policy

* Ban pubkey

**name:** `ban_pubkey`

**params:** 

```json
["<32-byte-hex-public-key>", "<optional-reason>"]
```

**result:**

```json
true
```

Relay MAY remove events sent by `pubkey` and prevent new events from them to be written.

---

* List Banned Pubkeys

**name:** `list_banned_pubkeys`

**params:** `[]`

**result:**

```json
[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, /* and more... */]
```

---

* Allow Pubkey

**name:** `allow_pubkey`

**params:** 

```json
["<32-byte-hex-public-key>", "<optional-reason>"]
```

**result:**

```json
true
```

---

* List Allowed Pubkeys

**name:** `list_allowed_pubkeys`

**params:** `[]`

**result:**

```json
[{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, /* and more... */]
```

---

* Allow Event

**name:** `allow_event`

**params:** 

```json
["<32-byte-hex-event-id>", "<optional-reason>"]
```

**result:**

```json
true
```

---

* Ban Event

**name:** `ban_event`

**params:** 

```json
["<32-byte-hex-event-id>", "<optional-reason>"]
```

**result:**

```json
true
```

Relay SHOULD delete and prevent re-broadcasting of event.

---

* List Banned Events

**name:** `list_banned_events`

**params:** `[]`

**result:**

```json
[{"id": "<32-byte hex>", "reason": "<optional-reason>"}, ...]
```

---

* Allow Kinds

**name:** `allow_kinds`

**params:** 

```json
[<kind-number>, <another-kind-number>, /* and more... */]
```

**result:**

```json
true
```

---

* Disallow Kinds

**name:** `disallow_kinds`

**params:** 

```json
[<kind-number>, <another-kind-number>, /* and more... */]
```

**result:**

```json
true
```

---

* List Disallowed Kinds

**name:** `list_disallow_kinds`

**params:** `[]`

**result:**

```json
[<kind-number>, <another-kind-number>, /* and more... */]
```

---

* List Allowed Kinds

**name:** `list_allowed_kinds`

**params:** `[]`

**result:**

```json
[<kind-number>, <another-kind-number>, /* and more... */]
```

---

* Block IP

**name:** `block_ip`

**params:** 

```json
["<ip-address>", "<optional-reason>"]
```

**result:**

```json
true
```

---

* Unblock IP

**name:** `unblock_ip`

**params:** 

```json
["<ip-address>"]
```

**result:**

```json
true
```

---

* List Blocked IPs

**name:** `list_blocked_ips`

**params:** `[]`

**result:**

```json
[{"ip": "<ip-address>", "reason": "<optional-reason>"}, /* and more... */]
```

### Access control

---

* Grant Admin

**name:** `grant_admin`

**params:** 

```jsonc
["<32-byte-hex-public-key>", {
  "allowed_methods": [
    "method-name",
    // an array of method names.
  ]
}]
```

**result:**

```json
true
```

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

---

* Revoke Admin

**name:** `revoke_admin`


**params:** 

```jsonc
["<32-byte-hex-public-key>", {
  "disallowed_methods": [
    "method-name",
    // an array of method names.
  ]
}]
```

**result:**

```json
true
```

If 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 401 status code.