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.

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 fxv_..." \
  https://fixvibe.app/api/v1/scans

Formato do token: fxv_ 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 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"}'

// resposta 200

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

Listar as 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 fxv_..." \
  "https://fixvibe.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 fxv_..." \
  https://fixvibe.app/api/v1/scans/8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d

Listar findings

GET/api/v1/findings

Lista filtrável de findings em todas as varreduras da org chamadora. Filtros: severity=critical,high, check_id=secrets.patterns, since=2026-04-01T00:00:00Z. Paginada por cursor.

curl -H "Authorization: Bearer fxv_..." \
  "https://fixvibe.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.

REST API — Docs · FixVibe