← All NIPs

NIP-86

Relay Management API

DraftHTTP

An HTTP API, on the same address as the relay's WebSocket, that lets a relay operator ban pubkeys, allow kinds and moderate events with simple JSON-RPC calls signed through NIP-98.

Status
In use and still allowed to change.
Last changed
Sep 24, 2026

Try it

Edit the form or the JSON: both stay in sync, the badge says whether the result is valid, and tapping any field explains it.

What to build

How the parts connect: Sign, then call

Examples
Valid

Form
POST

A JSON-RPC-like POST to the relay URL: one method, its params, one answer.

Headers

Tells the relay this HTTP request is a management call.

The string "Nostr " followed by the base64-encoded, signed kind 27235 event.

The auth event inside the header

{
  "kind": 27235,
  "created_at": 1735689600,
  "tags": [
    [
      "u",
      "https://relay.delta.example/"
    ],
    [
      "method",
      "POST"
    ],
    [
      "payload",
      "c8c5e8bc5a0a152d0537c925d29fa95a9456715bd77d6dd4c2e1f96175920ab5"
    ]
  ],
  "content": "",
  "pubkey": "1c028b39e7f3228444b3261e4b718efa92a91470086b44c9a72ef5357e970148",
  "id": "5b504ac6be7ecfa88f0c1fa0e51999ea45bcb5240b094cc1b6e2f4edd59c4857",
  "sig": "b8f8d10c380c8da6c22cf7dd20c39b1e4f72589d95698582920fe7ee7f887e603b3684618357f3b3a88cc18d2a4699010ab4a7294e82e7f60300d1247f626f42"
}

Body application/nostr+json+rpc

body

The call: which method to run and with which parameters.

Name of the method to run.

params

The method's arguments, in order. An empty array for methods without params.

Responses

  • 200 The call was handled.
  • 401 Authorization header missing or invalid.

How this NIP works

Step 1 of 5

Same address, plain HTTP

The management API lives at the relay's own URL, reached over https instead of wss. The relay spots it by the Content-Type application/nostr+json+rpc.

In the course

No course chapter covers this NIP yet. The editor above is the quickest way in.

Builds on

  • NIP-98 HTTP Auth

    Every call is authorized with a NIP-98 event in the Authorization header.

See also

Specification

Specification text is quoted in English from the nostr-protocol/nips repository. Our explanations and the interface are translated. Source on GitHub at commit 0046368

Read the spec915 words, quoted from the repository at commit 0046368.

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.