nips/86.md
2024-07-09 17:34:23 -03:00

3.3 KiB

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 an Authorization header and 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 format

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

This is the list of methods that may be supported:

  • supportedmethods:
    • params: []
    • result: ["<method-name>", "<method-name>", ...] (an array with the names of all the other supported methods)
  • banpubkey:
    • params: ["<32-byte-hex-public-key>", "<optional-reason>"]
    • result: true (a boolean always set to true)
  • listbannedpubkeys:
    • params: []
    • result: [{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...], an array of objects
  • allowpubkey:
    • params: ["<32-byte-hex-public-key>", "<optional-reason>"]
    • result: true (a boolean always set to true)
  • listallowedpubkeys:
    • params: []
    • result: [{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...], an array of objects
  • listeventsneedingmoderation:
    • params: []
    • result: [{"id": "<32-byte-hex>", "reason": "<optional-reason>"}], an array of objects
  • allowevent:
    • params: ["<32-byte-hex-event-id>", "<optional-reason>"]
    • result: true (a boolean always set to true)
  • banevent:
    • params: ["<32-byte-hex-event-id>", "<optional-reason>"]
    • result: true (a boolean always set to true)
  • listbannedevents:
    • params: []
    • result: [{"id": "<32-byte hex>", "reason": "<optional-reason>"}, ...], an array of objects
  • changerelayname:
    • params: ["<new-name>"]
    • result: true (a boolean always set to true)
  • changerelaydescription:
    • params: ["<new-description>"]
    • result: true (a boolean always set to true)
  • changerelayicon:
    • params: ["<new-icon-url>"]
    • result: true (a boolean always set to true)
  • allowkind:
    • params: [<kind-number>]
    • result: true (a boolean always set to true)
  • disallowkind:
    • params: [<kind-number>]
    • result: true (a boolean always set to true)
  • listallowedkinds:
    • params: []
    • result: [<kind-number>, ...], an array of numbers
  • blockip:
    • params: ["<ip-address>", "<optional-reason>"]
    • result: true (a boolean always set to true)
  • unblockip:
    • params: ["<ip-address>"]
    • result: true (a boolean always set to true)
  • listblockedips:
    • params: []
    • result: [{"ip": "<ip-address>", "reason": "<optional-reason>"}, ...], an array of objects

Authorization

The request must contain an Authorization header with the value set to Nostr <base64(auth-event)> in which <auth-event> is an event of kind 27235 with a tag ["host", <hostname-of-target-relay>], a tag ["payload", <sha256-hash-of-the-request-body-as-lowercase-hex>] and created_at set to the current timestamp.