Documentação da API do Kosto:
autoridade de domínio, dentro das suas próprias ferramentas.

Primeiros passos

Início rápido

Três passos da chave à primeira resposta.

1. 1

   Obtenha uma chave

   Crie uma chave abaixo. A chave só aparece no momento em que é criada; copie-a e guarde em um lugar seguro.
2. 2

   Envie a primeira requisição

   Envie a chave no cabeçalho Authorization. O exemplo à direita já vem pronto na linguagem que você escolher; troque YOUR_API_KEY pela sua própria chave.

3. 3

   Leia a resposta

   O campo authority_score é a pontuação de 0 a 100. Se found for false, o domínio não está no índice de links; isso não é um erro e é retornado 200. score_source informa o tipo de pontuação: data é baseada em dados, enquanto standard e calibrated são pontuações aproximadas.

Em cada endpoint, o painel Testar permite enviar a requisição direto do navegador. A chave fica apenas na memória desta aba, não é salva em lugar nenhum e nenhuma requisição é enviada até você pressionar o botão.

Primeiros passos

Autenticação

Todo endpoint, exceto /api/v1/openapi.json, exige uma chave de API. A chave começa com op_ e tem 35 caracteres no total. Use um dos dois cabeçalhos abaixo; os dois fazem o mesmo trabalho.

Protegendo a chave

• O servidor armazena não a chave em si, mas o resumo SHA-256 dela. Se você perdê-la, gere uma nova chave e revogue a antiga.
• Guarde a chave em uma variável de ambiente ou no cofre de segredos. Não a coloque em código-fonte, repositórios públicos nem em código executado no navegador.
• Uma chave revogada recebe 403 key_revoked. Se a chave estiver ausente ou malformada, é retornado 401.
• Nenhum cabeçalho CORS é enviado, então o código de navegador de outro site não consegue ler esta API (cross_site_forbidden). Scripts, linha de comando e código do lado do servidor funcionam sem problemas.
• No modo conta, a chave pertence a uma conta e é contabilizada no plano dela; uma chave cuja conta esteja suspensa, ou que não esteja vinculada a nenhuma conta, recebe 403.

Primeiros passos

Limites de taxa e cotas

Há dois limites separados: o limite de requisições por minuto é igual para todas as chaves, enquanto as cotas mensais e diárias dependem do seu plano.

Limite de taxa: 120 requisições por minuto

Cada chave pode fazer 120 requisições em uma janela fixa de 60 segundos. A janela abre com a primeira requisição da chave, fecha 60 segundos depois e o contador é zerado. Requisições que não enviam uma chave válida são contadas em uma janela compartilhada por endereço de cliente. Requisições rejeitadas (como 401 ou 400) também contam na janela. Toda resposta de /api/v1 traz estes cabeçalhos:

Quando o limite é excedido, é retornado 429 rate_limited. Aguarde o tempo indicado em Retry-After e tente de novo; tentar novamente sem esperar só enche ainda mais a janela.

Cotas por plano

No modo conta, cada chamada desconta um do contador de requisições de API. Uma consulta em lote gasta tantas linhas da consulta em lote quantas forem as suas linhas, e uma auditoria de spam gasta uma auditoria de spam. Uma chamada que falha devolve o que gastou. Uma auditoria de spam do mesmo domínio no mesmo dia não é contada de novo (exceto com fresh=1).

As cotas diárias e mensais são renovadas à meia-noite e no início do mês no horário da Turquia (UTC+3). Quando uma cota se esgota, é retornado 429 quota_exceeded; a mensagem informa qual contador acabou, seu uso e seu plano. Para os preços, veja a página de planos.

Primeiros passos

Códigos de erro

Os erros vêm com um código de status HTTP e sempre com o mesmo corpo. O code é estável, então seu programa deve se basear nele. O message é uma descrição escrita para pessoas e pode mudar; por padrão vem em inglês, e você pode escolher outro idioma com o cabeçalho Accept-Language ou X-Kosto-Lang.

• Em respostas 5xx e 429, aguarde o tempo indicado no cabeçalho Retry-After, se ele estiver presente. Não repita uma resposta 4xx com a mesma requisição; corrija a requisição.
• Em uma resposta 405, o cabeçalho Allow informa qual método o endpoint aceita. HEAD é tratado como GET.
• Enquanto o índice de links está carregando, as consultas de referências podem retornar 503 graph_unavailable; tente de novo após Retry-After: 15.

Primeiros passos

Paginação e requisições em lote

A API não usa cursores (cursor) nem números de página. Os endpoints que retornam listas respondem com uma única resposta, e o tamanho dela é limitado por parâmetros.

Dividindo listas grandes

Se você tiver mais de 1000 domínios, divida a lista em blocos de 1000 e envie-os em sequência. Cada bloco é uma requisição e conta no limite por minuto; no modo conta, ele também consome tantas cotas de consulta em lote quantas linhas tiver.

Outros

Versionamento e registro de alterações

A versão faz parte do endereço: /api/v1. O campo info.version do documento OpenAPI informa a versão do documento desta versão da API.

• Novos endpoints e novos campos nas respostas podem ser adicionados sem mudar a versão. Esperamos que seu cliente ignore os campos que não conhece.
• Mudanças incompatíveis, como alterar o tipo ou o significado de um campo existente ou remover um campo, chegam com uma nova versão (/api/v2).
• Os textos de message podem mudar. Baseie-se nos valores de code e nos códigos de status HTTP.

1. 1.0.0Versão atual

   Primeira versão. Sete endpoints: domain, backlinks, compare, bulk, spam, usage e openapi.json.

   • Autenticação por chave: Authorization: Bearer ou X-API-Key.
   • Limite de 120 requisições por minuto e cabeçalhos X-RateLimit-*.
   • Formato de erro: { "error": { "code", "message" } }.