SPHIOR

SPHIOR · API Reference

One endpoint. JSON in, JSON out.

The SPHIOR Security API lets you scan code for vulnerabilities and hand deterministic fix guidance to your own AI agent — from any language, framework, or environment.

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

Get API key API overview

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

API Reference

The SPHIOR Security API lets you scan code for vulnerabilities and hand deterministic fix guidance to your own AI agent — from any language, framework, or environment.

Authentication

All requests must include your API key in the Authorization header as a Bearer token.

bash

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

Never expose your API key in client-side code or public repositories. Use environment variables or a secrets manager.

Generate and manage API keys in the API Console. Maximum 5 active keys per account.

POST/v1/scan

Scan code

Analyze a code snippet for security vulnerabilities. Returns findings with severity, CVSS score, line number, and a fix recommendation. Fully deterministic (no AI): the same code always produces the same findings — reproducible and audit-ready.

Request body

Parameter	Type	Description
coderequired	string	The source code to analyze. Max size depends on your plan (10KB–10MB).
languagerequired	string	Programming language: javascript, typescript, python, go, java, ruby, php, sql
policy_id	string	Custom policy ID to apply (Business+ plans). Defaults to OWASP ruleset.

Example request

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

Example response

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

Get fix guidance

Given a finding ID from a previous scan, return deterministic fix guidance — why it matters, remediation steps, location, and instructions for your AI agent. SPHIOR never writes patches or transmits your source code; your own AI (via MCP) applies the fix.

Request body

Parameter	Type	Description
scan_idrequired	string	ID returned by a previous /v1/scan call.
finding_idrequired	string	Specific finding to generate a fix for.
context	string	Additional surrounding code context (full file recommended for best results).

Example response

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

List rules

List all active security rules available for your plan. Returns rule ID, category, severity, and applicable languages. Business+ plans can create custom rules via the console.

bash

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

Query parameters

Parameter	Type	Description
language	string	Filter by language (e.g. python, go). Omit for all languages.
severity	string	Filter by severity: critical, high, medium, low, info
category	string	Filter by OWASP category e.g. injection, auth, crypto

Webhooks

Register a webhook URL in the API Console to receive real-time events when scans complete, when critical findings are detected, or when spend caps are reached.

Event types

scan.completed

Fired when a scan finishes. Payload includes scan_id, summary, and finding count.

scan.critical_found

Fired immediately when a critical-severity finding is detected.

spend_cap.reached

Fired when monthly spend reaches the configured cap.

spend_cap.warning

Fired when spend reaches 80% of the cap.

Webhook payloads are signed with HMAC-SHA256 using your webhook secret. Always verify the X-SPHIOR-Signature header before processing.

Error codes

SPHIOR API uses standard HTTP status codes. Error responses are JSON with error and code fields.

Status	Code	Meaning
401	unauthenticated	Missing or invalid API key.
403	forbidden	Key does not have permission for this operation.
400	invalid_request	Malformed JSON, missing required fields, or unsupported language.
413	payload_too_large	Code size exceeds your plan's limit.
429	spend_cap_reached	Monthly spend cap has been reached. Rules-only results returned.
429	rate_limited	Too many requests per second. Back off and retry.
500	internal_error	Unexpected server error. Retry with exponential backoff.

json

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

SDKs

Official SDKs are available for TypeScript/JavaScript and Python. Both wrap the REST API with typed responses, automatic retries, and spend cap awareness.

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

Pricing

SPHIOR Security API charges a simple platform fee for access. Scanning and fix guidance run on a fully deterministic engine — there is no per-AI-call charge. Plans differ by rate limits, code-size limits, and support.

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

The deterministic engine keeps costs flat and predictable. Per-second rate limits and code-size limits scale by plan; configure them in the API Console.

Full pricing details Get API key