API REST v1

Autenticación

Cree una clave en Panel, claves de API (se requiere cuenta gratuita, 10 claves activas como máximo) y envíela como token Bearer. Una clave se muestra una sola vez al crearla y se almacena como hash. Cada clave tiene un límite por minuto; superarlo devuelve 429.

Authorization: Bearer sk_sc_...

POST /api/v1/assess

Alcance: assess. Sin answers, devuelve el banco de preguntas de los dominios solicitados. Con answers, devuelve puntuaciones, calificaciones, desglose por categoría, recomendaciones de experto y leyes aplicables.

curl -X POST https://structureclerk.ca/api/v1/assess \
  -H "Authorization: Bearer sk_sc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["data_protection", "cybersecurity"],
    "jurisdictions": ["CA_QC", "EU"],
    "answers": {
      "data_protection": { "dp_1": true, "dp_2": "partial" }
    }
  }'

{
  "overallScore": 62,
  "grade": "B-",
  "domains": {
    "data_protection": {
      "score": 62,
      "answeredQuestions": 2,
      "categoryScores": { "...": { "percentage": 50 } },
      "topRecommendations": [
        {
          "questionId": "dp_2",
          "title": "…",
          "advice": "…",
          "quickWin": "…",
          "effort": "medium",
          "impact": "high",
          "timeline": "30 jours"
        }
      ]
    }
  },
  "applicableLaws": [
    { "jurisdiction": "Québec", "law": "Loi 25", "domain": "data_protection" }
  ]
}

POST /api/v1/scan

Alcance: scan. Análisis pasivo de cumplimiento de un sitio: HTTPS, detección de política de privacidad, aviso de cookies, cabeceras de seguridad HTTP, datos de contacto. Solo páginas públicas, sin intrusión, sin pruebas activas.

curl -X POST https://structureclerk.ca/api/v1/scan \
  -H "Authorization: Bearer sk_sc_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.example.com" }'

{
  "url": "https://www.example.com",
  "overallScore": 75,
  "checks": {
    "https": { "passed": true, "details": "…" },
    "privacyPolicy": { "found": true, "url": "…", "details": "…" },
    "cookieBanner": { "detected": false, "details": "…" },
    "securityHeaders": { "score": 57, "headers": { "…": {} }, "details": "…" },
    "contactInfo": { "found": true, "details": "…" }
  },
  "recommendations": ["…"]
}

Gestión de claves

Puntos de entrada autenticados por sesión (navegador), detrás de la interfaz del panel:

• GET /api/v1/keys · listar sus claves (solo prefijos)
• POST /api/v1/keys · crear una clave ({ "name": "...", "scopes": ["assess","scan","authority"] })
• DELETE /api/v1/keys/:id · desactivar una clave

Puntos de entrada gratuitos

Públicos, sin clave, sin crédito. Se publicaron sin documentarse aquí, lo que equivale a no haberlos publicado.

• GET /api/v1/pricing · la tarifa en vivo: coste en créditos por punto de entrada, recargas, franquicia diaria. Legible por máquina, y la fuente que lee esta documentación.
• GET /api/v1/authority/verify/:evidence_id · verificar la firma Ed25519 de una decisión. Gratuito y sin cuenta, de forma permanente.
• GET /api/v1/authority/verify/anchors · los anclajes publicados del registro encadenado de decisiones, para comprobación por terceros.
• GET /api/v1/authority/stats · recuentos agregados de decisiones. Sin contenido de decisión, sin identificadores.

Créditos y franquicia gratuita

Los puntos de entrada de pago se miden en créditos prepagados, consumiendo primero la franquicia diaria. Los rechazos siguientes son los que recibirá realmente; el orden completo de resolución, los precios y las cabeceras de respuesta están en la página de Facturación.

Errores