SPHIOR

SPHIOR · Referência da API

Um endpoint. JSON entra, JSON sai.

A API de segurança SPHIOR permite escanear código em busca de vulnerabilidades e entregar orientação de correção determinística ao seu próprio agente de IA — em qualquer linguagem ou ambiente.

https://api.sphior.com|v1 (stable)|REST / JSON

Obter chave API Visão geral da API

Terminal

$ curl -X POST https://api.sphior.com/v1/scan \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"code": "...", "language": "javascript"}'

// Response
{
  "findings": [
    { "type": "sql_injection",
      "severity": "critical",
      "cvss": 9.8 }
  ]
}

SPHIOR API

Referência da API

Autenticação

Todas as requisições devem incluir sua chave API no cabeçalho Authorization como token Bearer.

bash

curl https://api.sphior.com/v1/scan \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Nunca exponha sua chave API em código do lado do cliente ou repositórios públicos. Use variáveis de ambiente ou um gerenciador de segredos.

Gere e gerencie chaves API no Console API. Máximo de 5 chaves ativas por conta.

POST/v1/scan

Escanear código

Analisa um trecho de código em busca de vulnerabilidades. Retorna descobertas com severidade, pontuação CVSS, número da linha e recomendação de correção. Totalmente determinístico (sem IA): o mesmo código sempre produz os mesmos resultados — reproduzível e pronto para auditoria.

Corpo da requisição

Parâmetro	Tipo	Descrição
coderequired	string	O código-fonte a analisar. Tamanho máximo depende do plano (10KB–10MB).
languagerequired	string	Linguagem: javascript, typescript, python, go, java, ruby, php, sql
policy_id	string	ID de política personalizada (planos Business+). Padrão: OWASP.

Exemplo de requisição

bash

curl -X POST https://api.sphior.com/v1/scan \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "app.get(\"/user\", (req, res) => { db.query(\"SELECT * FROM users WHERE id=\" + req.query.id) })",
    "language": "javascript"
  }'

Exemplo de resposta

json

{
  "scan_id": "scan_01j9x7z3k8q4b5c2d6e7f8g9h0",
  "status": "completed",
  "language": "javascript",
  "findings": [
    {
      "id": "find_001",
      "type": "sql_injection",
      "severity": "critical",
      "cvss": 9.8,
      "line": 2,
      "column": 11,
      "message": "Unsanitized user input passed directly to SQL query",
      "cwe": "CWE-89",
      "owasp": "A03:2021",
      "fix_hint": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [req.query.id])"
    }
  ],
  "summary": {
    "critical": 1, "high": 0, "medium": 0, "low": 0, "info": 0
  },
  "ai_calls": 0,
  "cached": false,
  "latency_ms": 12
}

POST/v1/fix

Obter guia de correção

A partir de um finding ID de uma varredura anterior, retorna orientação de correção determinística — por que importa, etapas de remediação, localização e instruções para seu agente de IA. A SPHIOR não escreve patches nem transmite seu código-fonte; sua própria IA (via MCP) aplica a correção.

Corpo da requisição

Parâmetro	Tipo	Descrição
scan_idrequired	string	ID retornado por uma chamada /v1/scan anterior.
finding_idrequired	string	Descoberta específica para gerar uma correção.
context	string	Contexto de código adicional (arquivo completo recomendado).

Exemplo de resposta

json

{
  "fix_id": "fix_01j9x8a1b2c3d4e5f6g7h8i9j0",
  "scan_id": "scan_01j9x7z3k8q4b5c2d6e7f8g9h0",
  "finding_id": "find_001",
  "patched_code": null,
  "fix_context": {
    "finding_id": "find_001",
    "rule_id": "pattern.js.sql_concat",
    "severity": "critical",
    "cwe": "CWE-89",
    "owasp": "A03:2021",
    "why": "OS command / SQL injection: untrusted input reaches the query and can execute arbitrary statements.",
    "remediation_steps": [
      "Review the flagged code and identify the interpolated value.",
      "Use a parameterized query (e.g. WHERE id = ?) with bound parameters.",
      "Add a regression test covering the fixed behavior."
    ],
    "agent_instructions": "Open the file in your workspace and read the actual code yourself (it is NOT included here). Apply the remediation steps. A human must review your change before merge.",
    "data_boundary_note": "SPHIOR does not transmit your source code. This payload contains only finding metadata and deterministic remediation guidance."
  },
  "latency_ms": 9
}

