API Reference

Programmatic Security Scanning

Integrate Bloodhound security scanning into your applications and workflows using our REST API. Full programmatic control over scans, results, and reports.

Overview

The Bloodhound API allows you to programmatically trigger scans, retrieve results, and generate reports. Use it to integrate security scanning into your custom workflows.

REST

Protocol

JSON

Format

Version

Bearer

Auth

Base URL

https://api.agnech.com/v1

Available Endpoints

POST/api/v1/scanStart a new security scan

GET/api/v1/scan/:idGet scan status and progress

GET/api/v1/scan/:id/resultsGet scan results

POST/api/v1/reportGenerate a report from scan results

GET/api/v1/licenseGet license informationEnterprise

POST/api/v1/webhookRegister a webhook endpointEnterprise

Authentication

All API requests require authentication using a Bearer token.

Authentication Example

Bash

1# Include your API key in the Authorization header
2curl -X GET "https://api.agnech.com/v1/license" \
3  -H "Authorization: Bearer YOUR_API_KEY" \
4  -H "Content-Type: application/json"

API Keys

API keys are generated from your enterprise dashboard. Each key is tied to your license and has the same permissions.

Scan API

Start a Scan

Initiate a security scan on a codebase.

POST /api/v1/scan

Bash

1# Start a scan
2curl -X POST "https://api.agnech.com/v1/scan" \
3  -H "Authorization: Bearer YOUR_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "repository": "https://github.com/user/repo",
7    "branch": "main",
8    "mode": "advanced",
9    "paths": ["src/"],
10    "exclude": ["node_modules/", "dist/"]
11  }'
12
13# Response
14{
15  "id": "scan_abc123",
16  "status": "pending",
17  "created_at": "2024-01-15T10:30:00Z",
18  "estimated_duration": 120
19}

Get Scan Status

GET /api/v1/scan/:id

Bash

1# Get scan status
2curl -X GET "https://api.agnech.com/v1/scan/scan_abc123" \
3  -H "Authorization: Bearer YOUR_API_KEY"
4
5# Response
6{
7  "id": "scan_abc123",
8  "status": "completed",
9  "progress": 100,
10  "findings_count": 12,
11  "engines_completed": 7,
12  "duration_seconds": 95,
13  "completed_at": "2024-01-15T10:31:35Z"
14}

Results API

GET /api/v1/scan/:id/results

Bash

1# Get scan results
2curl -X GET "https://api.agnech.com/v1/scan/scan_abc123/results" \
3  -H "Authorization: Bearer YOUR_API_KEY"
4
5# Response
6{
7  "id": "scan_abc123",
8  "summary": {
9    "total": 12,
10    "critical": 2,
11    "high": 5,
12    "medium": 3,
13    "low": 2,
14    "shield_score": 72
15  },
16  "findings": [
17    {
18      "id": "finding_001",
19      "type": "sql-injection",
20      "severity": "critical",
21      "confidence": 94,
22      "file": "src/api/users.ts",
23      "line": 45,
24      "column": 12,
25      "message": "SQL injection vulnerability detected",
26      "cwe": "CWE-89",
27      "engines": ["pattern", "sast", "taint"],
28      "remediation": "Use parameterized queries instead of string concatenation"
29    }
30  ]
31}

Reports API

POST /api/v1/report

Bash

1# Generate a report
2curl -X POST "https://api.agnech.com/v1/report" \
3  -H "Authorization: Bearer YOUR_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "scan_id": "scan_abc123",
7    "format": "executive",
8    "output": "pdf"
9  }'
10
11# Response
12{
13  "id": "report_xyz789",
14  "status": "generating",
15  "format": "executive",
16  "output": "pdf"
17}
18
19# Get report download URL
20curl -X GET "https://api.agnech.com/v1/report/report_xyz789" \
21  -H "Authorization: Bearer YOUR_API_KEY"
22
23# Response
24{
25  "id": "report_xyz789",
26  "status": "ready",
27  "download_url": "https://api.agnech.com/v1/report/report_xyz789/download",
28  "expires_at": "2024-01-16T10:30:00Z"
29}

WebhooksEnterprise

Receive real-time notifications when scans complete or findings are detected.

Webhooks

Bash

1# Register a webhook
2curl -X POST "https://api.agnech.com/v1/webhook" \
3  -H "Authorization: Bearer YOUR_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "url": "https://your-app.com/webhooks/bloodhound",
7    "events": ["scan.completed", "finding.critical"],
8    "secret": "your_webhook_secret"
9  }'
10
11# Webhook payload example
12{
13  "event": "scan.completed",
14  "timestamp": "2024-01-15T10:31:35Z",
15  "data": {
16    "scan_id": "scan_abc123",
17    "status": "completed",
18    "findings_count": 12,
19    "critical_count": 2
20  }
21}

SDKs

Use our official SDKs for easier integration.

Node.js / TypeScript

TypeScript

npm install @agnech/sdk

import { BloodhoundClient } from '@agnech/sdk';

const client = new BloodhoundClient({
  apiKey: process.env.BLOODHOUND_API_KEY
});

const scan = await client.scan({
  repository: 'https://github.com/user/repo',
  mode: 'advanced'
});

const results = await scan.waitForCompletion();
console.log(results.summary);

Python

pip install bloodhound-sdk

from bloodhound import Client

client = Client(api_key=os.environ['BLOODHOUND_API_KEY'])

scan = client.scan(
    repository='https://github.com/user/repo',
    mode='advanced'
)

results = scan.wait_for_completion()
print(results.summary)