API REST

La API REST de CrunchJunkie te da acceso programático y de solo lectura a los mismos datos que exponen la aplicación y el conector MCP (tus clientes, informes y sus datos en vivo, y las métricas de visibilidad en IA) mediante HTTPS sencillo con respuestas JSON. Está pensada para servidores, tareas cron, almacenes de datos y herramientas no-code como Zapier o Make: en cualquier lugar donde quieras tus cifras de CrunchJunkie sin que nadie navegue por el dashboard. Dos cosas se cumplen por diseño. Es de solo lectura: todos los endpoints de v1 consultan, ninguno escribe, así que una clave filtrada nunca puede cambiar ni eliminar nada ni gastar presupuesto. Y está limitada a tu equipo: una clave pertenece a exactamente un espacio de trabajo y solo devuelve los datos de ese espacio de trabajo. La API está disponible en los planes Pro, Agency y Scale. (El conector MCP está en todos los planes de pago.)

Abre Ajustes → API. Solo un propietario o administrador del espacio de trabajo puede crear o revocar claves: una clave puede leer todo el espacio de trabajo, así que no es una acción de nivel miembro. Ponle un nombre a la clave (p. ej. «Zapier production») y haz clic en Crear. La clave completa, con un aspecto como cj_live_ab12cd34.xxxx…, se muestra exactamente una vez. Cópiala y guárdala en un lugar seguro (un gestor de secretos, el campo de credenciales de tu herramienta); solo conservamos un hash, así que no podemos volver a mostrártela. Si la pierdes, revócala y crea una nueva. Revocar es instantáneo: haz clic en Revocar en una clave y cualquier integración que la use deja de funcionar en su siguiente solicitud. Las claves no caducan por sí solas salvo que fijes una caducidad. Una clave pertenece al espacio de trabajo, pero cuando un miembro se marcha, las claves que creó en él se revocan con él: cuando lo eliminas en Ajustes → Equipo (la eliminación pregunta primero e indica cuántas son) y cuando elimina su propia cuenta (su confirmación indica cuántas). Las claves siguen apareciendo aquí como revocadas.

La URL base es https://app.crunchjunkie.io/api/v1. Envía tu clave como token bearer en la cabecera Authorization: curl -H "Authorization: Bearer cj_live_ab12cd34.xxxx…" https://app.crunchjunkie.io/api/v1/clients Toda respuesta es JSON. Un éxito tiene este aspecto: { "data": … , "meta": { … } }; un error tiene este: { "error": { "code": "…", "message": "…" } }, con el estado HTTP correspondiente (401 sin autenticar, 403 ámbito o plan incorrectos, 404 no encontrado, 429 límite de frecuencia superado, 500 error del servidor).

