Ir al contenido
kosto kosto API v1
OpenAPI Volver al panel

Kosto API · v1

Documentación de la API de Kosto:
autoridad de dominio, dentro de tus propias herramientas.

Consulta por HTTP la puntuación de autoridad que ves en el panel, los dominios de referencia, la comparación lado a lado y la auditoría de spam. Todas las respuestas son JSON, los nombres de los campos se escriben en snake_case y cada endpoint incluye más abajo un ejemplo que funciona.

URL base
Endpoint
7
Límite por minuto
120
Formato
JSON
Autenticación
Clave de API

Puntuación de autoridad

Puntuación de 0 a 100, rankings y los componentes que forman la puntuación. Un dominio o diez a la vez.

Dominios de referencia

Dominios que enlazan a un dominio, ordenados por puntuación; tú defines la puntuación mínima.

Auditoría de spam

Puntuación de riesgo y motivos para señales de abuso como apuestas, contenido adulto, farmacia o réplicas.

  • Todos los endpoints están bajo /api/v1. La versión forma parte de la dirección.
  • Las solicitudes y respuestas son JSON en UTF-8. Las fechas se escriben en ISO 8601 (UTC).
  • Definición legible por máquinas: descarga el documento OpenAPI 3.1.

Primeros pasos

Inicio rápido

Tres pasos desde obtener una clave hasta la primera respuesta.

  1. 1

    Obtén una clave

    Crea una clave abajo. La clave solo aparece en el momento en que se crea; cópiala y guárdala en un lugar seguro.

  2. 2

    Envía la primera solicitud

    Envía la clave en el encabezado Authorization. El ejemplo de la derecha está listo en el lenguaje que elijas; sustituye YOUR_API_KEY por tu propia clave.

  3. 3

    Lee la respuesta

    El campo authority_score es la puntuación de 0 a 100. Si found es false, el dominio no está en el índice de enlaces; esto no es un error y se devuelve 200. score_source indica el tipo de puntuación: data se basa en datos, mientras que standard y calibrated son puntuaciones aproximadas.

Desde el panel Probar que hay bajo cada endpoint se puede enviar la solicitud directamente desde el navegador. La clave solo se conserva en la memoria de esta pestaña, no se guarda en ningún sitio y la solicitud no se envía hasta que se pulsa el botón.

Primeros pasos

Autenticación

Todos los endpoints, salvo /api/v1/openapi.json, requieren una clave de API. La clave empieza por op_ y mide 35 caracteres en total. Usa uno de los dos encabezados siguientes; ambos hacen lo mismo.

Encabezado HTTPFormato
AuthorizationBearer op_… (Bearer no distingue entre mayúsculas y minúsculas)
X-API-Keyop_…

Protege la clave

  • El servidor no guarda la clave en sí, sino su resumen SHA-256. Si la pierdes, genera una clave nueva y revoca la anterior.
  • Guarda la clave en una variable de entorno o en tu gestor de secretos. No la incluyas en el código fuente, en repositorios públicos ni en código que se ejecute en el navegador.
  • Una clave revocada recibe 403 key_revoked. Si falta la clave o su formato es incorrecto, se devuelve 401.
  • No se envía el encabezado CORS, por lo que el código de navegador de otro sitio no puede leer esta API (cross_site_forbidden). Los scripts, la línea de comandos y el código del lado del servidor funcionan sin problemas.
  • En modo cuenta, la clave pertenece a una cuenta y se contabiliza según el plan de esa cuenta; una clave cuya cuenta está suspendida, o que no está vinculada a ninguna cuenta, recibe 403.

Primeros pasos

Límites de frecuencia y cuotas

Hay dos límites distintos: el límite de solicitudes por minuto es el mismo para todas las claves, mientras que las cuotas mensuales y diarias dependen de tu plan.

Límite de velocidad: 120 solicitudes por minuto

