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.

ምርግጋጽ መንነት

ነፍሲ ወከፍ request ኣብ Authorization header bearer token ክሕዝ ኣለዎ። Tokens ካብ Account → API tokens ይወጹ፤ plaintext ኣብ ፍጥረት ሓንሳብ ጥራይ ትርእዮ። Token revoke ምግባር ኣብ ቀጻሊ call 401 ይመልስ።

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

ቅርጺ token: fxv_ ተኸቲሉ 43 base64url characters። ኣብ rest ከም SHA-256 hash ይዕቀብ፤ plaintext ኣብ server-side ፈጺሙ ኣይዕቀብን።

Rate limits

ኣብ ነፍሲ ወከፍ authenticated request ክልተ windows: 10 req/sec burst ን 60 req/min steady፣ ክልቲኦም ብ bearer hash keyed እዮም። Quota enforcement (per-month scan caps) ኣብ ልዕሊኡ ይድረብ፤ Quota ን ወሰናት ርአ።

Pagination

List endpoints (/api/v1/scans, /api/v1/findings) cursor-based pagination ይጥቀሙ፣ ብ (created_at, id) ኣብ descending order keyed እዮም። ቀጻሊ ገጽ ንምርካብ ?cursor=<next_cursor> ኣሕልፍ። Cursor ኣብ concurrent writes ልክዕ ይተርፍ (OFFSET skew የለን)።

ቅርጺ error

ነፍሲ ወከፍ error ብውሑዱ error key ዘለዎ JSON object እዩ።

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

Endpoints

Scan ጀምር

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

// 200 መልሲ

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

Scansካ ዘርዝር

GET/api/v1/scans

ን org ምስቲ calling token ዝተኣሳሰሩ scans ይመልስ፣ ዝሓደሰ መጀመርታ። ብ ?cursor= paginate ግበር። Default limit 50፣ max 100።

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

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

Scan ርኸብ

GET/api/v1/scans/{scanId}

ብ default scan envelope + per-category severity summary ይመልስ። ምሉእ report ንምርካብ ?include_findings=true ኣሕልፍ (ን noisy scans ዓቢ እዩ፤ findings endpoint ምስ filters ምረጽ)።

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

Findings ዘርዝር

GET/api/v1/findings

ኣብ ኩሉ scans ናይ caller org filterable findings list። Filters: severity=critical,high, check_id=secrets.patterns, since=2026-04-01T00:00:00Z። Cursor-paginated።

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

// 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
}

OpenAPI spec

Machine-readable spec ኣብ /docs/api/openapi (text/yaml)። ን typed clients ናብ ዝፈትዎ codegen (openapi-typescript, openapi-python-client, ወይ ዝኾነ OpenAPI 3.1 toolchain) ኣእትዎ።

REST API — Docs · FixVibe