New api
Corgea API Reference
This document provides detailed information about the Corgea API endpoints. The API allows you to programmatically interact with Corgea’s scanning and vulnerability management features.
Authentication
Most endpoints require authentication using a Corgea token that should be included in the CORGEA-TOKEN
header. You can obtain a token from your Corgea account settings.
Endpoints
Verify Token API
Description: Verifies the provided token and returns the status.
Endpoint: /verify/<str:token>
HTTP Method: GET
Request Headers: None
Request Parameters:
Path Parameters:
token
(string): The token to be verified. Query Parameters: None Request Body: None Response: Status Codes:- 200: Token is valid.
- 400: Invalid token. Response Body:
or
Example Usage:
Scan Upload API
Description: Uploads a scan report for a given run ID.
Endpoint: /scan-upload
HTTP Method: POST
Request Headers:
CORGEA-TOKEN
: API key for authentication. Request Parameters: Query Parameters:run_id
(string): The ID of the run associated with the scan report.engine
(string): The engine used for the scan.project
(string): The name of the project. Request Body: The scan report file. Response: Status Codes:- 200: Scan report uploaded successfully.
- 400: Invalid request or content. Response Body:
or
Example Usage:
Start Scan API
Description: Initiates a new scan or continues an existing scan with a transfer ID. The Start Scan API supports chunked file uploads for large codebases by allowing you to split the upload into multiple requests.
For new scans, you must first initiate the scan with a POST request. Currently, only “blast” scan type is supported, which requires uploading a single source code file. Your company account must have blast scanning enabled to use this feature.
To upload a file, it must be divided into chunks. You can continue the upload process using PATCH requests with a transfer ID. Each chunk should be sent as a ‘chunk_data’ file parameter.
Endpoint:
/start-scan
(for new scans)/start-scan/<str:transfer_id>/
(for continuing existing scans)
HTTP Method:
- POST (for new scans)
- PATCH (for continuing existing scans)
- HEAD (to check upload status)
Request Headers:
CORGEA-TOKEN
: API key for authentication.
Request Parameters: Path Parameters:
transfer_id
(string, optional): The transfer ID for continuing an existing scan upload.
Query Parameters: None
Request Body: For new scans (POST):
scan_type
(string): Currently only “blast” is supported.repo_url
(string): The URL of the repository.branch
(string): The branch to be scanned.sha
(string): The commit SHA to be scanned.files
(file): Single source code file to be scanned. Multiple files are not supported.
For continuing existing scans (PATCH):
chunk_data
(file): The next chunk of data for the scan.
Response: Status Codes:
- 200: Scan initiated or continued successfully.
- 400: Invalid request or content. Common errors include:
- Blast scanning not enabled for your account
- No files uploaded
- Multiple files uploaded (only single file supported)
- Invalid scan type (only “blast” supported)
- Missing chunk_data file
- Other scan initialization failures
Here are some example responses for the /start-scan
and /start-scan/<str:transfer_id>/
endpoints. These responses cover the different scenarios handled by the endpoint, including successful scan initiation, file upload errors, invalid request methods, and upload status checks. The responses are formatted as JSON objects with appropriate status codes and error messages.
POST /start-scan (New Scan)
Success Response (200 OK):
Error Responses (400 Bad Request):
PATCH /start-scan/transfer_id/ (Continue Existing Scan)
Success Response (200 OK):
Response headers should include Upload-Offset
looks like this
Success Response (200 OK): Once the full chunk is uploaded, the response will include a scan_id
instead of a transfer_id
.
This occurs when the Upload-Offset
in the response headers matches the Upload-Length
in the request headers.
You can use the scan_id
to retrieve more scan-specific details using other APIs.
Request headers should look like
Response header should have
Error Response (400 Bad Request):
HEAD /start-scan/transfer_id/ (Check Upload Status)
Success Response (200 OK):
Error Response (400 Bad Request):
Get Scans API
Description: Retrieves a list of scans for the authenticated user’s company.
Endpoint: /scans
HTTP Method: GET
Request Headers:
CORGEA-TOKEN
: API key for authentication. Request Parameters: Query Parameters:project
(string, optional): Filter scans by project name.page
(integer, optional): The page number for pagination (default: 1).page_size
(integer, optional): The number of results per page (default: 20, max: 50). Request Body: None Response: Status Codes:- 200: Scans retrieved successfully. Response Body:
Example Usage:
Get Scan API
Description: Retrieves details of a specific scan.
Endpoint: /scan/<str:scan_id>
HTTP Method: GET
Request Headers:
CORGEA-TOKEN
: API key for authentication. Request Parameters: Path Parameters:scan_id
(string): The ID of the scan. Query Parameters: None Request Body: None Response: Status Codes:- 200: Scan details retrieved successfully.
- 404: Scan not found. Response Body:
or
Example Usage:
Get Issues for Scan API
Description: Retrieves a list of issues for a specific scan.
Endpoint: /scan/<str:scan_id>/issues
HTTP Method: GET
Request Headers:
CORGEA-TOKEN
: API key for authentication. Request Parameters: Path Parameters:scan_id
(string): The ID of the scan. Query Parameters:page
(integer, optional): The page number for pagination (default: 1).page_size
(integer, optional): The number of results per page (default: 20, max: 50). Request Body: None Response: Status Codes:- 200: Issues retrieved successfully.
- 404: Scan not found. Response Body:
or
Example Usage:
Get Issue API
Description: Retrieves details of a specific issue.
Endpoint: /issue/<str:issue_id>
HTTP Method: GET
Request Headers:
CORGEA-TOKEN
: API key for authentication. Request Parameters: Path Parameters:issue_id
(string): The ID of the issue. Query Parameters:show_full_code
(boolean, optional): Whether to include the full code in the response (default: false). Request Body: None Response: Status Codes:- 200: Issue details retrieved successfully.
- 404: Issue not found. Response Body:
or
Example Usage: