API Oracle

GET/health

Estado de funcionamento do processo e versão da publicação.

{
  "status": "healthy",
  "version": "0.3.0"
}

Um processo saudável ainda pode estar aguardando eventos dos relays ou não conseguir persistir atualizações. Use /ready para verificar a prontidão da ingestão.

GET/ready

Estado da ingestão: HTTP 200 quando pronta, HTTP 503 caso contrário.

A prontidão exige ingestão em execução, ausência de falha atual no banco de dados e um evento de seguidores ou silenciamento recebido nos últimos cinco minutos. Assim, um relay privado sem atividade pode gerar 503 mesmo com o processo operacional. Exemplo durante a espera pelo primeiro evento:

{
  "running": true,
  "ready": false,
  "last_event_received_at": 0,
  "last_persisted_at": 0,
  "persisted_events": 0,
  "lagged_notifications": 0,
  "persistence_errors": 0,
  "coverage": "configured_relays_only"
}

Os horários são expressos em segundos Unix; zero significa que ainda não foram observados. persisted_events conta atualizações aceitas de autores gravadas no armazenamento após a consolidação dos lotes. lagged_notifications e persistence_errors expõem problemas na ingestão.

GET/stats

Contagens do grafo indexado, configurações de cache, métricas de bloqueio e estado da ingestão.

{
  "node_count": 3,
  "edge_count": 2,
  "nodes_with_follows": 2,
  "mute_edge_count": 0,
  "nodes_with_mute_lists": 1,
  "sync": {
    "running": true,
    "ready": false,
    "last_event_received_at": 0,
    "last_persisted_at": 0,
    "persisted_events": 0,
    "lagged_notifications": 0,
    "persistence_errors": 0,
    "coverage": "configured_relays_only"
  },
  "cache": {
    "size": 0,
    "capacity": 100000,
    "ttl_secs": 300
  },
  "locks": {
    "write_lock_count": 0,
    "write_lock_avg_us": 0,
    "write_lock_max_us": 0,
    "read_lock_count": 0,
    "read_lock_avg_us": 0,
    "read_lock_max_us": 0
  }
}

As contagens e configurações acima são ilustrativas. edge_count conta arestas de seguidores; mute_edge_count conta arestas públicas de silenciamento de chaves públicas. nodes_with_mute_lists inclui listas conhecidas sem entradas públicas de chaves públicas. Os tempos de bloqueio são em microssegundos. O objeto sync tem os mesmos campos de /ready.

GET/distance

Menor distância direcionada de seguidores entre duas chaves públicas.

• from e to: chaves públicas de origem e destino obrigatórias.
• max_hops: de 1 a 5, padrão 3.
• include_bridges: booleano, padrão false. Inclui os nós de encontro da busca quando disponíveis.
• bypass_cache: booleano, padrão false. Recalcula a partir do grafo indexado atual; não busca novos dados dos relays.

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "hops": 2,
  "path_count": 1,
  "mutual_follow": false
}

hops é zero para a distância até a própria conta e um para quem é seguido diretamente. Um valor null significa que nenhuma rota foi encontrada na profundidade solicitada no grafo indexado. Isso não prova que não exista conexão em outro lugar no Nostr.

path_count conta os caminhos direcionados mais curtos, mesmo quando as pontes são omitidas; as contagens são limitadas ao máximo de um inteiro de 64 bits sem sinal. mutual_follow indica que as contas seguem uma à outra diretamente. O campo opcional bridges contém os nós de encontro da busca, não um caminho completo nem uma prova de caminhos disjuntos.

POST/distance/batch

Consulte até 100 destinos a partir de uma origem, preservando a ordem e as duplicatas dos destinos.

Campos JSON obrigatórios: from e targets. Os opcionais max_hops, include_bridges e bypass_cache usam os mesmos valores padrão de /distance.

Requisição

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "targets": [
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  ],
  "max_hops": 3
}

Resposta

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "results": [
    {
      "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "hops": 2,
      "path_count": 1,
      "mutual_follow": false
    }
  ]
}

Cada resultado inclui from e to.

GET/path

Retorna as chaves públicas intermediárias de um dos caminhos direcionados de seguidores mais curtos.

from e to são obrigatórios; max_hops é opcional (de 1 a 5, padrão 3).

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "path": [
    "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  ]
}

O exemplo representa duas arestas de seguidores: da origem à ponte e da ponte ao destino. Origem e destino são excluídos de path. Caminhos até a própria conta ou até quem é seguido diretamente retornam um array vazio; a ausência de rota na profundidade solicitada retorna null. Essa resposta não possui o campo hops.

GET/follows

Pagina a lista de seguidores atualmente indexada para uma chave pública.

pubkey é obrigatório; offset (padrão 0) e limit (padrão 500, máximo 5000) são opcionais. total é o tamanho completo da lista indexada, independentemente do tamanho da página.

{
  "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "follows": [
    "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  ],
  "total": 1
}

Uma chave pública desconhecida retorna uma lista vazia e total: 0.

GET/common-follows

Retorna as chaves públicas seguidas diretamente por ambas as contas.

Parâmetros obrigatórios: from e to.

{
  "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "common_follows": [
    "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  ]
}

GET/mutes

Pagina as entradas públicas de chaves públicas de uma lista de silenciamento indexada do tipo 10000.

pubkey é obrigatório; offset (padrão 0) e limit (padrão 500, máximo 5000) são opcionais. total é o tamanho completo da lista indexada, independentemente do tamanho da página.

{
  "pubkey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "mutes": [],
  "total": 0,
  "public_list_known": true
}

public_list_known: false significa que nenhum evento de lista de silenciamento foi indexado para essa chave pública. Um evento conhecido pode não ter entradas públicas de chaves públicas, como mostrado acima. Entradas criptografadas de silenciamento não estão disponíveis para o Oracle, e uma lista pública conhecida e vazia ainda pode conter entradas criptografadas. Tags de silenciamento de palavras, hashtags e conversas são excluídas das evidências de chaves públicas.

GET/trust

Retorna a distância de seguidores junto com observações públicas separadas de silenciamento.

• from e to: chaves públicas de origem e destino obrigatórias.
• max_hops: de 1 a 5, padrão 3.
• include_bridges: booleano, padrão false. Inclui os nós de encontro da busca quando disponíveis.
• bypass_cache: booleano, padrão false. Recalcula a partir do grafo indexado atual; não busca novos dados dos relays.

{
  "follow_distance": {
    "from": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "to": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "hops": 2,
    "path_count": 1,
    "mutual_follow": false
  },
  "public_mute_evidence": {
    "source_mutes_target": false,
    "target_mutes_source": false,
    "followed_muters": [
      "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
    ],
    "source_mute_list_known": true,
    "target_mute_list_known": false
  }
}

followed_muters lista as contas seguidas diretamente pela origem cujas listas públicas indexadas de silenciamento contêm o destino. Os dois booleanos de silenciamento direto descrevem a relação entre origem e destino; os indicadores de lista conhecida distinguem listas ausentes de listas públicas conhecidas.

Silenciamentos podem expressar preferências pessoais. A ausência de evidência pública não é um endosso. Os clientes decidem como usar essas observações: a resposta não aplica peso, pontuação agregada ou exclusão automática. A distância de seguidores e as evidências de silenciamento podem ser lidas em instantes ligeiramente diferentes durante a ingestão.