Documentación de la API

Pruébala primero, sin clave

Un endpoint responde sin clave y sin cuenta. Pégalo en una terminal antes de leer cualquier otra cosa:

curl https://honesthook.com/api/v1/nichos

Una respuesta real, medida el 7 de septiembre de 2026:

{"niches":[
  {"id":"ai-agents","label":"AI agents",
   "windows_24h":24,"last_window":"2026-09-07T18:00:00+00:00"},
  {"id":"devtools","label":"Developer tools",
   "windows_24h":24,"last_window":"2026-09-07T18:00:00+00:00"},
  {"id":"indie-saas","label":"Indie SaaS",
   "windows_24h":23,"last_window":"2026-09-07T18:00:00+00:00"}
]}

Eso son metadatos de descubrimiento, no el archivo: qué nichos existen, y cuántas capturas por hora tiene ya cada uno. Te dice que el archivo es real y hasta dónde llega — no devuelve una línea de él. Leer lo que está dentro del archivo necesita una clave, y esa es la siguiente sección.

Consigue una clave

Gratis mientras el archivo es joven: 1000 créditos gratis al mes — sin tarjeta y sin llamada comercial. La franquicia se renueva el día 1; los créditos que compras no caducan.

La unidad es el crédito, no la llamada, y los endpoints cuestan cantidades distintas. La franquicia mensual compra 1000 llamadas a archive/trends (1 crédito cada una) o 100 a archive/movers (10 cada una) — o cualquier mezcla. archive/coverage no cuesta nada.

¿Con prisa? El inicio rápido es una sola pantalla: la clave, un comando con tu clave ya dentro, y la respuesta que deberías recibir.

¿Prefieres la terminal? El registro también es un endpoint — no hace falta navegador:

curl -X POST https://honesthook.com/api/v1/chaves \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com"}'

La clave se devuelve una vez y nunca más: la base de datos guarda solo su SHA-256. Si la pierdes, escribe a contato@honesthook.com y la rotamos a mano. Una reemisión automática permitiría que cualquiera te tumbara la clave escribiendo tu dirección.

Autenticación

Envía la clave como bearer token. Toda petición al archivo la necesita; el descubrimiento no.

curl https://honesthook.com/api/v1/trends/ai-agents \
  -H "Authorization: Bearer hk_live_..."

Endpoints

GET /api/v1/nichos — qué existe, y desde cuándo

No necesita clave. Devuelve los nichos y cuánto histórico tiene cada uno — nunca una línea del archivo en sí. Hoy: AI agents, Developer tools, Indie SaaS.

GET /api/v1/trends/{niche} — el archivo

Necesita clave. Devuelve el histórico de un nicho agrupado por elemento, no por ventana. Una ventana es cómo el archivo guarda; un elemento con su serie es cómo se hace la pregunta.

GET /api/v1/movers/{niche} — qué ganó tracción

Necesita clave. /trends responde qué está en el ranking. Este responde qué ganó tracción desde ayer — una pregunta que solo puedes responder si guardaste el ayer. Cuesta 10 créditos, y solo cobra si encuentra movimiento.

curl "https://honesthook.com/api/v1/movers/ai-agents?hours=24&limit=20" \
  -H "Authorization: Bearer hk_live_..."

Con movimiento:

{
  "niche": "ai-agents",
  "total": 2,
  "interval_min": 1208,
  "credits_charged": 10,
  "credits_balance": 990,
  "items": [
    {
      "external_id": "49569136",
      "title": "Show HN: Sageling - a local AI agent for Mac",
      "url": "https://sageling.ai/",
      "points": 7,
      "points_gained": 1,
      "comments": 1,
      "position": 2
    }
  ]
}

Sin movimiento — sigue siendo un 200, y es gratis:

{
  "niche": "ai-agents",
  "items": [],
  "total": 0,
  "interval_min": null,
  "credits_charged": 0,
  "credits_balance": 1000,
  "note": "nothing gained traction in this window -- not charged"
}

Las dos son respuestas correctas. Ramifica sobre total, no sobre el código de estado. «Miré y no había nada» es una respuesta legítima, y no deberías tener que pagarla — que es exactamente por lo que no deberías construir lógica para evitar llamar.

GET /api/v1/{platform}/posts — publicaciones recientes

