API Documentation

Integrate TrustTrace scanning into your workflow.

Authentication

All API requests require an API key sent via the Authorization header.

You can also use the X-API-Key header as an alternative.

Base URL

https://api.trusttrace.io/v1

POST/v1/scan/mcp

Submit an MCP server URL for security scanning. The server's tool definitions will be fetched and analyzed for OWASP LLM Top 10 vulnerabilities.

Request

curl -X POST https://api.trusttrace.io/v1/scan/mcp \
  -H "Authorization: Bearer sk_scan_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-mcp-server.com/sse"}'

Response

{
  "scan_id": "abc123-def456",
  "status": "queued"
}

POST/v1/scan/upload

Upload files for scanning. Supports tool schemas (.json), dependency files, code files, and archives (.zip, .tar.gz).

Request

curl -X POST https://api.trusttrace.io/v1/scan/upload \
  -H "Authorization: Bearer sk_scan_your_key_here" \
  -F "file=@tools.json"

Response

{
  "scan_id": "abc123-def456",
  "status": "queued"
}

GET/v1/scan/{scan_id}

Poll for scan results. Returns status, score, and findings when complete. Finding detail level depends on your plan.

Request

curl https://api.trusttrace.io/v1/scan/abc123-def456 \
  -H "Authorization: Bearer sk_scan_your_key_here"

Response (completed, paid tier)

{
  "scan_id": "abc123-def456",
  "status": "completed",
  "overall_score": 65,
  "letter_grade": "C",
  "findings_count": 7,
  "findings": [
    {
      "finding_id": "FND-a1b2c3d4",
      "title": "Unauthenticated MCP Server Access",
      "severity": "CRITICAL",
      "owasp_category": "LLM06",
      "description": "The MCP server allows...",
      "remediation": "Implement authentication...",
      "evidence": ["No auth middleware detected"],
      "hipaa_mapping": [],
      "soc2_mapping": []
    }
  ],
  "category_scores": [
    {"category": "LLM01", "score": 7.0, "rating": "High Risk"}
  ]
}

Response (completed, free tier)

{
  "scan_id": "abc123-def456",
  "status": "completed",
  "overall_score": 65,
  "letter_grade": "C",
  "findings_count": 7,
  "findings": [
    {
      "finding_id": "FND-a1b2c3d4",
      "title": "Unauthenticated MCP Server Access",
      "severity": "CRITICAL",
      "owasp_category": "LLM06"
    }
  ],
  "upgrade_message": "Upgrade to Developer to see full details..."
}

GET/v1/scans

List your scan history with pagination. Requires Developer plan or above.

Request

curl "https://api.trusttrace.io/v1/scans?limit=20&offset=0" \
  -H "Authorization: Bearer sk_scan_your_key_here"

Rate Limits

Scan limits are enforced per calendar month and reset on the 1st.

Plan	Scans/Month	API Requests/Min
Free	3	10
Developer	15	10
Pro	50	10
Team	200	10
Enterprise	500	10

Error Codes

Code	Description
400	Bad request — invalid input
401	Unauthorized — missing or invalid API key
403	Forbidden — feature not available on your plan
413	File too large — max 50MB per upload
429	Rate limit exceeded — too many requests or monthly scan limit reached

CI/CD Integration

Add TrustTrace scanning to your GitHub Actions workflow. Set TRUSTTRACE_API_KEY as a repository secret.

name: TrustTrace MCP Scan
on: [push, pull_request]
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan MCP Server
        env:
          API_KEY: ${{ secrets.TRUSTTRACE_API_KEY }}
          MCP_URL: ${{ vars.MCP_SERVER_URL }}
        run: |
          # Submit scan
          RESULT=$(curl -s -X POST https://api.trusttrace.io/v1/scan/mcp \
            -H "Authorization: Bearer $API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"url\": \"$MCP_URL\"}")
          SCAN_ID=$(echo $RESULT | jq -r '.scan_id')

          # Poll for results
          for i in {1..30}; do
            STATUS=$(curl -s https://api.trusttrace.io/v1/scan/$SCAN_ID \
              -H "Authorization: Bearer $API_KEY" | jq -r '.status')
            if [ "$STATUS" = "completed" ]; then break; fi
            if [ "$STATUS" = "failed" ]; then
              echo "::error::Scan failed"
              exit 1
            fi
            sleep 10
          done

          # Check for critical findings
          CRITICALS=$(curl -s https://api.trusttrace.io/v1/scan/$SCAN_ID \
            -H "Authorization: Bearer $API_KEY" \
            | jq '.findings | map(select(.severity == "CRITICAL")) | length')
          if [ "$CRITICALS" -gt 0 ]; then
            echo "::error::TrustTrace found $CRITICALS critical vulnerabilities"
            exit 1
          fi