Referência da API REST

URL base

A API é servida sob /api/v1 na mesma porta do relay WebSocket:

http://<host>:<port>/api/v1/{identifier}
http://<host>:<port>/api/v1/{identifier}/{kind}

Roteamento por host (server.api_host)

Quando server.api_host (ex.: api.example.com) está configurado, a API e o relay são separados pelo cabeçalho Host: api.example.com recebe /api/v1, /health e /metrics; qualquer outro host recebe o relay WebSocket e NIP-11. Sem api_host, a API é servida em todos os hosts. Apenas GET é suportado — solicitações de upgrade WebSocket para /api/v1 são recusadas com 403.

Endpoints

Caminhos baseados em identificadores

Identificadores de autor aceitam npub1..., nprofile1... ou uma pubkey hexadecimal de 64 caracteres (insensível a maiúsculas) em cada endpoint.

Endpoints de consulta e agregação

• GET /api/v1/query — consulta genérica com filtro sem identificador.
• GET /api/v1/count — contagem total para os mesmos parâmetros de filtro (semântica NIP-45).
• GET /api/v1/<npub1...>/kinds — contagens de eventos por kind para um autor, os mais usados primeiro.
• GET /api/v1/<npub1...>/<kind>/daily — contagens por dia para um mês; o mês deve ser 1–12, e cada dia é relatado com preenchimento de zeros até o último dia (cada entrada e o total trazem uma marca approximate).
• GET /api/v1/ids/<hex> — um evento único pelo seu id hexadecimal de 64 caracteres (prefixos rejeitados).
• GET /api/v1/<npub1...>/stats — resumo do autor (total, primeira/última atividade, divisão por kind); first_seen/last_seen/meses são null quando não existem eventos visíveis.
• GET /api/v1/<npub1...>/<kind>/hourly — contagens por hora para um dia; todas as 24 horas são relatadas com preenchimento de zeros (mesmas marcas approximate de daily).
• GET /api/v1/ids/<hex>/related — respostas (#e) e citações (#q) que referenciam o evento; o id do caminho é convertido para minúsculas antes da comparação, e um parâmetro de consulta e é combinado com OR no lado #e.
• GET /api/v1/<npub1...>/follows — a lista de seguidos kind-3 mais recente do autor.
• GET /api/v1/relay/kinds — os kinds mais comuns no relay (amostra limitada, filtrada por visibilidade; marcas approximate e filtered).
• GET /api/v1/relay/top-authors — os autores mais ativos no relay (amostra limitada, filtrada por visibilidade; marcas approximate e filtered).
• GET /api/v1/<npub1...>/relays — a lista de relays NIP-65 mais recente do autor (kind 10002).
• GET /api/v1/<npub1...>/<kind>/monthly — contagens por mês, com preenchimento de zeros no intervalo since/until (padrão: todo o período; limitado a 120 meses).

Parâmetros de consulta

Formato de resposta

Respostas bem-sucedidas retornam 200 OK com o seguinte corpo JSON:

{
  "events": [
    {
      "id": "32-byte hex event id",
      "pubkey": "32-byte hex pubkey",
      "created_at": 1700000000,
      "kind": 1,
      "tags": [["t", "example"]],
      "content": "hello",
      "sig": "64-byte hex signature"
    }
  ],
  "count": 1,
  "more": false
}

Paginação

A paginação é feita com offset e a marca more, calculados sobre a sequência visível — eventos ocultos nunca pulam nem duplicam uma página:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=0"     # página 1
curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=50&offset=50"    # página 2 (quando more era true)

Regras de visibilidade

A API não é autenticada, por isso oculta os mesmos eventos que uma conexão WebSocket anônima:

• Eventos protegidos NIP-70 (com tag -)
• Gift wraps NIP-59 (kind 1059)
• Conteúdo de grupo privado/oculto NIP-29 (visível apenas para membros)

Erros e códigos de estado

Exemplos

Buscar as notas de um usuário (mais recentes primeiro):

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1"

Paginar e ordenar:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?limit=10&offset=10&sort=asc"

Buscar um evento único por id (tanto note1... quanto nevent1... funcionam):

curl "http://127.0.0.1:8080/api/v1/note1..."
curl "http://127.0.0.1:8080/api/v1/nevent1..."

Buscar um evento endereçável (naddr1...):

curl "http://127.0.0.1:8080/api/v1/naddr1..."

Pesquisar:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/1?search=rust"

Filtro por tag:

curl "http://127.0.0.1:8080/api/v1/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkws3w8ktc/7?e=<event-id>&limit=100"