Cada clave puede realizar 120 solicitudes en una ventana fija de 60 segundos. La ventana se abre con la primera solicitud de la clave, se cierra 60 segundos después y el contador se reinicia. Las solicitudes que no envían una clave válida se cuentan en una ventana compartida por dirección de cliente. Las solicitudes rechazadas (como 401 o 400) también se registran en la ventana. Cada respuesta de /api/v1 incluye estos encabezados:

Encabezado HTTPSignificado
X-RateLimit-LimitNúmero de solicitudes permitidas por ventana (120).
X-RateLimit-RemainingSolicitudes restantes en la ventana actual.
X-RateLimit-ResetMomento en que se cierra la ventana, en segundos Unix.
Retry-AfterSegundos que se deben esperar en las respuestas 429 y 503.

Cuando se supera el límite, se devuelve 429 rate_limited. Espera el tiempo indicado en el encabezado Retry-After y vuelve a intentarlo; reintentar sin esperar solo llena más la ventana.

Cuotas por plan

En modo cuenta, cada llamada descuenta una unidad del contador de solicitudes de API. Una consulta en bloque consume tantas filas de consulta en bloque como filas tenga, y una auditoría de spam consume una auditoría de spam. Una llamada fallida devuelve lo que consumió. La auditoría de spam del mismo dominio en el mismo día no se vuelve a contar (salvo con fresh=1).

PlanClave de APISolicitudes a la API / mesFilas de consulta en bloque / díaAuditorías de spam / día

Las cuotas diarias y mensuales se renuevan a medianoche y a principios de mes según la hora de Turquía (UTC+3). Cuando se agota una cuota, se devuelve 429 quota_exceeded; el mensaje indica qué contador se agotó, tu uso y tu plan. Para ver los precios, consulta la página de planes.

Primeros pasos

Códigos de error

Los errores llegan con un código de estado HTTP y siempre con el mismo cuerpo. El code es estable, por lo que el programa debe ramificarse según él. El message es una descripción escrita para personas y puede cambiar; por defecto está en inglés y se puede elegir otro idioma con el encabezado Accept-Language o X-Kosto-Lang.

EstadoCódigoCuándo
  • En las respuestas 5xx y 429, si existe el encabezado Retry-After, espera el tiempo que indica. No repitas la misma solicitud tras una respuesta 4xx; corrígela.
  • En una respuesta 405, el encabezado Allow indica el método que admite el endpoint. HEAD se trata igual que GET.
  • Mientras se carga el índice de enlaces, las consultas de referencias pueden devolver 503 graph_unavailable; vuelve a intentarlo tras Retry-After: 15.

Primeros pasos

Paginación y solicitudes en bloque

La API no utiliza cursores (cursor) ni números de página. Los endpoints que devuelven listas responden con una sola respuesta, cuyo tamaño se limita mediante parámetros.

EndpointRegla
GET /backlinkslimit es como máximo 1.000 (por defecto 100). El servidor elige primero las mejores referencias por puntuación, y el filtro min_score se aplica entre las 1.000 mejores referencias según la posición de enlaces. Por eso, al filtrar, returned puede ser menor que limit. total es el número total de referencias, independiente del filtro.
GET /compareEntre 2 y 10 dominios. Las variantes que apuntan al mismo sitio se reducen a una sola fila; tras la reducción deben quedar al menos dos sitios distintos.
POST /bulkComo máximo 1.000 dominios por solicitud y un cuerpo de 1 MB como máximo. Si se superan, se recibe too_many_domains (400) o payload_too_large (413). Las líneas vacías se omiten, un mismo sitio se fusiona en una fila y las entradas no válidas permanecen en su lugar como valid: false; el orden es el de la primera aparición.

Dividir listas grandes

Si tienes más de 1.000 dominios, divide la lista en bloques de 1.000 y envíalos uno tras otro. Cada bloque es una solicitud y cuenta para el límite por minuto; en el modo de cuenta, además, consume tantas cuotas de consulta en bloque como filas tenga.

Otros

Versiones y registro de cambios

