API, CLI y MCP

EMPIECE AQUÍ

Primera solicitud

# 1. Start the full audit: 202 with an id (a refusal is printed and ends the script)
curl -sS -X POST 'https://fukamo.com/api/v1/audits' \
  -H "Authorization: Bearer $FUKAMO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"urls": ["https://example.com/"]}' > start.json
ID=$(jq -r '.id // empty' start.json)
[ -n "$ID" ] || { cat start.json; exit 1; }

# 2. Poll every 5 seconds until it is complete (typically 1–4 minutes, at most 15)
for i in $(seq 180); do
  curl -sS "https://fukamo.com/api/v1/audits/$ID" -H "Authorization: Bearer $FUKAMO_API_KEY" > audit.json
  [ "$(jq -r .status audit.json)" = complete ] && break
  jq -e '.code and .code != "rate_limited"' audit.json > /dev/null && { cat audit.json; exit 1; }
  sleep 5
done

jq '.pages[0].result.score' audit.json

Datos de ejemplo. No se envía nada y no necesita una clave.

COMPROBAR LA CLAVE

Pruebe su clave de API

La clave solo va a nuestro servidor y no se guarda. La prueba no ejecuta ninguna auditoría ni gasta cuota.

Esta es la respuesta para una clave válida

HTTP/1.1 404 Not Found
{
  "error": "No such batch for this key.",
  "code": "not_found"
}

CÓMO FUNCIONA

Iniciar, consultar, recoger

Una auditoría dura minutos, así que la API devuelve un id al instante y usted recoge el resultado cuando está listo.

POST /api/v1/audits1. Inicie la auditoría
Envíe la URL. El servidor responde al instante con 202 y un id.
GET /api/v1/audits/{id}2. Consulte el estado
Cada 5 segundos hasta que status sea complete. No gasta cuota.
GET /api/v1/audits/{id}?format=pdf3. Recoja el resultado
pages[].result trae las puntuaciones y los hallazgos; ?format=pdf devuelve el PDF.

queueden espera en la cola

runningla auditoría está en curso, normalmente 1–4 minutos

completeel resultado está listo

Clave y límites

Envíe la clave en cada llamada: Authorization: Bearer fk_… o X-Api-Key. Nunca la ponga en una URL ni en JavaScript público.

Límite	Valor
Auditorías por clave	60 por hora de forma predeterminada
Una auditoría completa de una página	5 auditorías de la cuota: 12 auditorías completas por hora de forma predeterminada
Páginas de un sitio	1 al día por clave, salvo que el operador le dé más (hasta 50); la misma página se puede auditar de nuevo
Páginas en curso por clave	Como máximo 10 a la vez, en cola o en ejecución
Consultas de estado	120 por minuto, fuera de la cuota
Informes PDF	Una cuarta parte de la cuota, 15 por hora de forma predeterminada, aparte de las auditorías

Pida una clave en support@fukamo.com e indique para qué la usará.

POST /api/v1/audits

Envíe url. Opcionalmente añada query: la frase de búsqueda con la que se mide la página (una frase, máx. 32 palabras).

Sin query: usamos la primera sugerencia de palabra clave del sitio. Sus hallazgos llegan como review y no bajan la puntuación.
Con query: se evalúa igual que en el sitio web. Una página que apenas cubre la frase recibe un score.fukamo limitado.
locale: el idioma del informe — en (predeterminado), sk o es — para el JSON y el PDF.

curl -X POST "https://fukamo.com/api/v1/audits" \
  -H "Authorization: Bearer $FUKAMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/"], "query": "seo audit" }'

Recibe al instante 202 con id y statusUrl. La cuota solo se gasta cuando la página responde: una página inaccesible devuelve 502 unreachable y no cuesta nada.

{
  "version": 1,
  "id": "c547d6c0-15b5-4ba9-badc-c6fc392e0d7b",
  "status": "queued",
  "pages": 1,
  "queries": [
    { "url": "https://example.com/", "query": { "primary": "seo audit", "source": "input" } }
  ],
  "statusUrl": "/api/v1/audits/c547d6c0-15b5-4ba9-badc-c6fc392e0d7b"
}

curl "https://fukamo.com/api/v1/audits/<id>" -H "Authorization: Bearer $FUKAMO_API_KEY"

