API Reference

Complete REST API documentation for the Spyda TrustScore Platform

Base URL

https://api.spyda.ai/v1

All API endpoints are versioned. The current version is v1.

Authentication

API requests require an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

POST

/v1/score

Calculate a TrustScore by uploading scanner results. Ingests multiple security tool outputs, normalizes findings, correlates across sources, and returns a unified security score.

Query Parameters

Parameter	Type	Required	Description
project_name	string	Yes	Name of the project being scanned

Request Body

Content-Type: multipart/form-data

Field	Type	Description
files	File[]	One or more JSON files from security scanners (Snyk, Trivy, Semgrep, Syft)

Example Request

curl -X 'POST' \
  'https://api.spyda.ai/v1/score?project_name=SpydaWeb-Core' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@snyk_report.json' \
  -F 'files=@trivy_report.json'

Response

{
  "project": "SpydaWeb-Core",
  "trustscore": 87.5,
  "grade": "PASS",
  "score_threshold": 85.0,
  "policy": "Standard-Security-Gate",
  "breakdown": {
    "vulnerabilities": 85.2,
    "compliance": 92.0,
    "supply_chain": 83.1,
    "ai_risk": 95.0
  },
  "findings": [
    {
      "id": "f1a2b3c4",
      "domain": "supply_chain",
      "title": "Log4j RCE",
      "severity": "Critical",
      "confidence": 0.95,
      "confidence_breakdown": {
        "corroboration": 1.0,
        "clarity": 0.9,
        "source_credibility": 0.85,
        "exploitability": 0.8,
        "contradiction": 0.0
      },
      "description": "Corroborated by 2 sources. Remote Code Execution in Log4j",
      "evidence": {
        "sources": [
          {
            "tool": "Snyk",
            "issueId": "SNYK-JAVA-LOG4J-123",
            "component": "log4j-core"
          },
          {
            "tool": "Trivy",
            "issueId": "CVE-2021-44228",
            "component": "log4j-core"
          }
        ],
        "references": [
          "https://nvd.nist.gov/vuln/detail/CVE-2021-44228"
        ]
      },
      "status": "Open"
    }
  ],
  "timestamp": "2025-01-15T12:00:00Z"
}

Response Fields

trustscore(float) - Final security score from 0-100

grade(string) - "PASS", "FAIL", or "FAIL (Critical Block)"

breakdown(object) - Domain-specific scores for vulnerabilities, compliance, supply_chain, ai_risk

findings(array) - Normalized, correlated security findings with confidence scores

Additional Endpoints

GET/v1/health

Check API health status

GET/v1/policies

List available security policies

POST/v1/waiver

Mark findings as false positives or accepted risks

SDK Examples

JavaScript/TypeScript

const FormData = require('form-data');
const fs = require('fs');

const formData = new FormData();
formData.append('files', fs.createReadStream('snyk_report.json'));
formData.append('files', fs.createReadStream('trivy_report.json'));

const response = await fetch(
  'https://api.spyda.ai/v1/score?project_name=MyProject',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      ...formData.getHeaders()
    },
    body: formData
  }
);

const result = await response.json();
console.log(`TrustScore: ${result.trustscore}`);

Python

import requests

files = [
    ('files', open('snyk_report.json', 'rb')),
    ('files', open('trivy_report.json', 'rb'))
]

response = requests.post(
    'https://api.spyda.ai/v1/score',
    params={'project_name': 'MyProject'},
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    files=files
)

result = response.json()
print(f"TrustScore: {result['trustscore']}")