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

Autenticação

Cada requisição deve carregar um token bearer no header Authorization. Tokens são emitidos em Conta → Tokens de API; o texto simples é mostrado a você exatamente uma vez na criação. Revogar um token retorna 401 na próxima chamada.

bash

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

Formato do token: fxw_ seguido de 43 caracteres base64url. Armazenado em repouso como hash SHA-256; o texto simples nunca é persistido no servidor.

Limites de taxa

Duas janelas em cada requisição autenticada: burst de 10 req/s e estado estável de 60 req/min, ambas indexadas pelo hash bearer. A aplicação de cota (limites de varredura por mês) é adicionada por cima — veja Cotas e limites.

Paginação

Endpoints de listagem (/api/v1/scans, /api/v1/findings) usam paginação baseada em cursor indexada por (created_at, id) em ordem descendente. Passe ?cursor=<next_cursor> para buscar a próxima página. O cursor continua correto sob escritas concorrentes (sem desvio de OFFSET).

Formatos de erro

Todo erro é um objeto JSON com pelo menos uma chave 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

Iniciar uma varredura

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

// resposta 200

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

Listar suas varreduras

GET/api/v1/scans

Retorna varreduras da org vinculada ao token chamador, mais recentes primeiro. Pagine com ?cursor=. Limite padrão 50, máximo 100.

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

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

Obter uma varredura

GET/api/v1/scans/{scanId}

Retorna o envelope da varredura + resumo de severidade por categoria por padrão. Passe ?include_findings=true para obter o relatório completo (grande para varreduras ruidosas — prefira o endpoint de findings com filtros).

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

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

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

Spec OpenAPI

Spec legível por máquina em /docs/api/openapi (text/yaml). Coloque no seu codegen favorito (openapi-typescript, openapi-python-client ou qualquer toolchain OpenAPI 3.1) para clientes tipados.