Ban API Endpoints¶

This document describes all public and authenticated endpoints of the Azzamo Ban API.

The Ban API provides a centralized, programmable way to query ban status, submit reports, and manage bans for Nostr-based infrastructure.

Base URL:

https://ban-api.azzamo.net

The authoritative machine-readable specification is available at:

https://ban-api.azzamo.net/openapi.json

This document focuses on practical usage and examples.

Public endpoints¶

Public endpoints do not require authentication and are safe to call from clients, frontends, and automation.

List blocked public keys¶

GET /blocked/pubkeys

Description: Returns all currently blocked public keys.

Typical use cases:

Client-side filtering
Transparency dashboards
Relay-side prefiltering

Example:

curl https://ban-api.azzamo.net/blocked/pubkeys

Response (example):

{
  "pubkeys": [
    {
      "pubkey": "npub1...",
      "reason": "spam",
      "expires_at": null
    }
  ]
}

Check ban status for a public key¶

GET /blocked/pubkeys/{pubkey}

Description: Checks whether a specific public key is currently blocked.

Example:

curl https://ban-api.azzamo.net/blocked/pubkeys/npub1example...

Response (example):

{
  "blocked": true,
  "reason": "automated spam",
  "expires_at": 1712345678
}

List blocked words¶

GET /blocked/words

Description: Returns the list of words or phrases currently blocked.

Example:

curl https://ban-api.azzamo.net/blocked/words

Reporting endpoints¶

Reporting endpoints allow users or applications to submit reports for abusive or harmful behavior.

Submit a report¶

POST /reports

Description: Submits a report against a public key.

Reports are used as input signals for moderation and may or may not result in enforcement actions.

Request body:

reported_pubkey (string, required)
reason (string, required)
event_ids (array of strings, optional)
comment (string, optional)

Example:

curl -X POST https://ban-api.azzamo.net/reports \
  -H "Content-Type: application/json" \
  -d '{
    "reported_pubkey": "npub1example...",
    "reason": "spam",
    "event_ids": ["note1..."],
    "comment": "automated replies"
  }'

Response (example):

{
  "status": "received",
  "report_id": "rep_123456"
}

List reports¶

GET /reports

Description: Returns submitted reports. This endpoint may be restricted depending on configuration.

Example:

curl https://ban-api.azzamo.net/reports

Admin endpoints¶

Admin endpoints require authentication using an API key.

The API key must be sent using the Authorization header:

Authorization: Bearer YOUR_API_KEY

Admin endpoints are intended for relay operators and moderation tooling.

Ban a public key¶

POST /admin/ban

Description: Bans a public key, optionally for a limited duration.

Request body:

pubkey (string, required)
reason (string, required)
duration (integer, optional, seconds)

Example:

curl -X POST https://ban-api.azzamo.net/admin/ban \
  -H "Authorization: Bearer $BAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pubkey": "npub1example...",
    "reason": "coordinated spam",
    "duration": 86400
  }'

Unban a public key¶

POST /admin/unban

Description: Removes an active ban from a public key.

Example:

curl -X POST https://ban-api.azzamo.net/admin/unban \
  -H "Authorization: Bearer $BAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pubkey": "npub1example..." }'

Temporarily ban a public key¶

POST /admin/temp-ban

Description: Applies a temporary ban that expires automatically.

Request body:

pubkey
reason
expires_at (unix timestamp)

List all bans¶

GET /admin/bans

Description: Returns all active and expired bans with metadata.

Errors¶

All endpoints return structured JSON errors.

Common HTTP status codes:

400 Invalid request
401 Missing or invalid authentication
403 Insufficient permissions
404 Resource not found
429 Rate limit exceeded
500 Internal server error

Error response example:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}

Clients should not retry requests automatically unless explicitly documented.

Notes¶

Public endpoints are safe for client use
Admin endpoints must never be exposed to browsers
This document complements the OpenAPI spec and may omit low-level schema details