v1 es de solo lectura y refleja las herramientas de lectura de MCP, de modo que las cifras coinciden exactamente con las de la aplicación: • GET /api/v1/clients: tus clientes, sus proveedores conectados y el número de informes. • GET /api/v1/reports?clientId=…: tus informes (los ids para las llamadas siguientes). Los informes en Eliminados se dejan fuera; añade includeDeleted=true para listarlos también, marcados con deleted: true. • GET /api/v1/reports/{id}: la definición de un informe (widgets, configuración de fechas). • GET /api/v1/reports/{id}/data?datePreset=…&comparePreset=…: los datos ensamblados en vivo del informe (KPI, gráficos, tablas). Un preajuste se resuelve en la zona horaria del espacio de trabajo, como en la aplicación, y la respuesta incluye el dateRange resuelto. Añade brandFilter=branded o brandFilter=nonbranded para leer sus widgets de Search Console, y todos los demás widgets que cuentan consultas de búsqueda o palabras clave, solo para ese grupo. • GET /api/v1/ai-visibility/projects?clientId=…: tus proyectos de visibilidad en IA. • GET /api/v1/ai-visibility/projects/{id}/metrics?dateFrom=…&dateTo=…&model=…&market=…&source=…&limit=…&offset=…: métricas de visibilidad en IA sobre días UTC completos (por defecto los últimos 30, como máximo 180): cada marca agrupada sobre todas las respuestas (respuestas que la nombran ÷ respuestas, con las respuestas como n y el margen ±), el cliente por motor, y las filas de instantánea que hay detrás, cada una con su etiqueta de motor y su fuente. El sentimiento va de 0 a 100 con 50 neutro, y la posición 1 significa nombrado en primer lugar; ambos son null, con avgPositionMentions / sentimentMentions y un motivo, cuando menos de 10 menciones los respaldan; meta.note indica la regla de agrupación. Una llamada devuelve como máximo 5.000 filas de instantánea (limit, de 1 a 5.000; 500 si se omite); pagina con offset hasta tener meta.total filas. • GET /api/v1/ai-visibility/projects/{id}/prompts?days=…&activeOnly=…&q=…: los prompts monitorizados, cada uno con su visibilidad agrupada sobre sus respuestas en la ventana y las respuestas como n. activeOnly=true (el valor por defecto) lista los prompts que preguntan los escaneos; activeOnly=false añade los prompts en pausa, marcados con active: false, cuyas respuestas almacenadas se conservan. La API nunca cambia un prompt. Un prompt eliminado en la aplicación o mediante el conector MCP desaparece con todas las respuestas almacenadas para él, así que esta lista ya no lo incluye, tampoco para periodos pasados. En /reports/{id}/data, el prev de una métrica de KPI es el valor del periodo de comparación. Es null cuando no hay nada con lo que comparar: ningún periodo de comparación, ningún dato anterior para esa métrica, un periodo de comparación que no se pudo leer de la fuente, o una cifra que solo existe tal como está hoy (recuentos de catálogo, totales de reseñas, totales de seguidores). Es un número, 0 incluido, cuando el periodo de comparación se midió: 0 es un 0 anterior real, desde el cual no hay cambio porcentual. Todo widget de KPI lleva prevNull: true; meta.note dice lo mismo. El value de una métrica de KPI es null cuando no hay cifra: la lectura falló, o el valor no se puede calcular (por ejemplo, coste por conversión con 0 conversiones). Nunca representa un 0. Un gráfico de Search Console o de Rank Tracking en /reports/{id}/data puede llevar googleUpdates: las actualizaciones del ranking de Google que se desplegaron durante sus fechas, tomadas del Search Status Dashboard de Google (nombre, enlace, inicio y fin como días del Pacífico de EE. UU., con fin null mientras sigue desplegándose). Muestran solo el momento, no una causa, y meta.googleUpdates lo repite siempre que un gráfico las lleva. Un donut de Google Ads por dispositivo o red de una tasa, una cuota o un promedio (CTR, CPC, cuota de impresiones, coste por conversión, ROAS) no tiene porciones en /reports/{id}/data ni en el get_report_data de MCP: su emptyReason es "gads_not_summable", ya que una cifra así por dispositivo no es parte de un total. Un mapa de Google Ads de una métrica así lleva notSummable: true, y las cifras de sus países son la tasa propia de cada país, nunca cuotas que sumar. meta.gadsNotSummable lo indica para un donut así y meta.geoNotSummable para un mapa de cualquier fuente (también un mapa de Usuarios o de una tasa de Google Analytics), y el aiNote del widget nombra la métrica. Un donut de cualquier otra fuente funciona igual desde la 3.187: una tasa, un promedio, un ratio, el alcance o los usuarios únicos (CTR, ROAS, porcentaje de rebote, posición media, usuarios, visitantes) no tiene porciones y su emptyReason es "not_summable", y meta.donutNotSummable lo indica. Un donut de un recuento o un importe conserva sus 9 porciones más grandes y un «Otros» con el resto, de modo que sus porciones suman todas las filas que devolvió la fuente (Google Analytics devuelve hasta 10.000 filas, Matomo y Piwik PRO hasta 1.000; las filas posteriores no están en ninguna porción). Los nombres de las columnas de las tablas (cols) siguen siendo ids en inglés; las celdas mostradas se escriben en el idioma del informe, tal como las imprime el informe: desde el 14 de octubre de 2026 eso incluye las celdas Tipo y Fuente de la tabla de URL citadas y las celdas Problema de la tabla de estado de las fuentes (antes en inglés), tanto en /reports/{id}/data como en el get_report_data de MCP. Un widget de fuentes o citas de visibilidad en IA en /reports/{id}/data (y en el get_report_data de MCP) que dejó fuera respuestas cuyas URL proceden de la memoria del modelo, no de una búsqueda, indica cuántas: memoryExcluded en una tabla, donut o gráfico, fromMemory en cada métrica de KPI afectada. Esas respuestas no están ni en el numerador ni en el denominador; los endpoints de citas y de carencias de contenido informan del mismo recuento como answersFromMemoryExcluded. Cualquier tabla de visibilidad en IA con comparación también puede llevar withinMargin, las celdas [fila, columna] cuyo cambio no es al menos el doble de su margen de error: en una tabla de Marca, la comparación de una celda; en una tabla de Prompts, su celda Δ Visibilidad; en una tabla de etiquetas, sus columnas Δ y el cambio bajo un valor. El informe las imprime en gris con «~», así que lee ese cambio como sin variación: lee este campo en lugar del «~» del texto. La especificación OpenAPI 3.1 legible por máquina se publica en https://app.crunchjunkie.io/api/v1/openapi.json: impórtala en Postman, Insomnia o el generador de código que prefieras.

Cada clave tiene un límite de frecuencia de tipo token bucket; si lo superas recibes un 429 con una cabecera Retry-After que te indica cuántos segundos esperar. Las colecciones grandes devuelven las filas más recientes con un meta.total y un indicador meta.truncated, de modo que una página recortada nunca se hace pasar por el conjunto completo: acota por fecha o modelo para llegar a datos más antiguos. Una nota de precisión que importa si calculas tus propios agregados: las métricas de visibilidad en IA siguen el contrato de métricas: agrupa una tasa sumando los recuentos y las ejecuciones y dividiendo una sola vez (Σ visibilityCount ÷ Σ totalRuns), nunca promediando porcentajes por fila, y mantén cada mercado (locale) como su propia población. La aplicación lo hace por ti; haz lo mismo después y tus cifras coincidirán con las nuestras.