Necesita clave, 1 crédito, y no cobra cuando no encuentra nada.

curl "https://honesthook.com/api/v1/bluesky/posts?handle=bsky.app&limit=5" \
  -H "Authorization: Bearer hk_live_..."

Cada elemento lleva id, url, text, published_at y un objeto metrics con likes, replies, reposts y quotes.

Un limit fuera del rango se rechaza con 400, no se recorta en silencio. Las fuentes recortan sin avisar, y alguien que pidiera 100 publicaciones recibiría 40 y concluiría que la cuenta tiene 40.

Los handles de Mastodon son siempre usuario@instancia. La red está federada, así que un nombre a secas no identifica a nadie. Los elementos de Mastodon también llevan text_html junto al text ya limpio — ese campo es HTML de terceros y hay que sanearlo antes de que llegue a una página, o tienes un agujero de XSS.

Lo que este endpoint no devuelve

• Ni comentarios ni respuestas de otras personas. Solo lo que publicó esta cuenta.
• Ninguna publicación más allá de lo que sirve la página pública. has_more no es una sola respuesta para las tres. bluesky lo calcula del cursor que devuelve la fuente, así que puede ser true. mastodon es false hoy porque todavía no leemos la cabecera Link que nos lo diría. threads es null: sus publicaciones llegan dentro del documento de perfil, no hay nada que paginar, y no sabemos cuántas quedaron fuera. Un null es nosotros diciendo que no sabemos — nunca «no hay más».
• Ningún recuento de visualizaciones, en ninguna. Ninguna de las tres fuentes publica uno en la superficie pública, así que no hay campo para él. Una métrica ausente es null, nunca 0.
• Solo métricas que medimos de verdad. Threads no tiene recuento de citas, así que metrics.quotes es null ahí — y el reshare_count y el media_type de Threads se quedan fuera porque solo aparecieron en parte de la muestra. El bookmarkCount de Bluesky se queda fuera porque solo Bluesky lo tiene, y un campo que existe en una plataforma de diez no es una forma contra la que puedas programar.

Threads lee las publicaciones del mismo tipo de documento que lee threads/profile — pero descarga ese documento otra vez. Llamar a los dos para el mismo handle descarga dos veces. Medido el 15 de septiembre de 2026: las publicaciones justo después del perfil tardaron 1,55 s con cached: false, contra 1,60 s para las publicaciones sin llamada de perfil antes. Idénticos, así que no se reutilizó nada. Cachear por documento en lugar de por endpoint lo arreglaría, y no se ha hecho.

POST /api/v1/chaves — emitir una clave

Recibe {"email": "..."}, devuelve 201 con la clave en texto plano, una vez. Una clave activa por dirección; una segunda petición devuelve 409, sin repetir nada sobre la clave que ya existe.

GET /api/v1/account — tu propio consumo

curl "https://honesthook.com/api/v1/account" \
  -H "Authorization: Bearer hk_live_..."

{
  "success": true,
  "endpoint": "account",
  "data": {
    "key_prefix": "hk_live_f2e3febc",
    "key_created_at": "2026-09-15T14:15:47.683Z",
    "cycle_started_at": "2026-09-01T00:00:00.000Z",
    "credits_spent_this_cycle": 1,
    "credits_spent_by_endpoint": { "github/profile": 1 }
  },
  "credits_used": 0,
  "credits_remaining": 999,
  "credits_purchased_remaining": 0,
  "free_credits_remaining": 999,
  "free_credits_total": 1000,
  "free_credits_reset_at": "2026-10-01T00:00:00.000Z"
}

El ciclo es el mes natural en UTC — la misma ventana que usa el código de cobro, así que cycle_started_at y free_credits_reset_at no pueden desviarse de aquello por lo que de verdad te facturan.

credits_spent_by_endpoint solo lista endpoints que cobraron. Una llamada que no costó nada no es gasto, y un 0 en ese mapa sugeriría un cargo que nunca ocurrió. Una clave que todavía no ha gastado recibe {}, con 200 — eso es una respuesta, no un error.

La respuesta lleva el prefijo de la clave, nunca la clave. El prefijo son los mismos 16 caracteres que guardamos en texto plano de nuestro lado; no autoriza nada por sí solo.

Cuánto cuesta cada llamada

