REST API v1

身份认证

在控制台的 API 密钥中创建密钥（需免费账户，最多 10 个有效密钥），然后作为 Bearer 令牌发送。密钥仅在创建时显示一次，并以哈希形式存储。每个密钥都有每分钟速率限制；超出将返回 429。

Authorization: Bearer sk_sc_...

POST /api/v1/assess

作用域：assess。不带 answers 时，返回所请求领域的题库。带 answers 时，返回分数、等级、按类别的细分、专家建议和适用法律。

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

作用域：scan。网站合规的被动扫描：HTTPS、隐私政策检测、Cookie 横幅、HTTP 安全响应头、联系方式。仅限公开页面，不入侵，不做主动测试。

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": ["…"]
}

密钥管理

由会话（浏览器）身份认证的端点，支撑控制台界面：

• GET /api/v1/keys · 列出您的密钥（仅前缀）
• POST /api/v1/keys · 创建密钥 ({ "name": "...", "scopes": ["assess","scan","authority"] })
• DELETE /api/v1/keys/:id · 停用密钥

免费端点

公开、无需密钥、不计费。它们已经上线却从未在此记录，这等同于没有上线。

• GET /api/v1/pricing · 实时价目表：每个端点的额度成本、充值包、每日免费额度。机器可读，也是本文档读取的来源。
• GET /api/v1/authority/verify/:evidence_id · 验证某个决策的 Ed25519 签名。永久免费且无需账户。
• GET /api/v1/authority/verify/anchors · 链式决策日志的已发布锚点，供第三方核查。
• GET /api/v1/authority/stats · 决策数量的汇总。不含决策内容，不含标识符。

额度与免费配额

付费端点以预付额度计量，并优先消耗每日免费配额。下列拒绝即是您实际会收到的；完整的处理顺序、价格和响应头见计费页面。

错误