{
  "version": 1,
  "id": "c547d6c0-15b5-4ba9-badc-c6fc392e0d7b",
  "status": "complete",
  "createdAt": "2026-09-24T08:12:03.000Z",
  "queue": { "position": 0, "pagesAhead": 0, "etaSeconds": 0, "samples": 12 },
  "pages": [
    {
      "url": "https://example.com/",
      "status": "done",
      "result": {
        "version": 1,
        "url": "https://example.com/",
        "scannedAt": "2026-09-24T08:14:41.000Z",
        "score": {
          "seo": 71,
          "geo": 64,
          "fukamo": 68,
          "parts": { "content": 66, "google": 71, "ai": 64, "technical": 76,
            "experience": 61 },
          "html": 69
        },
        "summary": { "failed": 1, "review": 0, "extras": 0, "passed": 311,
          "notApplicable": 424, "unavailable": 6, "total": 742, "checksEvaluated": 760 },
        "findings": [
          { "id": "meta-description", "label": "Meta description is missing", "status": "fail",
            "level": "high", "category": "on-page",
            "evidence": "<head> does not contain <meta name=\"description\">",
            "fix": "Add a specific description of the page content." }
        ],
        "performance": {
          "mobile": { "performance": 0.62, "accessibility": 0.91, "seo": 1 },
          "desktop": { "performance": 0.88, "accessibility": 0.91, "seo": 1 }
        },
        "query": { "primary": "seo audit", "source": "input", "score": 62,
          "suggestions": ["seo audit", "website audit", "technical seo check"] },
        "unmeasured": ["JavaScript audit"],
        "reportUrl": "https://fukamo.com/?url=https%3A%2F%2Fexample.com%2F",
        "page": {
          "title": "Example — SEO audit", "description": "…", "language": "en",
          "canonical": "https://example.com/", "responseTimeMs": 312,
          "wordCount": { "main": 144, "total": 881, "pageType": "homepage" }
        }
      }
    }
  ],
  "site": { "addresses": 1, "uniquePages": 1, "meanScore": 68, "score": 68, "cappedBy": null,
    "issues": [] }
}

Campo	Significado
`score.fukamo`	La puntuación principal, como en el sitio web y en el PDF. Media ponderada de `score.parts`: el contenido pesa más y la puntuación no puede superarlo en más de 15 puntos.
`score.parts.content`	Contenido: extensión, estructura, coincidencia con la frase, actualidad y confianza. Los puntos se ganan, no solo se pierden.
`score.seo`, `score.geo`	Puntuaciones HTML de SEO y GEO.
`score.html`	Puntuación HTML general, con las mediciones.
`findings`	Solo `fail` y `review`, del peor al mejor.
`summary`	Los recuentos de la web, cada problema una vez: `failed`, `review`, `extras` (sugerencias técnicas), `passed`, `notApplicable` y `unavailable` suman `total`. `checksEvaluated` son todas las comprobaciones ejecutadas, antes de fusionar duplicados. Una regla del HTML y la misma auditoría de Lighthouse (por ejemplo `image-alt`) son una sola causa: si fallan ambas, `failed` las cuenta una vez.
`query`	La frase medida y su origen (`input`, `suggested`, `none`). `query.score` es la coincidencia, `query.suggestions` las sugerencias del sitio.
`page`	Título, descripción, idioma, canonical, `responseTimeMs`, `wordCount`.
`performance`	Lighthouse para móvil y escritorio, 0–1. Se omite si PageSpeed falló.
`unmeasured`	Lo que no terminó. Esa parte de la puntuación es `null`, nunca 0.
`result.url`	La dirección tras las redirecciones. `pages[].url` es la que usted envió.
`site.score`	La puntuación del sitio. Menor que `site.meanScore` cuando un problema de todo el sitio la limita (`site.cappedBy`).

Los textos están en inglés, también los hallazgos de la frase (query-*): una frase eslovaca se compara con reglas eslovacas y se describe en inglés. El contenido citado de la página conserva su idioma.
Use id, status y level para comparar: nunca se traducen.
Pueden aparecer campos nuevos. Los existentes solo cambian con una nueva version.

?format=pdf devuelve el mismo informe en PDF, en inglés.

Aún no ha terminado: 409 not_ready.
Límite: una cuarta parte de la cuota de la clave (15 por hora por defecto), aparte de las auditorías.
Por encima del límite: 429 con retryAfter en segundos.

curl -H "Authorization: Bearer $FUKAMO_API_KEY" \
  "https://fukamo.com/api/v1/audits/<id>?format=pdf" \
  -o report.pdf