Los créditos se debitan dentro de la misma transacción de base de datos que lee el archivo — no por esta ruta, y no después. Algunos endpoints no cobran nada cuando no encuentran nada; la tabla dice cuáles.

Toda respuesta de pago lleva credits_charged (lo que esta llamada costó de verdad) y credits_balance (lo que queda). Lee credits_charged en lugar de suponer que se cobró el precio de lista — en una llamada a movers sin resultados es 0.

Cuánto te queda

Los endpoints de perfil (/api/v1/<platform>/profile) responden con cinco campos de crédito, porque hay dos carteras y se comportan de forma distinta.

"credits_used": 1,
"credits_remaining": 999,             // what you can spend right now
"credits_purchased_remaining": 0,     // bought credits — never expire
"free_credits_remaining": 999,        // this month's allowance
"free_credits_total": 1000,
"free_credits_reset_at": "2026-10-01T00:00:00.000Z"

credits_remaining es el único que responde «¿puedo volver a llamar?» — es la suma. Las dos parcelas de debajo existen porque la franquicia se reinicia el día 1 y los créditos comprados no, así que un número único bajaría por su cuenta al cambiar el mes. free_credits_reset_at dice exactamente cuándo, en UTC.

Un campo que no pudimos calcular vuelve como null, nunca como 0. El cero es un hecho sobre tu cuenta; null es un hecho sobre nuestra lectura de ella.

Qué vuelve

{
  "niche": "ai-agents",
  "from": "2026-08-30T00:00:00Z",
  "to":   "2026-09-06T16:00:00Z",
  "points": 412,
  "truncated": false,
  "credits_charged": 1,
  "paid_from": "free",
  "free_used": 3,
  "free_total": 1000,
  "credits_balance": 0,
  "items": [
    {
      "external_id": "44912730",
      "title": "...",
      "url": "https://...",
      "platform": "hackernews",
      "entered_at": "2026-09-05T14:00:00Z",
      "left_at":   "2026-09-06T15:00:00Z",
      "best_position": 3,
      "movement": 9,
      "series": [
        { "window": "2026-09-05T14:00:00Z", "position": 12, "points": 41 },
        { "window": "2026-09-05T15:00:00Z", "position": 3,  "points": 96 }
      ]
    }
  ]
}

movement es la posición más antigua menos la más reciente: positivo significa que subió.

truncated: true significa que había más — no que algo falló. Dos cosas lo disparan: el tope de 5.000 puntos, y el limit que enviaste tú. Si pediste limit=3 y recibiste truncated: true con points: 3, ese es el parámetro haciendo su trabajo — quítalo y obtienes la ventana completa. Solo cuando no fijaste limit significa truncated el tope, y solo entonces ayuda estrechar el intervalo.

Qué campos obtienes de verdad

Toda respuesta de perfil lleva las mismas doce claves, en todas las plataformas. Una clave nunca desaparece porque la plataforma no la tenga — vuelve como null. Eso es justamente el punto: tu código lee la misma forma en todas partes, y un null significa «no lo sabemos», nunca «cero».

Lo que sigue es cuáles de los cinco campos de métrica vienen de verdad rellenos, por plataforma. Medido el 2026-09-22. siempre quiere decir en toda respuesta; a veces quiere decir que hay una condición, detallada abajo; nunca quiere decir que devolvemos null a propósito, también explicado abajo.

instagram.posts_count depende del tamaño de la cuenta

El campo exacto que Instagram expuso en su día vuelve vacío, así que leemos el recuento de la descripción de la página. Por debajo del umbral dice 4,930 Posts y te damos 4930. Por encima, la página solo dice 60.4K Posts — y 60.4K es cualquier cosa entre 60.350 y 60.449. Devolver 60400 sería inventar una precisión que la fuente nunca nos dio, así que devolvemos null. Si necesitas un orden de magnitud para cuentas grandes, este campo no te lo va a dar, y preferimos que lo sepas antes que darte un número plausible y equivocado.

Todos los demás campos de Instagram — followers, following, verified, is_private — son exactos, en cuentas de cualquier tamaño.

metrics.quotes falta en threads/posts

Los endpoints de publicaciones devuelven un objeto metrics, y no es el mismo en las tres. bluesky/posts y mastodon/posts te dan likes, reposts, replies y quotes. threads/posts te da los tres primeros y ninguna clave quotes — la fuente no expone un recuento de citas.

