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.

Uthibitishaji

Kila ombi lazima libebe bearer token kwenye header ya Authorization. Tokens hutolewa kutoka Account → API tokens; plaintext huonyeshwa kwako mara moja tu wakati wa kuunda. Kufuta token hurejesha 401 kwenye simu inayofuata.

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

Muundo wa token: fxw_ ikifuatwa na herufi 43 za base64url. Huhifadhiwa at rest kama SHA-256 hash; plaintext haihifadhiwi kamwe upande wa server.

Vikomo vya kasi

Madirisha mawili kwa kila ombi lililothibitishwa: burst ya 10 req/sec na steady ya 60 req/min, zote zikifunguliwa kwa bearer hash. Utekelezaji wa kota (vikomo vya skani kwa mwezi) huwekwa juu yake — tazama Kota na vikomo.

Upangaji kurasa

List endpoints (/api/v1/scans, /api/v1/findings) hutumia upangaji kurasa wa cursor unaofunguliwa kwa (created_at, id) kwa mpangilio wa kushuka. Pitisha ?cursor=<next_cursor> kufetch ukurasa unaofuata. Cursor hubaki sahihi chini ya maandiko ya wakati mmoja (hakuna OFFSET skew).

Miundo ya hitilafu

Kila hitilafu ni kitu cha JSON chenye angalau key ya 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

Endpoints

Anzisha skani

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

Orodhesha skani zako

GET/api/v1/scans

Hurejesha skani za org iliyounganishwa na token inayopiga simu, mpya zaidi kwanza. Panga kurasa kwa ?cursor=. Kikomo chaguo-msingi 50, cha juu 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-..."
}

Pata skani

GET/api/v1/scans/{scanId}

Hurejesha envelope ya skani + muhtasari wa severity kwa kila category kwa chaguo-msingi. Pitisha ?include_findings=true kupata ripoti kamili (kubwa kwa skani zenye kelele — pendelea endpoint ya findings yenye filters).

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

Orodhesha 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 inayosomeka na mashine ipo /docs/api/openapi (text/yaml). Iweke kwenye codegen unayoipenda (openapi-typescript, openapi-python-client, au toolchain yoyote ya OpenAPI 3.1) kwa clients zenye types.

REST API — Docs · FixWeb