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:

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

Then it should return a response in the below format:

{
  "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:

    [
      {
        "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:

    [
      {
        "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 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_disallowed_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 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.