GET/v1/rules

Listar regras

Lista todas as regras de segurança ativas disponíveis para seu plano. Retorna ID da regra, categoria, severidade e linguagens aplicáveis.

bash

curl https://api.sphior.com/v1/rules \
  -H "Authorization: Bearer sk_live_..." \
  -G -d "language=javascript" -d "severity=critical"

Parâmetros de consulta

Parâmetro	Tipo	Descrição
language	string	Filtrar por linguagem (ex. python, go). Omitir para todas.
severity	string	Filtrar por severidade: critical, high, medium, low, info
category	string	Filtrar por categoria OWASP: injection, auth, crypto

Webhooks

Registre uma URL de webhook no Console API para receber eventos em tempo real quando varreduras forem concluídas ou vulnerabilidades críticas detectadas.

Tipos de evento

scan.completed

Disparado quando uma varredura é concluída. Inclui scan_id, resumo e contagem.

scan.critical_found

Disparado imediatamente quando uma vulnerabilidade crítica é detectada.

spend_cap.reached

Disparado quando o gasto mensal atinge o limite configurado.

spend_cap.warning

Disparado quando o gasto atinge 80% do limite.

Os payloads de webhook são assinados com HMAC-SHA256. Sempre verifique o cabeçalho X-SPHIOR-Signature antes de processar.

Códigos de erro

A API SPHIOR usa códigos de status HTTP padrão. Respostas de erro são JSON com campos error e code.

Status	Código	Significado
401	unauthenticated	Chave API ausente ou inválida.
403	forbidden	A chave não tem permissão para esta operação.
400	invalid_request	JSON malformado, campos obrigatórios ausentes ou linguagem não suportada.
413	payload_too_large	O tamanho do código excede o limite do seu plano.
429	spend_cap_reached	Limite de gastos mensal atingido. Apenas resultados de regras são retornados.
429	rate_limited	Muitas requisições por segundo. Recue e tente novamente.
500	internal_error	Erro inesperado do servidor. Tente novamente com backoff exponencial.

json

// Error response shape
{
  "error": "Missing required field: language",
  "code": "invalid_request",
  "status": 400
}

SDKs

SDKs oficiais estão disponíveis para TypeScript/JavaScript e Python. Ambos encapsulam a API REST com respostas tipadas, retentativas automáticas e controle de gastos.

TypeScript / Node.js

bash

npm install @sphior/sdk

typescript

import { SphiorClient } from "@sphior/sdk";

const sphior = new SphiorClient({ apiKey: process.env.SPHIOR_API_KEY });

const result = await sphior.scan({
  code: fs.readFileSync("./auth.ts", "utf8"),
  language: "typescript",
});

for (const finding of result.findings) {
  console.log(`${finding.severity.toUpperCase()}: ${finding.message} (line ${finding.line})`);
  console.log("Fix hint:", finding.fix_hint);
}

// Hand a finding to your own AI agent to fix (deterministic guidance, no code sent):
const guidance = await sphior.fix({ scan_id: result.scan_id, finding_id: result.findings[0].id });
console.log(guidance.fix_context.remediation_steps);

Python

bash

pip install sphior-sdk

python

from sphior import SphiorClient

client = SphiorClient(api_key=os.environ["SPHIOR_API_KEY"])

result = client.scan(
    code=open("app.py").read(),
    language="python",
)

for finding in result.findings:
    print(f"{finding.severity.upper()}: {finding.message} (line {finding.line})")
    print("Fix hint:", finding.fix_hint)

# Hand a finding to your own AI agent to fix (deterministic guidance, no code sent):
guidance = client.fix(scan_id=result.scan_id, finding_id=result.findings[0].id)
print(guidance.fix_context["remediation_steps"])

Preços

A API cobra uma taxa de plataforma simples pelo acesso. A varredura e a orientação de correção rodam em um motor totalmente determinístico — sem cobrança por chamada de IA. Os planos diferem em limites de taxa, tamanho de código e suporte.

Plan	Platform fee	Scanning	Fix guidance
Free	$0/mo	Included	Included
Developer	$29/mo	Included	Included
Business	$99/mo	Included	Included
Enterprise	$299+/mo	Included	Included

O motor determinístico mantém os custos estáveis e previsíveis. Limites de taxa por segundo e de tamanho de código escalam por plano; configure-os no Console API.

Detalhes completos de preços Obter chave API