Skip to content

Ban API Overview

The Azzamo Ban API provides a shared moderation and enforcement layer for Nostr-based infrastructure.

It is designed to expose ban state, reporting signals, and enforcement actions in a transparent and machine-readable way, without requiring clients or relays to implement their own isolated moderation systems.

Purpose

The Ban API exists to solve a practical problem:

  • Spam, abuse, and coordinated attacks affect multiple relays and clients at once
  • Local-only moderation does not scale across the Nostr network
  • Clients and infrastructure need a consistent source of ban state

The Ban API provides a common reference point while preserving Nostr’s decentralized nature.

What the Ban API does

The Ban API allows consumers to:

  • Query whether a public key is currently banned
  • Retrieve lists of blocked public keys and blocked words
  • Submit reports about abusive or harmful behavior
  • Apply or remove bans through authenticated endpoints
  • Inspect ban metadata such as reasons and expiration

The API itself does not publish or censor content. It exposes signals that other systems can choose to enforce.

Public and admin access

The Ban API is split into two conceptual layers.

Public access

Public endpoints are readable without authentication and are intended for:

  • Nostr clients
  • Relay software
  • Transparency tools
  • Community dashboards

These endpoints expose ban state only. They do not allow modification.

Admin access

Admin endpoints require authentication and are intended for:

  • Relay operators
  • Moderation tooling
  • Automated enforcement systems

Admin endpoints allow:

  • Banning and unbanning public keys
  • Applying temporary bans
  • Managing blocked words
  • Reviewing reports

Admin access is restricted and must not be exposed to end users.

Reporting model

The Ban API supports reporting as an input signal, not an automatic punishment.

  • Reports can be submitted by users or systems
  • Reports may reference public keys and specific events
  • Reports are reviewed or processed according to configured thresholds

A report does not automatically result in a ban.

Enforcement

The Ban API does not enforce bans by itself.

Enforcement is performed by consuming systems, such as:

  • Nostr relays
  • Import pipelines
  • Client-side filters
  • Moderation dashboards

This separation keeps enforcement explicit and auditable.

Transparency and trust

The Ban API is designed to be observable.

  • Public ban lists can be inspected
  • Ban reasons and expiration may be exposed
  • Decisions are not hidden behind opaque systems

Consumers are free to use, ignore, or combine Ban API data with other signals.

What the Ban API is not

To set expectations clearly:

  • It is not global censorship
  • It does not force clients or relays to comply
  • It does not decide truth or correctness
  • It is not a reputation oracle

It is a tool for coordination, not authority.

When to use the Ban API

The Ban API is useful if you:

  • Operate a relay or relay cluster
  • Build a Nostr client with moderation features
  • Need shared ban state across services
  • Want transparent, inspectable moderation signals

If you want fully local or purely manual moderation, you may not need this API.

Where to go next

  • Ban API endpoints and examples
  • Moderation and trust philosophy
  • Relay spam filtering behavior