SPHIOR

SPHIOR · Referencia API

Un endpoint. JSON entra, JSON sale.

La API de seguridad SPHIOR permite escanear código en busca de vulnerabilidades y entregar una guía de corrección determinista a tu propio agente de IA — desde cualquier lenguaje o entorno.

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

Obtener clave API Resumen 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

Referencia API

La API de seguridad SPHIOR permite escanear código en busca de vulnerabilidades y entregar una guía de corrección determinista a tu propio agente de IA — desde cualquier lenguaje o entorno.

Autenticación

Todas las solicitudes deben incluir su clave API en el encabezado 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 exponga su clave API en código del lado del cliente o repositorios públicos. Use variables de entorno o un gestor de secretos.

Genere y administre claves API en la Consola API. Máximo 5 claves activas por cuenta.

POST/v1/scan

Escanear código

Analiza un fragmento de código en busca de vulnerabilidades. Devuelve hallazgos con severidad, puntuación CVSS, número de línea y recomendación de corrección. Totalmente determinista (sin IA): el mismo código siempre produce los mismos hallazgos — reproducible y listo para auditoría.

Cuerpo de la solicitud

Parámetro	Tipo	Descripción
coderequired	string	El código fuente a analizar. Tamaño máximo según su plan (10KB–10MB).
languagerequired	string	Lenguaje: javascript, typescript, python, go, java, ruby, php, sql
policy_id	string	ID de política personalizada (planes Business+). Por defecto OWASP.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Obtener guía de corrección

Dado un finding ID de un escaneo anterior, devuelve una guía de corrección determinista: por qué importa, pasos de remediación, ubicación e instrucciones para tu agente de IA. SPHIOR no escribe parches ni transmite tu código fuente; tu propia IA (vía MCP) aplica la corrección.

Cuerpo de la solicitud

Parámetro	Tipo	Descripción
scan_idrequired	string	ID devuelto por una llamada /v1/scan anterior.
finding_idrequired	string	Hallazgo específico para generar una corrección.
context	string	Contexto de código adicional (se recomienda el archivo completo).

Ejemplo de respuesta

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 reglas

Lista todas las reglas de seguridad activas disponibles para su plan. Devuelve ID de regla, categoría, severidad e idiomas aplicables.

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	Descripción
language	string	Filtrar por lenguaje (ej. python, go). Omitir para todos.
severity	string	Filtrar por severidad: critical, high, medium, low, info
category	string	Filtrar por categoría OWASP: injection, auth, crypto

Webhooks

Registre una URL de webhook en la Consola API para recibir eventos en tiempo real cuando se completen escaneos o se detecten hallazgos críticos.

Tipos de evento

scan.completed

Se dispara al completar un escaneo. Incluye scan_id, resumen y conteo.

scan.critical_found

Se dispara inmediatamente al detectar un hallazgo crítico.

spend_cap.reached

Se dispara cuando el gasto mensual alcanza el límite configurado.

spend_cap.warning

Se dispara cuando el gasto alcanza el 80% del límite.

Los payloads de webhook están firmados con HMAC-SHA256. Verifique siempre el encabezado X-SPHIOR-Signature antes de procesar.

Códigos de error

La API de SPHIOR usa códigos de estado HTTP estándar. Las respuestas de error son JSON con campos error y code.

Estado	Código	Significado
401	unauthenticated	Clave API faltante o inválida.
403	forbidden	La clave no tiene permiso para esta operación.
400	invalid_request	JSON malformado, campos requeridos faltantes o lenguaje no soportado.
413	payload_too_large	El tamaño del código excede el límite de su plan.
429	spend_cap_reached	Se alcanzó el límite de gasto mensual. Solo se devuelven resultados de reglas.
429	rate_limited	Demasiadas solicitudes por segundo. Retroceda y reintente.
500	internal_error	Error inesperado del servidor. Reintente con retroceso exponencial.

json

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

SDKs

Los SDKs oficiales están disponibles para TypeScript/JavaScript y Python. Ambos envuelven la API REST con respuestas tipadas, reintentos automáticos y control de gasto.

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"])

Precios

La API cobra una simple tarifa de plataforma por el acceso. El escaneo y la guía de corrección se ejecutan en un motor totalmente determinista — sin cargo por llamada de IA. Los planes difieren en límites de tasa, tamaño de código y soporte.

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

El motor determinista mantiene los costos planos y predecibles. Los límites de tasa por segundo y de tamaño de código escalan por plan; configúrelos en la Consola API.

Detalles completos de precios Obtener clave API