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 format

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

This is the list of methods that may be supported:

supportedmethods

Lists the methods supported by the relay. May be customized to match permissions assigned to the authenticated user.

• params: []
• result: ["<method-name>", "<method-name>", ...] (an array with the names of all the other supported methods)

banpubkey

Bans a pubkey from the relay. Should automatically remove the pubkey from the allow list.

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

unbanpubkey

Removes a pubkey from the relay’s ban list. Should not automatically add the pubkey to the allow list.

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

listbannedpubkeys

Lists pubkeys banned from the relay.

• params: []
• result: [{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...], an array of objects

allowpubkey

Adds a pubkey to the relay’s allow list. Should automatically remove the pubkey from the ban list.

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

unallowpubkey

Removes a pubkey from the relay’s allow list. Should not automatically add the pubkey to the ban list.

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

listallowedpubkeys

Lists pubkeys on the relay’s allow list.

• params: []
• result: [{"pubkey": "<32-byte-hex>", "reason": "<optional-reason>"}, ...], an array of objects

createrole

Creates a new role.

• params: [id, label, description, color, order]
• result: true (boolean true)

editrole

Updates an existing role.

• params: [id, label, description, color, order]
• result: true (boolean true)

deleterole

Deletes a role.

• params: [id]
• result: true (boolean true)

assignrole

Assigns a role to a pubkey.

• params: ["<32-byte-hex-public-key>", "<role-id>"]
• result: true (a boolean always set to true)

unassignrole

Removes a role from a pubkey.

• params: ["<32-byte-hex-public-key>", "<role-id>"]
• result: true (a boolean always set to true)

listclaims

Lists NIP 43 invite codes currently accepted by the relay.

• params: []
• result: [claim, ...], an array of NIP 43 invite codes

createclaim

Creates a new NIP 43 invite code.

• params: [claim]
• result: true (boolean true)

deleteclaim

Revokes a NIP 43 invite code.

• params: [claim]
• result: true (boolean true)

listeventsneedingmoderation

Lists events awaiting moderation.

• params: []
• result: [{"id": "<32-byte-hex>", "reason": "<optional-reason>"}], an array of objects

allowevent

Adds an event to the relay’s allow list. Should automatically remove the event from the ban list.

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

unallowevent

Removes an event from the relay’s allow list. Should not automatically add the event to the ban list.

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

banevent

Bans an event from the relay. Should automatically remove the event from the allow list.

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

unbanevent

Removes an event from the relay’s ban list. Should not automatically add the event to the allow list.

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

listbannedevents

Lists events banned from the relay.

• params: []
• result: [{"id": "<32-byte hex>", "reason": "<optional-reason>"}, ...], an array of objects

listallowedevents

Lists events on the relay’s allow list.

• params: []
• result: [{"id": "<32-byte-hex>", "reason": "<optional-reason>"}, ...], an array of objects

changerelayname

Changes the relay’s name.

• params: ["<new-name>"]
• result: true (a boolean always set to true)

changerelaydescription

Changes the relay’s description.

• params: ["<new-description>"]
• result: true (a boolean always set to true)

changerelayicon

Changes the relay’s icon.

• params: ["<new-icon-url>"]
• result: true (a boolean always set to true)

allowkind

Adds an event kind to the relay’s allow list.

• params: [<kind-number>]
• result: true (a boolean always set to true)

disallowkind

Disallows an event kind.

• params: [<kind-number>]
• result: true (a boolean always set to true)

listallowedkinds

Lists event kinds on the relay’s allow list.

• params: []
• result: [<kind-number>, ...], an array of numbers

listdisallowedkinds

Lists event kinds the relay disallows.

• params: []
• result: [<kind-number>, ...], an array of numbers

blockip

Adds an IP address to the relay’s block list.

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

unblockip

Removes an IP address from the relay’s block list.

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

listblockedips

Lists IP addresses blocked by the relay.

• params: []
• result: [{"ip": "<ip-address>", "reason": "<optional-reason>"}, ...], an array of objects

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 401 response.