Es el único sitio donde una clave está ausente en lugar de venir null, así que metrics.quotes se lee como undefined en Threads y como un número en las otras dos.

Campos que podríamos rellenar, y deliberadamente no rellenamos

La razón es la misma en todos los casos: el número de al lado responde a otra pregunta, y un campo relleno que significa otra cosa es peor que uno vacío. Un null lo ves; un número equivocado que parece correcto, no.

• github.posts_count — GitHub publica public_repos. Un repositorio no es una publicación. Rellenar esto haría que el archivo registrara «las publicaciones pasaron de 11 a 12» para un número que cuenta otra cosa, y nadie se daría cuenta, porque el campo estaría relleno y sería plausible.
• medium.posts_count — el número de un perfil de Medium es el recuento de historias cargadas en la primera pantalla; la página hace scroll infinito. Publicarlo diría «esta persona escribió 10 piezas» de alguien que escribió 300.
• medium.verified — el perfil trae verifications.isBookAuthor. Es el único campo con «verif» en el nombre, y dice algo completamente distinto: que la persona publicó un libro. Mapearlo haría que esta API afirmara un distintivo que Medium nunca otorgó.
• pinterest.verified — Pinterest tiene al menos tres distintivos distintos: domain_verified, is_verified_merchant, y un verified_identity en los tableros. Dominio confirmado, comerciante aprobado, identidad comprobada — elegir uno publicaría un distintivo que la plataforma no dio. null dice «no sabemos cuál»; false sería una afirmación.
• pinterest.following y pinterest.posts_count — los dos números existen en la página, pero también los contadores equivalentes de los tableros, y el equivocado se parece exactamente al correcto. Se rellenarán el día en que haya un anclaje lo bastante limpio para distinguirlos.
• mastodon.verified — Mastodon verifica enlaces y marca verified_at. Eso prueba que la persona controla un dominio, no que la plataforma haya confirmado quién es. Leerlo como verified: true publicaría un distintivo que Mastodon no emite.

Errores

Todo fallo lleva un código error estable. Ramifica sobre el código, no sobre la prosa.

402 y 429 significan cosas opuestas. 429 dice espera y reinténtalo — la cuota mensual de llamadas se renueva. 402 dice que esperar no va a ayudar: recarga créditos o sube el techo. Un cliente que trate el 402 como un límite de frecuencia construye un bucle de retroceso que nunca puede tener éxito.

Un 402 lleva la dirección consigo, para que tu propio manejador de errores pueda señalar a una persona la página correcta sin hardcodear una URL:

{
  "success": false,
  "error": {
    "type": "sem_creditos",
    "message": "no credits left on this key",
    "upgrade_url": "https://honesthook.com/login?next=%2Faccount"
  },
  "credits_used": 0
}

Va a la página de inicio de sesión porque comprar está ligado a una cuenta y a una clave verificada — el nivel gratuito nunca la necesita. El campo aparece solo en el 402; todos los demás errores lo dejan fuera.

Las lecturas correctas también llevan X-RateLimit-Limit y X-RateLimit-Remaining, para que puedas vigilar la cuota sin gastar una segunda llamada en ello.

Servir la última lectura cuando una plataforma nos bloquea

Un 451 significa que la plataforma rechazó nuestras direcciones — el perfil existe y tu clave está bien. Esos rechazos vienen en ventanas: una plataforma ha llegado a estar hasta 7 horas sin una lectura fresca, y vuelve por su cuenta.

Puedes optar por recibir la última lectura almacenada en lugar del error, con la cabecera estándar de RFC 5861:

curl -H "Authorization: Bearer $HH_KEY" \
  -H "Cache-Control: stale-if-error=86400" \
  "https://honesthook.com/api/v1/medium/profile?handle=markmanson"

Sin la cabecera no cambia nada: recibes el 451, como siempre. No te vamos a entregar datos viejos que no pediste.

Cuando aplica, la respuesta es 200 y lleva tres campos extra: stale: true, as_of — la hora real de la captura, nunca la hora de tu petición — y stale_age_seconds.

