API Reference

The TrustTrace API lets you scan MCP servers and configuration files programmatically. Use it to integrate security scanning into your scripts, automation, and CI/CD pipelines.

Base URL: https://api.trusttrace.io

Authentication

All API requests require authentication via API key. Find your API key on your account page.

Include your key in the request header:

Authorization: Bearer sk_scan_your_api_key_here

Or use the X-API-Key header:

X-API-Key: sk_scan_your_api_key_here

Keep your API key secret. If compromised, generate a new one from your account page. The old key will be immediately revoked.

Rate Limits

API requests count toward your monthly scan limit:

Plan	Scans per Month
Free	3
Developer	15
Pro	50
Team	200
Enterprise	500

When you exceed your limit, the API returns 429 Too Many Requests with a Retry-After header indicating when your limit resets.

{
  "error": "Monthly scan limit reached",
  "limit": 15,
  "used": 15,
  "resets_at": "2026-04-01T00:00:00Z",
  "upgrade_url": "https://trusttrace.io/pricing"
}

Endpoints

Submit MCP Server Scan

Scan a live MCP server by URL.

POST /v1/scan/mcp

Request:

{
  "url": "https://your-mcp-server.example.com/sse",
  "auth_token": null
}

Field	Type	Required	Description
`url`	string	Yes	MCP server endpoint URL. Must be `http://` or `https://`.
`auth_token`	string	No	Authentication token if the server requires it.

Response (202 Accepted):

{
  "scan_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "estimated_seconds": 60
}

Restrictions:

URLs pointing to private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are rejected
Maximum connection timeout: 10 seconds
Maximum response size: 1MB

Submit File Upload Scan

Scan configuration files by uploading them.

POST /v1/scan/upload
Content-Type: multipart/form-data

Request:

curl -X POST https://api.trusttrace.io/v1/scan/upload \
  -H "Authorization: Bearer sk_scan_your_key" \
  -F "files=@tool_schema.json" \
  -F "files=@requirements.txt" \
  -F "files=@agent.py"

Field	Type	Required	Description
`files`	multipart	Yes	One or more files. Accepted types: `.json`, `.yaml`, `.yml`, `.txt`, `.py`, `.js`, `.ts`, `.toml`, and standard lockfile names.

Response (202 Accepted):

{
  "scan_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "files_accepted": ["tool_schema.json", "requirements.txt", "agent.py"],
  "estimated_seconds": 90
}

Restrictions:

Maximum total upload size: 10MB
Unrecognized file types are rejected
Executable files (.exe, .sh, .bat) are rejected

Get Scan Results

Poll for scan status and retrieve results.

GET /v1/scan/{scan_id}

Response varies by scan status:

Queued:

{
  "scan_id": "a1b2c3d4...",
  "status": "queued",
  "position": 3
}

Running:

{
  "scan_id": "a1b2c3d4...",
  "status": "running",
  "progress": "Analyzing MCP tool definitions..."
}

Complete:

{
  "scan_id": "a1b2c3d4...",
  "status": "complete",
  "overall_score": 43,
  "letter_grade": "D",
  "findings": [
    {
      "id": "MCP-001",
      "title": "Unauthenticated MCP server",
      "severity": "critical",
      "owasp_category": "LLM06",
      "confidence": "confirmed",
      "description": "MCP server accepts connections without...",
      "remediation": "Enable authentication on the MCP server...",
      "evidence": "Connection succeeded without credentials on...",
      "hipaa_mapping": null,
      "monitor_candidate": true
    }
  ]
}

Tier-based response filtering:

Field	Free	Developer+	Enterprise
`severity`	✅	✅	✅
`title`	✅	✅	✅
`owasp_category`	✅	✅	✅
`description`	—	✅	✅
`remediation`	—	✅	✅
`evidence`	—	✅	✅
`hipaa_mapping`	—	—	✅

Free tier responses include an upgrade_message field on each finding.

Failed:

{
  "scan_id": "a1b2c3d4...",
  "status": "failed",
  "error": "Connection timeout: unable to reach MCP server"
}

List Scan History

Retrieve your past scans. Requires Developer plan or above.

GET /v1/scans?page=1&per_page=20&status=complete

Parameter	Type	Default	Description
`page`	int	1	Page number
`per_page`	int	20	Results per page (max 100)
`status`	string	—	Filter by status: `queued`, `running`, `complete`, `failed`

Response:

{
  "scans": [
    {
      "scan_id": "a1b2c3d4...",
      "scan_type": "mcp",
      "status": "complete",
      "overall_score": 43,
      "finding_count": 7,
      "created_at": "2026-03-06T14:30:00Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 42
}

Generate PDF Report

Generate a downloadable PDF report from a completed scan. Requires Developer plan or above.

POST /v1/scan/{scan_id}/report

Response:

{
  "report_url": "https://api.trusttrace.io/v1/reports/abc123.pdf",
  "expires_at": "2026-03-07T14:30:00Z"
}

Report URLs are temporary and expire after 24 hours.

Get Account Info

Retrieve your account details, current plan, and usage.

GET /v1/account

Response:

{
  "email": "developer@example.com",
  "tier": "developer",
  "api_key": "sk_scan_abc123...",
  "scans_used": 12,
  "scans_limit": 15,
  "resets_at": "2026-04-01T00:00:00Z",
  "webhook_url": null
}

Set Webhook URL (Team+)

Configure a webhook to receive scan results automatically. Requires Team plan or above.

PUT /v1/account/webhook

Request:

{
  "webhook_url": "https://your-app.example.com/webhooks/trusttrace"
}

When a scan completes, TrustTrace sends a POST request to your webhook URL:

{
  "scan_id": "a1b2c3d4...",
  "status": "complete",
  "overall_score": 43,
  "letter_grade": "D",
  "findings_count": {
    "critical": 3,
    "high": 5,
    "medium": 2,
    "low": 1
  }
}

The request includes an X-TrustTrace-Signature header containing an HMAC-SHA256 signature of the payload, signed with your API key. Verify this signature to confirm the webhook is authentic.

Verification example (Python):

import hmac
import hashlib

def verify_webhook(payload_body, signature, api_key):
    expected = hmac.new(
        api_key.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Error Codes

Code	Meaning
400	Bad request — invalid URL, unsupported file type, or missing required fields
401	Unauthorized — missing or invalid API key
403	Forbidden — feature not available on your plan
404	Not found — scan ID doesn't exist or doesn't belong to you
413	Payload too large — upload exceeds 10MB
429	Rate limit exceeded — monthly scan limit reached
500	Server error — contact hello@trusttrace.io

All error responses include a JSON body:

{
  "error": "Description of what went wrong",
  "code": "ERROR_CODE"
}

SDKs and Libraries

Official SDKs are on our roadmap. In the meantime, the REST API works with any HTTP client. The curl examples throughout this documentation can be adapted to any language.

Need Help?

Email: hello@trusttrace.io
Issues with the API? Include your scan ID in your message for fastest resolution.