La versión forma parte de la dirección: /api/v1. El campo info.version del documento OpenAPI indica la versión del documento de esta versión de la API.

  • Se pueden añadir nuevos endpoints y nuevos campos en las respuestas sin cambiar la versión. Esperamos que tu cliente ignore los campos que no conozca.
  • Los cambios incompatibles, como modificar el tipo o el significado de un campo existente o eliminar un campo, llegan con una nueva versión (/api/v2).
  • Los textos de message pueden cambiar. Basa tu lógica en los valores de code y en los códigos de estado HTTP.
  1. 1.0.0Versión actual

    Primera versión. Siete endpoints: domain, backlinks, compare, bulk, spam, usage y openapi.json.

    • Autenticación por clave: Authorization: Bearer o X-API-Key.
    • Límite de solicitudes de 120 por minuto y encabezados X-RateLimit-*.
    • Formato de error: { "error": { "code", "message" } }.

Otros

Preguntas frecuentes

¿Dominio no encontrado, es un error?

No. Para un dominio que no está en el índice de enlaces se devuelven 200 y found: false. En ese caso, subdomains y referring_domains son null. En cambio, una entrada no válida (texto que no es un dominio) devuelve 400 invalid_domain.

¿Puedo enviar una URL?

Sí. El parámetro domain acepta un dominio o una URL. https://www.example.com/page se convierte en example.com en la respuesta. Lo mismo se aplica a bulk y compare.

¿Por qué el número de dominios de referencia a veces es null?

referring_domains es null si el dominio no está en el grafo de enlaces o si el grafo no puede responder en ese momento. backlinks devuelve 503 graph_unavailable mientras el grafo no está listo.

¿La puntuación es aproximada o basada en datos?

Consulta el campo score_source. Si es data, la puntuación se calculó a partir de datos medidos de enlaces y tráfico; el panel la muestra con la insignia basada en datos y un punto relleno. standard y calibrated son puntuaciones aproximadas; el panel les asigna la insignia aproximada y un punto vacío. Cuando están presentes, score_low y score_high indican el intervalo esperado de la puntuación, y el panel dibuja ese intervalo como un arco en el indicador. Si ambos son null, no se informa ningún intervalo; no significa un intervalo de ancho cero.

¿Por qué el número de referencias del panel puede ser distinto del de la API?

referring_domains es siempre el número de dominios de referencia contados en el índice de enlaces, y el endpoint backlinks lista esos dominios por nombre. El panel muestra una sola cifra en el encabezado: la de los datos de búsqueda si se han abierto para el dominio y, si no, la del índice de enlaces. Cuando la cifra de los datos de búsqueda está en el encabezado, la del índice de enlaces aparece en el detalle bajo la tarjeta, como la cifra que “podemos listar por nombre”. Las dos cifras se miden con métodos distintos y ninguna desmiente a la otra.

¿Por qué la auditoría de spam puede ser tan lenta?

En la primera consulta se leen los datos de archivo, de rastreo y de la página activa del dominio, lo que puede tardar hasta 25 segundos. El resultado se guarda en caché durante 24 horas (cached: true). Configura el tiempo de espera del cliente en al menos 30 segundos. fresh=1 omite la caché y vuelve a rastrear.

¿Puedo llamarla desde el navegador, desde mi propio sitio?

No. La API no envía el encabezado CORS y rechaza las solicitudes del navegador que llegan desde otros sitios. Poner tu clave en el código del navegador tampoco sería seguro; haz la llamada desde tu propio servidor. El panel Probar de esta página es la excepción, porque se ejecuta desde la misma dirección.

Perdí mi clave.

La clave no se puede recuperar; solo se guarda su hash. Crea una clave nueva, actualiza tu script y revoca la anterior.

¿Cómo veo mi límite?

GET /api/v1/usage devuelve el número total de solicitudes de tu clave y el estado de la ventana de un minuto actual. En modo cuenta, los encabezados X-Quota-* de las respuestas correctas muestran lo que queda de la última cuota contabilizada; los detalles están en la página de tu cuenta.

¿En qué zona horaria están las marcas de tiempo?

Los campos de fecha de las respuestas están en UTC (como 2026-11-10T09:40:36.000Z). Las cuotas diarias y mensuales se renuevan según la hora de Turquía (UTC+3).