AZAYA API / V1
O recorte mineral,
em estrutura.
Minerais, operações e registros minerários em uma API de leitura. Cada camada mantém o contexto necessário para saber de onde o dado veio — e onde ele termina.
Explorar o contratoPOR QUE EXISTE
A profundidade está na ligação.
O desafio não é devolver uma lista de minerais. É manter a relação entre mineral, operação, titular, processo, data e evidência sem confundir uma coisa com outra.
A API v1 expõe o recorte atual em um contrato versionado. Ela não transforma um snapshot em dado ao vivo e não entrega uma tese de investimento pronta.
01 / CONTRATO
Uma superfície pequena e previsível.
Todos os endpoints abaixo usam GET e o prefixo /api/v1. IDs são opacos; consulte a lista antes de abrir um detalhe.
GETGETGETGETGETGETlimit de 1 a 100 (padrão 20), after com o último ID recebido. A resposta informa nextCursor.
mineral em /assets e asset em /processes. Filtros inválidos retornam erro explícito.
02 / RESPOSTA
O dado vem com o recorte.
Listas e detalhes seguem um envelope: data, meta e requestId. Erros usam error.code e o mesmo identificador de requisição.
REQUISIÇÃO
GET /api/v1/minerals?limit=2
Authorization: Bearer <sua-chave>RESPOSTA / EXEMPLO
{
"data": [
{
"id": "cobalto",
"name": "Cobalto",
"tagline": "Cátodos de bateria",
"unit": "t de Co contido",
"sources": [
"USGS, Mineral Commodity Summaries 2026, cobalt, tabela World Mine Production and Reserves (produção estimada 2025; reservas), https://pubs.usgs.gov/periodicals/mcs2026/mcs2026-cobalt.pdf"
]
},
{
"id": "grafite",
"name": "Grafite",
"tagline": "Ânodos de bateria",
"unit": "t de grafita natural",
"sources": [
"USGS, Mineral Commodity Summaries 2026, graphite, tabela World Mine Production and Reserves (produção estimada 2025; reservas), https://pubs.usgs.gov/periodicals/mcs2026/mcs2026-graphite.pdf"
]
}
],
"meta": {
"apiVersion": "v1",
"total": 6,
"nextCursor": "grafite",
"quality": "estimated",
"reference": "USGS MCS 2026; produção mineira estimada 2025 e reservas"
},
"requestId": "00000000-0000-4000-8000-000000000000"
}Exemplo gerado a partir do recorte atual. O requestId mostrado é ilustrativo.
03 / PROVENIÊNCIA
O que a API preserva.
Fonte e qualidade
Minerais carregam referências e o marcador estimated; produção mineira estimada para 2025 e reservas vêm do USGS MCS 2026.
Data do snapshot
Recorte SIGMINE extraído em 2026-09-24. A API informa sua idade e marca revisão pendente após 30 dias; eventos podem ter mudado antes disso.
Registro ≠ processo
Um número de processo pode aparecer em mais de um registro espacial. projectLinks só lista vínculos documentados; lista vazia significa associação apenas com a titular. O ID da API identifica o registro.
04 / OPERAÇÃO
Limites claros, falhas legíveis.
Uma chave identifica a cota. O servidor devolve os segundos até a próxima janela quando ela se esgota, e um ID para localizar cada requisição nos logs.
Por chave
O limite vale para todas as rotas de dados e é compartilhado entre instâncias em produção.
Cota excedida
Leia Retry-After antes de tentar novamente. X-RateLimit-Remaining mostra o saldo da janela.
Acesso indisponível
Sem chaves ou controle de uso configurado em produção, a API interrompe as leituras.
Respostas incluem X-Request-Id; informe esse valor ao relatar uma falha. O contrato completo de erros está no OpenAPI.
ACESSO
Em construção, sem fachada.
As rotas exigem uma chave e têm limite de 60 requisições por minuto por chave, compartilhado entre instâncias quando o Redis está configurado. Sem credenciais ou controle de uso em produção, a API fecha o acesso. Ainda faltam emissão pública de chaves, monitoramento operacional e política de disponibilidade para oferecer este serviço amplamente.