Errores

Los errores son JSON con error y code. Decida según code, no según el texto.

429: espere retryAfter segundos.
502 / 503: reintente unas pocas veces con pausas crecientes.

HTTP	code	Cuándo
400	invalid_request	El cuerpo no es JSON con una lista `urls` no vacía de direcciones http(s) públicas.
400	invalid_query	`query` no es una cadena o tiene más de 32 palabras.
400	invalid_locale	`locale` no es `en`, `sk` ni `es`. Sin él, el informe está en inglés.
400	bad_format	`?format=` tiene un valor distinto de `json` o `pdf`.
400	bad_page	Con `?format=pdf`, `?page=` no es el índice de una página de esta auditoría.
401	unauthorized	Falta la clave o no es válida; la respuesta es deliberadamente la misma en ambos casos.
404	not_found	No existe ninguna auditoría con este id o pertenece a otra clave.
409	not_ready	Se pidió el PDF antes de que la página terminara; incluye `status`. Espere a `complete`.
410	use_async	El antiguo `GET /api/v1/audit` síncrono está retirado. Use `POST /api/v1/audits` y actualice `@fukamo/cli` y `@fukamo/mcp` a la versión 0.3.0 o posterior.
429	rate_limited	Se agotó la cuota, hay demasiados PDF, demasiados destinos inaccesibles (10 por hora) o se consultó el estado con demasiada frecuencia; `retryAfter` indica los segundos.
429	queue_full	La clave ya tiene 10 páginas en cola o en curso; `retryAfter` indica los segundos. Recoja primero sus resultados.
429	domain_limit	Esta clave ya auditó hoy tantas páginas de este sitio como puede (1 por defecto; el propietario puede ampliarlo en el panel); `availableUrl` es una página que puede volver a auditar, `pagesPerSite` su número diario.
502	report_failed	No se pudo generar el PDF; el resultado JSON sigue siendo válido.
502	unreachable	No se puede analizar el destino: no existe, rechaza la conexión o no es público. Incluye `host`.
503	unavailable	No se pudo poner la auditoría en cola por un fallo de nuestra parte; `retryAfter` indica los segundos.
503	not_configured	Este servidor no tiene ninguna clave emitida.

Postman

Todas las llamadas de esta página, listas para importar. En Postman: Import → ambos archivos → entorno “Fukamo — produkcia” → su clave en apiKey. Los archivos no contienen ninguna clave.

Descargar la colección ↓Descargar el entorno ↓

CLI — @fukamo/cli

export FUKAMO_API_KEY=fk_…          # from the environment, never as an argument
npx @fukamo/cli audit https://example.com/
npx @fukamo/cli audit https://example.com/ --query "seo audit" --json
npx @fukamo/cli audit https://example.com/ --pdf report.pdf

Ejecuta la auditoría completa y espera (1–4 minutos). Muestra la puntuación y los 10 peores hallazgos; --json muestra el result exacto.
--query fija la frase. --pdf report.pdf guarda el PDF.
Código de salida: 2 = comprobaciones fallidas, 0 = ninguna, 1 = la llamada falló. Así fukamo audit "$URL" && deploy funciona en CI.
Con --pdf el código es 0 en cuanto se escribe el archivo: en CI, decida con --json.
fukamo result <id> recoge una auditoría en curso sin iniciar otra.
Requiere Node 20+. FUKAMO_API_URL cambia el servidor.
Las versiones anteriores a 0.3.0 reciben 410 use_async: actualice.

MCP — @fukamo/mcp

audit_website(url, query?) ejecuta la auditoría y devuelve la puntuación y las comprobaciones fallidas, cada una con su reparación.
¿No termina en 45 s? Recibe el id y get_audit_result(audit_id) la espera sin coste.
fukamo_report_pdf(path, url | audit_id, query?) guarda el PDF.

{
  "mcpServers": {
    "fukamo": {
      "command": "npx",
      "args": ["-y", "@fukamo/mcp"],
      "env": { "FUKAMO_API_KEY": "fk_…" }
    }
  }
}

La clave va en env, nunca en un prompt.

Qué datos conservamos

Por auditoría, durante 90 días: nombre de la clave, hora, la dirección de la página auditada (sin “?…”), id, estado y duración. Nunca la clave, solo su huella.
El resultado queda en el servidor con su id. Por ahora no se elimina automáticamente.
Solo direcciones http(s) públicas; las redes internas se rechazan.