FixVibe

// docs / rest api

REST API

Bearer-authenticated JSON API for scan automation, scan status, and findings. Passive scans are available through REST; active scans are available for paid plans only after the domain is verified and explicitly authorized in the dashboard.

Xác thực

Mỗi request phải mang bearer token trong header Authorization. Token được cấp từ Account → API tokens; plaintext hiển thị cho bạn đúng một lần khi tạo. Thu hồi token sẽ trả 401 ở lần gọi tiếp theo.

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

Định dạng token: fxv_ theo sau bởi 43 ký tự base64url. Lưu khi nghỉ dưới dạng hash SHA-256; plaintext không bao giờ được lưu phía máy chủ.

Giới hạn tốc độ

Hai cửa sổ trên mọi request đã xác thực: burst 10 req/sec và steady 60 req/min, cả hai đều key theo bearer hash. Thực thi hạn mức (giới hạn số lần quét mỗi tháng) nằm chồng lên trên — xem Hạn mức & giới hạn.

Phân trang

Các endpoint danh sách (/api/v1/scans, /api/v1/findings) dùng phân trang dựa trên con trỏ, key theo (created_at, id) theo thứ tự giảm dần. Truyền ?cursor=<next_cursor> để lấy trang tiếp theo. Con trỏ vẫn chính xác khi có ghi đồng thời (không lệch OFFSET).

Dạng lỗi

Mọi lỗi là một object JSON có ít nhất 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

Bắt đầu quét

POST/api/v1/scans

Enqueues a passive scan by default. For verified domains with active authorization, paid plans can request active mode. Returns immediately with a queued scan id; poll GET /api/v1/scans/[scanId] until status === "completed".

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

// phản hồi 200

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

Liệt kê các lần quét của bạn

GET/api/v1/scans

Trả về các lần quét cho org gắn với token gọi, mới nhất trước. Phân trang bằng ?cursor=. Giới hạn mặc định 50, tối đa 100.

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

// phản hồi 200

{
  "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-..."
}

Lấy một lần quét

GET/api/v1/scans/{scanId}

Mặc định trả về envelope lần quét + tóm tắt mức độ nghiêm trọng theo danh mục. Truyền ?include_findings=true để lấy báo cáo đầy đủ (lớn với các lần quét nhiều nhiễu — nên dùng endpoint findings với filter).

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

Liệt kê phát hiện

GET/api/v1/findings

Danh sách phát hiện có thể lọc trên mọi lần quét trong org của người gọi. Filter: severity=critical,high, check_id=secrets.patterns, since=2026-04-01T00:00:00Z. Có phân trang bằng con trỏ.

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

// phản hồi 200

{
  "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
}

Đặc tả OpenAPI

Đặc tả đọc được bằng máy tại /docs/api/openapi (text/yaml). Đưa vào công cụ codegen bạn thích (openapi-typescript, openapi-python-client hoặc bất kỳ toolchain OpenAPI 3.1 nào) để tạo client có kiểu.

REST API — Docs · FixVibe