API Reference
ByteHide Radar provides a REST API that allows you to programmatically trigger scans, retrieve findings, and integrate security testing into your development workflow. The API uses your project token for authentication.
Authentication
Include your project token in the Authorization header of every request:
CODE
Authorization: Bearer {project-token}Authorization: Bearer {project-token}Find your token on the Project Settings page. Click the copy icon to copy it.
Protect Your Token
Treat your project token as a secret. Do not hardcode it in source code or commit it to version control. Use environment variables or a secret management tool.
Base URL
CODE
https://api.bytehide.com/v1/radarhttps://api.bytehide.com/v1/radarEndpoints
Trigger Scan
CODE
POST /projects/{projectId}/scansPOST /projects/{projectId}/scansRequest Body:
| Parameter | Type | Required | Description |
|---|---|---|---|
branch | string | No | Branch to scan. Defaults to the project's configured default branch |
Response:
| Field | Type | Description |
|---|---|---|
scanId | string | Unique identifier for the initiated scan |
status | string | Initial scan status (queued) |
estimatedCompletionTime | string | Estimated time for scan completion |
Get Scan Status
CODE
GET /projects/{projectId}/scans/{scanId}GET /projects/{projectId}/scans/{scanId}Response:
| Field | Type | Description |
|---|---|---|
scanId | string | Unique identifier of the scan |
status | string | queued, in_progress, completed, or failed |
startTime | string | ISO 8601 timestamp when the scan started |
endTime | string | ISO 8601 timestamp when the scan finished (null if running) |
findings | object | Finding counts by type: sast, sca, secrets |
List Findings
CODE
GET /projects/{projectId}/findingsGET /projects/{projectId}/findingsQuery Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | No | Filter by type: sast, sca, secrets |
severity | string | No | Filter: critical, high, medium, low |
status | string | No | Filter: open, fixed, ignored, false_positive |
page | integer | No | Page number (default: 1) |
per_page | integer | No | Results per page (default: 25, max: 100) |
Response:
| Field | Type | Description |
|---|---|---|
total | integer | Total findings matching filters |
page | integer | Current page number |
per_page | integer | Results per page |
findings | array | Array of finding objects |
Get Finding Detail
CODE
GET /projects/{projectId}/findings/{findingId}GET /projects/{projectId}/findings/{findingId}Response:
| Field | Type | Description |
|---|---|---|
findingId | string | Unique identifier |
fingerprint | string | Stable fingerprint for tracking across scans |
title | string | Vulnerability title |
description | string | Detailed description |
severity | string | Severity level |
status | string | Current status |
location | object | File path, line number, and code snippet |
cwe | array | CWE identifiers (SAST findings) |
cve | array | CVE identifiers (SCA findings) |
aiExplanation | string | AI-generated contextual analysis |
Update Finding Status
CODE
PATCH /projects/{projectId}/findings/{findingId}PATCH /projects/{projectId}/findings/{findingId}Request Body:
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | Yes | New status: ignored or false_positive |
Returns the updated finding object.
Get Project Summary
CODE
GET /projects/{projectId}/summaryGET /projects/{projectId}/summaryResponse:
| Field | Type | Description |
|---|---|---|
totalFindings | object | Finding counts by type and severity |
openFindings | integer | Total open findings |
fixedFindings | integer | Total fixed findings |
scanHistory | array | Recent scan results with timestamps and counts |
trends | object | Finding trend data over time |
Example Workflow
Bash
# Trigger a scan
curl -X POST https://api.bytehide.com/v1/radar/projects/{projectId}/scans \
-H "Authorization: Bearer {project-token}" \
-H "Content-Type: application/json" \
-d '{"branch": "main"}'
# Check scan status
curl https://api.bytehide.com/v1/radar/projects/{projectId}/scans/{scanId} \
-H "Authorization: Bearer {project-token}"
# List critical findings
curl "https://api.bytehide.com/v1/radar/projects/{projectId}/findings?severity=critical&status=open" \
-H "Authorization: Bearer {project-token}"
# Get a specific finding with AI explanation
curl https://api.bytehide.com/v1/radar/projects/{projectId}/findings/{findingId} \
-H "Authorization: Bearer {project-token}"
# Mark a finding as false positive
curl -X PATCH https://api.bytehide.com/v1/radar/projects/{projectId}/findings/{findingId} \
-H "Authorization: Bearer {project-token}" \
-H "Content-Type: application/json" \
-d '{"status": "false_positive"}'# Trigger a scan
curl -X POST https://api.bytehide.com/v1/radar/projects/{projectId}/scans \
-H "Authorization: Bearer {project-token}" \
-H "Content-Type: application/json" \
-d '{"branch": "main"}'
# Check scan status
curl https://api.bytehide.com/v1/radar/projects/{projectId}/scans/{scanId} \
-H "Authorization: Bearer {project-token}"
# List critical findings
curl "https://api.bytehide.com/v1/radar/projects/{projectId}/findings?severity=critical&status=open" \
-H "Authorization: Bearer {project-token}"
# Get a specific finding with AI explanation
curl https://api.bytehide.com/v1/radar/projects/{projectId}/findings/{findingId} \
-H "Authorization: Bearer {project-token}"
# Mark a finding as false positive
curl -X PATCH https://api.bytehide.com/v1/radar/projects/{projectId}/findings/{findingId} \
-H "Authorization: Bearer {project-token}" \
-H "Content-Type: application/json" \
-d '{"status": "false_positive"}'Rate Limits
| Endpoint Category | Limit |
|---|---|
| General API requests | 100 requests per minute |
| Scan triggers | 10 per hour |
If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header. For increased limits on Enterprise plans, contact ByteHide support.
Error Handling
| Status Code | Meaning |
|---|---|
200 OK | Request succeeded |
201 Created | Resource created |
400 Bad Request | Invalid parameters |
401 Unauthorized | Invalid or expired token |
404 Not Found | Project or finding not found |
429 Too Many Requests | Rate limit exceeded |
500 Internal Server Error | Retry after a short delay |
Error responses include a JSON body:
JSON
{
"error": "Invalid project token",
"code": "UNAUTHORIZED",
"message": "The provided token is invalid or has been revoked."
}{
"error": "Invalid project token",
"code": "UNAUTHORIZED",
"message": "The provided token is invalid or has been revoked."
}API vs Dashboard
The API is designed for automation and CI/CD integration. For interactive use, the ByteHide Cloud dashboard provides visual charts, filtering, and one-click actions.
Next Steps
CI/CD Integration
Integrate Radar into your build pipeline for automated security scanning.
Project Settings
Find your project token and configure project-level settings.