• No cuesta créditos. credits_used es 0: no obtuviste lo que pediste.
• 48 horas es un techo duro, y gana a tu petición. Medimos la deriva por hora en los recuentos de seguidores almacenados: a las 48 h la peor plataforma se mueve un 1,90 % en el percentil 95 — sigue siendo el mismo número. A los 7 días pasa del 5 % y deja de serlo. Pide menos de 48 h si quieres menos; pedir más te da el 451.
• La forma es más pequeña, y lo dice. Guardamos solo métricas — followers, following, posts_count, verified, is_private. Ni nombre, ni biografía, ni avatar, ni URL, nunca. fields_available lista cuáles de los cinco tenemos de verdad para ese handle, así que un null nunca es ambiguo entre «cero» y «nunca lo guardamos».
• Sin lectura almacenada no hay respuesta stale. Un handle que nunca hemos buscado recibe el 451, incluso con la cabecera. No convertimos la ausencia en dato.

Límites

Los cuatro se aplican dentro de Postgres, no en la capa HTTP. Es deliberado: la clave de base de datos del lado del navegador es pública, así que un límite que viviera en la ruta sería un límite que cualquiera podría rodear.

Lo que estos datos todavía no sostienen

Un archivo de tendencias que se halaga a sí mismo no vale nada, así que aquí está la parte que la mayoría de las documentaciones de API deja fuera.

La posición es más débil que los puntos, y antes del 2026-09-06 15:20 UTC no es fiable. Hasta ese momento el ranking se ordenaba solo por puntuación, y los elementos empatados caían en el orden que devolviera la búsqueda de origen — que varía entre llamadas. La mayoría de los elementos de una instantánea están a menos de tres puntos entre sí, así que los empates son la regla, no la excepción. En un par de ventanas medido, 19 de 29 elementos «cambiaron de posición» sin ganar ni perder un solo punto. El orden es determinista desde esa marca de tiempo en adelante. Para cualquier cosa anterior, lee points y trata position como decoración.

movers ordena por puntos ganados, no por posición — y eso es una corrección, no una preferencia. Medido el 2026-09-06 en 19 pares de ventanas: la posición cambió en 19 de 29 elementos sin que cambiara un solo punto. Eso era ruido de desempate entre elementos con la misma puntuación, no movimiento. points_gained es el contador propio de Hacker News, no un número que derivemos, así que no puede reordenarse por su cuenta. La respuesta sigue llevando position, como referencia — no ordenes por ella, y no la compares entre llamadas.

interval_min es el hueco real, y normalmente no es el que pediste. El endpoint compara la ventana más reciente contra la ventana archivada cuya hora real de captura está más cerca de hace hours — no «la ventana N posiciones atrás», porque las ventanas no son equidistantes. Los intervalos observados han ido de 12 a 321 minutos. Pide hours=24 a un archivo que tiene 20 horas de profundidad y obtienes interval_min: 1208, no 1440. Divide por el número que vuelve, nunca por el que enviaste.

Un nicho mal escrito es un éxito vacío, no un error — en los dos endpoints de archivo. Nada valida el nombre del nicho. En movers, un nicho que no existe devuelve el mismo 200 vacío y sin cobro que un nicho donde nada ganó puntos. En trends devuelve items: [] con points: 0 — y gasta igualmente una llamada de tu cuota mensual, porque el contador se incrementa antes de leer el archivo. Comprueba /api/v1/nichos en lugar de leer un resultado vacío como un hallazgo. Es la forma de fallo que este proyecto se sigue pillando a sí mismo: ningún error, y una respuesta que parece plausible.

Una ventana se redondea a la hora, y eso borra el intervalo real. Dos capturas separadas por 12 minutos y dos separadas por 96 parecen las dos «una ventana». El redondeo es lo que hace idempotente la recolección y se queda — pero una diferencia sin intervalo es un número sin unidad, así que lee las marcas de tiempo de series en lugar de suponer que pasó una hora.

Hoy hay una fuente en vivo: Hacker News. Reddit está escrito y esperando credenciales. Esto afecta de forma desigual según el nicho — Hacker News apenas habla de SaaS indie, así que ese nicho es escaso por cobertura, no por frecuencia. Mira la página de estado antes de construir sobre un nicho: publica la última captura y las últimas 24 horas por fuente, incluidas las fuentes que están rotas.

Legible por máquina

El spec completo está en /openapi.json (OpenAPI 3.1), y hay un /llms.txt para agentes. Si vas a apuntar un modelo a esta API, dale el spec en lugar de esta página.