FixWeb

// docs / rest api

REST API

Bearer-authenticated JSON API for passive scan automation, scan status, and findings. Cursor-paginated, rate-limited, and shipped with a machine-readable OpenAPI spec for client codegen. Active scans stay in the dashboard UI for ownership attestation.

احراز هویت

هر request باید bearer token را در header Authorization داشته باشد. Tokenها از Account → API tokens صادر می‌شوند؛ plaintext دقیقا یک بار هنگام creation به شما نمایش داده می‌شود. Revoking یک token در call بعدی 401 برمی‌گرداند.

bash
curl -H "Authorization: Bearer fxw_..." \
  https://fixweb.app/api/v1/scans

فرمت token: fxw_ و بعد ۴۳ کاراکتر base64url. در حالت at rest به‌صورت hash با SHA-256 ذخیره می‌شود؛ plaintext هرگز سمت سرور persist نمی‌شود.

Rate limitها

دو window روی هر request احرازشده: burst با ۱۰ req/sec و steady با ۶۰ req/min، هر دو keyed روی bearer hash. اجرای quota (سقف اسکن ماهانه) روی آن قرار می‌گیرد؛ سهمیه‌ها و محدودیت‌ها را ببینید.

صفحه‌بندی

Endpointهای list (/api/v1/scans، /api/v1/findings) از صفحه‌بندی cursor-based استفاده می‌کنند که روی (created_at, id) به ترتیب نزولی keyed شده است. ?cursor=<next_cursor> را بفرستید تا صفحه بعد را fetch کنید. cursor زیر writeهای همزمان درست می‌ماند (بدون OFFSET skew).

شکل خطاها

هر error یک JSON object است که حداقل یک key به نام error دارد.

jsonc
{ "error": "invalid_token" }                              // 401
{ "error": "forbidden" }                                  // 403
{ "error": "not_found" }                                  // 404
{ "error": "quota_exceeded", "quota": {...} }             // 429
{ "error": "rate_limited", "retry_after_seconds": 47 }    // 429
{ "error": "invalid_input", "issues": [...] }             // 400

Endpointها

شروع یک اسکن

POST/api/v1/scans

Enqueues a passive scan. Returns immediately with a queued scan id; poll GET /api/v1/scans/[scanId] until status === "completed". Owner-depth mode is not exposed — see Scan types for the attestation-flow rationale.

curl -X POST https://fixweb.app/api/v1/scans \
  -H "Authorization: Bearer fxw_..." \
  -H "content-type: application/json" \
  -d '{"target":"https://staging.example.com"}'

// 200 response

{
  "id": "8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d",
  "status": "queued",
  "target": "https://staging.example.com",
  "mode": "passive"
}

فهرست اسکن‌های شما

GET/api/v1/scans

اسکن‌های org متصل به token فراخوان را برمی‌گرداند، تازه‌ترین‌ها اول. با ?cursor= صفحه‌بندی کنید. limit پیش‌فرض 50، حداکثر 100.

curl -H "Authorization: Bearer fxw_..." \
  "https://fixweb.app/api/v1/scans?limit=25"

// 200 response

{
  "scans": [
    {
      "id": "8f1c4e2a-...",
      "target_url": "https://staging.example.com",
      "target_hostname": "staging.example.com",
      "mode": "passive",
      "status": "completed",
      "started_at": "2026-05-07T14:00:00Z",
      "completed_at": "2026-05-07T14:00:23Z",
      "findings_count": { "critical": 1, "high": 3, "medium": 7, "low": 2, "info": 4 },
      "triggered_by": "api",
      "created_at": "2026-05-07T14:00:00Z"
    }
  ],
  "next_cursor": "2026-05-07T14:00:00Z:8f1c4e2a-..."
}

دریافت یک اسکن

GET/api/v1/scans/{scanId}

به‌صورت پیش‌فرض scan envelope + خلاصه severity برای هر category را برمی‌گرداند. ?include_findings=true را بفرستید تا report کامل را بگیرید (برای scanهای پرسر و صدا بزرگ است؛ بهتر است endpoint findings را با filter استفاده کنید).

curl -H "Authorization: Bearer fxw_..." \
  https://fixweb.app/api/v1/scans/8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d

فهرست findings

GET/api/v1/findings

Filterable findings list across every scan in the caller's org. Filters: severity=critical,high, check_id=performance.delivery, since=2026-04-01T00:00:00Z. Cursor-paginated.

curl -H "Authorization: Bearer fxw_..." \
  "https://fixweb.app/api/v1/findings?severity=critical,high&limit=50"

// 200 response

{
  "findings": [
    {
      "id": "...",
      "scan_id": "...",
      "check_id": "secrets.js-bundle-sweep",
      "severity": "critical",
      "title": "Supabase service role key exposed in JS bundle",
      "description": "...",
      "evidence": { ... },
      "remediation": "...",
      "cwe_id": "CWE-798",
      "created_at": "2026-05-07T14:00:23Z"
    }
  ],
  "next_cursor": null
}

OpenAPI spec

Spec خوانا برای ماشین در /docs/api/openapi (text/yaml). برای clientهای typed آن را در codegen محبوب خود بگذارید (openapi-typescript، openapi-python-client، یا هر toolchain OpenAPI 3.1).

REST API — Docs · FixWeb