{ "openapi": "3.0.0", "info": { "title": "Corgea API", "version": "1.0.0", "description": "API for interacting with Corgea's scanning and vulnerability management features" }, "servers": [ { "url": "https://www.corgea.app/api/v1", "description": "Production server" } ], "security": [ { "CorgeaToken": [] }, { "BearerAuth": [] } ], "paths": { "/verify/{token}": { "get": { "summary": "Verify Token (Deprecated)", "operationId": "verifyTokenDeprecated", "tags": [ "Authentication" ], "security": [], "deprecated": true, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The token to be verified" } ], "responses": { "200": { "description": "Token is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } }, "400": { "description": "Invalid token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" } } } } } } } } }, "/verify": { "get": { "summary": "Verify Token", "operationId": "verifyToken", "tags": [ "Authentication" ], "description": "Verify the API token and optionally return user information", "parameters": [ { "name": "user_info", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include user information in the response" } ], "responses": { "200": { "description": "Token is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "user": { "type": "object", "description": "User information (only included if user_info=true)", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } } } } }, "401": { "description": "Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" } } } } } } } } }, "/auth/logins": { "get": { "summary": "Get Login Attempts", "operationId": "getAuthLogins", "tags": [ "Authentication" ], "description": "Retrieve successful login attempts for users", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 20 }, "description": "The number of results per page" }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include logins after this ISO 8601 timestamp" }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include logins before this ISO 8601 timestamp" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by username" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order for results" } ], "responses": { "200": { "description": "Login attempts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_logins": { "type": "integer" }, "logins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "user_id": { "type": "integer" }, "user_agent": { "type": "string" }, "path": { "type": "string" } } } } } } } } }, "401": { "description": "Invalid or missing token" }, "403": { "description": "Insufficient permissions" } } } }, "/auth/failed-logins": { "get": { "summary": "Get Failed Login Attempts", "operationId": "getAuthFailedLogins", "tags": [ "Authentication" ], "description": "Retrieve failed login attempts for users", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include failed logins after this ISO 8601 timestamp" }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include failed logins before this ISO 8601 timestamp" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by username" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order for results" } ], "responses": { "200": { "description": "Failed login attempts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_failed_logins": { "type": "integer" }, "failed_logins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "user_id": { "type": "integer" }, "user_agent": { "type": "string" }, "path": { "type": "string" } } } } } } } } }, "401": { "description": "Invalid or missing token" }, "403": { "description": "Insufficient permissions" } } } }, "/users/{user_id}/logins": { "get": { "summary": "Get User Login Attempts", "operationId": "getUserLogins", "tags": [ "Authentication" ], "description": "Retrieve successful login attempts for a specific user", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User ID to fetch logins for" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include logins after this ISO 8601 timestamp" }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include logins before this ISO 8601 timestamp" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order for results" } ], "responses": { "200": { "description": "Login attempts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_logins": { "type": "integer" }, "logins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "user_agent": { "type": "string" }, "path": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid user ID format" }, "401": { "description": "Invalid or missing token" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "User not found" } } } }, "/users/{user_id}/failed-logins": { "get": { "summary": "Get User Failed Login Attempts", "operationId": "getUserFailedLogins", "tags": [ "Authentication" ], "description": "Retrieve failed login attempts for a specific user", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User ID to fetch failed logins for" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include failed logins after this ISO 8601 timestamp" }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only include failed logins before this ISO 8601 timestamp" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order for results" } ], "responses": { "200": { "description": "Failed login attempts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_failed_logins": { "type": "integer" }, "failed_logins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "user_agent": { "type": "string" }, "path": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid user ID format" }, "401": { "description": "Invalid or missing token" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "User not found" } } } }, "/scans": { "get": { "summary": "Get Scans", "operationId": "getScans", "tags": [ "Scans" ], "description": "Retrieves a list of scans for the authenticated user's company", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter scans by project name" }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter scans by repository URL substring" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter scans by exact branch name" }, { "name": "pull_request_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter scans by exact pull request or merge request identifier" }, { "name": "sha", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter scans by exact commit SHA" }, { "name": "metadata_key", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter scans that contain this metadata key. Combine with metadata_value to match an exact key and value." }, { "name": "metadata_value", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match an exact value for metadata_key, or search across scan metadata when used alone." }, { "name": "triggered_by", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter scans by the user who triggered them. Use an email address or \"current_user\"." }, { "name": "scan_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "partial" ] }, "description": "Filter scans by type. Use \"full\" for full scans or \"partial\" for scans limited to selected files." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" } ], "responses": { "200": { "description": "Scans retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_scans": { "type": "integer", "description": "Total number of scans matching the request across all pages" }, "scans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "engine": { "type": "string", "example": "corgea" }, "project": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "repo": { "type": "string" }, "branch": { "type": "string" }, "status": { "type": "string", "enum": [ "scanning", "processing", "complete", "incomplete" ], "description": "Scan progress. \"scanning\" and \"processing\" are in-flight states, \"complete\" means the scan finished, and \"incomplete\" means it failed." }, "pull_request_id": { "type": "string", "nullable": true }, "git_sha": { "type": "string", "nullable": true, "description": "Commit SHA associated with the scan" }, "worktree_dirty": { "type": "boolean", "nullable": true, "description": "Whether the scan included uncommitted local changes. Null for scans created without a worktree state signal." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "User-supplied metadata associated with the scan" } } } } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/scan/{scan_id}": { "get": { "summary": "Get Scan", "operationId": "getScan", "tags": [ "Scans" ], "description": "Retrieves details of a specific scan", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" } ], "responses": { "200": { "description": "Scan details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project": { "type": "string" }, "repo": { "type": "string" }, "branch": { "type": "string" }, "status": { "type": "string", "enum": [ "scanning", "processing", "complete", "incomplete" ], "description": "Scan progress. \"scanning\" and \"processing\" are in-flight states, \"complete\" means the scan finished, and \"incomplete\" means it failed." }, "engine": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "time_taken": { "type": "number", "nullable": true, "description": "Scan duration in seconds, or null until the scan finishes processing" }, "git_sha": { "type": "string", "nullable": true, "description": "Commit SHA associated with the scan" }, "worktree_dirty": { "type": "boolean", "nullable": true, "description": "Whether the scan included uncommitted local changes. Null for scans created without a worktree state signal." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "User-supplied metadata associated with the scan" } } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Scan doesn't exist" } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/scan/{scan_id}/report": { "get": { "summary": "Get Scan Report", "operationId": "getScanReport", "tags": [ "Scans", "Reports" ], "description": "Retrieve a scan report in HTML, SARIF, Markdown, or PDF format. PDF reports are available after a scan completes, including scans with no findings. format=pdf accepts only urgency and classification filters; other filters return 400. Reports with more than 500 findings are generated asynchronously and return 202 with a poll_url that includes a job parameter. Poll the same endpoint with format=pdf and job until the PDF is ready.", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sarif", "html", "markdown", "pdf" ], "default": "sarif" }, "description": "Report format (html, sarif, markdown, or pdf)" }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "default": "cwe" }, "description": "View type for HTML reports" }, { "name": "urgency", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": ["CR", "HI", "ME", "LO"] } }, "style": "form", "explode": true, "description": "Repeatable urgency filter. PDF reports accept CR, HI, ME, and LO." }, { "name": "classification", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Repeatable finding classification filter for PDF reports. Matching is case-insensitive and accepts prefixes such as CWE-79." }, { "name": "job", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "PDF export job ID returned in a 202 response. Poll the same endpoint with format=pdf and this job value until the report is ready." } ], "responses": { "200": { "description": "Report retrieved successfully", "content": { "application/json": { "schema": { "description": "SARIF report when format=sarif", "type": "object" } }, "text/html": { "schema": { "type": "string", "description": "HTML report when format=html" } }, "text/markdown": { "schema": { "type": "string", "description": "Markdown report when format=markdown. Issue entries include the issue assignee when available." } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "Branded scan report when format=pdf" } } }, "headers": { "Content-Disposition": { "description": "Filename for downloadable report formats", "schema": { "type": "string" } } } }, "202": { "description": "PDF report generation is in progress. Retry the poll_url after the number of seconds in Retry-After.", "headers": { "Retry-After": { "schema": {"type": "integer", "example": 5}, "description": "Seconds to wait before polling again" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "example": "generating"}, "job_id": {"type": "string"}, "findings": {"type": "integer", "description": "Number of findings; returned when generation starts"}, "poll_url": {"type": "string", "description": "URL to poll; returned when generation starts"}, "retry_after_seconds": {"type": "integer", "example": 5} } } } } }, "400": { "description": "PDF report is unavailable while the scan is running, or a filter is empty, unknown, or unsupported", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "example": "error"}, "message": {"type": "string"} } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Scan not found" } } } } } }, "500": { "description": "Report generation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "SARIF export failed. Please try again later or contact support." } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/scan/{scan_id}/check_blocking_rules": { "get": { "summary": "Check Blocking Rules", "operationId": "checkBlockingRules", "tags": [ "Scans", "Policies" ], "description": "Check if scan issues violate any blocking rules", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" } ], "responses": { "200": { "description": "Blocking rules check completed", "content": { "application/json": { "schema": { "type": "object", "required": [ "block", "status", "blocking_issues", "stats", "page", "total_pages" ], "properties": { "block": { "type": "boolean", "description": "Whether the scan is blocked by any rules" }, "status": { "type": "string", "enum": [ "pending", "complete" ], "description": "Whether blocking-rule evaluation is still waiting for dependency license data or is complete" }, "blocking_issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "The blocked item type; license violations are returned as dependency" }, "triggered_by_rules": { "type": "array", "items": { "type": "string" } } } } }, "stats": { "type": "object", "properties": { "total_issues": { "type": "integer" }, "blocked_issues": { "type": "integer" } } }, "page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "SAST scan not found" } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/issues": { "get": { "summary": "List All Issues", "operationId": "listIssues", "tags": [ "Issues" ], "description": "Retrieve a list of all security issues for the authenticated user's company", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter issues by project name" }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter issues by repository URL" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter issues by branch name" }, { "name": "triggered_by", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter issues to the latest scan triggered by a specific user. Use an email address or \"current_user\"." }, { "name": "scan_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "partial" ] }, "description": "Filter issues to the latest scan by scan type. Use \"full\" or \"partial\"." }, { "name": "show_false_positives", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include issues marked as false positives (manual or AI). By default false positives are excluded." }, { "name": "include_reachability", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include endpoint reachability summary for each issue." }, { "name": "file_path_exact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by an exact file path. Unlike file_path, this does not match paths that merely contain the value, which makes it safe for drilling into a file group returned by the groups endpoint.", "example": "src/api/auth.py" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across classification and file path", "example": "sql injection" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" } ], "responses": { "200": { "description": "Issues retrieved successfully or no project found", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "no_project_found" } } } ] } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/issues/groups": { "get": { "summary": "List Security Issue Groups", "operationId": "listSecurityIssueGroups", "tags": [ "Issues" ], "description": "Retrieve security issues collapsed into groups with a count per group, so a client can render a summary without downloading every issue. Accepts the same filters as GET /issues. Drill into a group by re-issuing those filters against GET /issues with cwe or file_path_exact.", "parameters": [ { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cwe", "file_path" ], "default": "cwe" }, "description": "How to group the issues. cwe groups by CWE classification, file_path groups by the exact file each issue was found in.", "example": "file_path" }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include per-urgency and per-status counts on each group" }, { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter issues by project name" }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter issues by repository URL" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter issues by branch name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "The number of groups per page" } ], "responses": { "200": { "description": "Issue groups retrieved successfully or no project found", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_groups": { "type": "integer" }, "groups": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/IssueCweGroup" }, { "$ref": "#/components/schemas/IssueFileGroup" } ] } } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "no_project_found" } } } ] } } } }, "400": { "description": "Invalid group_by value" } } } }, "/issues/code-quality": { "get": { "summary": "List Code Quality Issues", "operationId": "listCodeQualityIssues", "tags": [ "Issues" ], "description": "Retrieve code quality findings separately from security issues. Classification values are code quality labels, such as Maintainability, rather than CWEs.", "parameters": [ { "name": "project", "in": "query", "schema": { "type": "string" }, "description": "Filter issues by project name" }, { "name": "repo", "in": "query", "schema": { "type": "string" }, "description": "Filter issues by repository URL" }, { "name": "branch", "in": "query", "schema": { "type": "string" }, "description": "Filter issues by branch name" }, { "name": "classification", "in": "query", "schema": { "type": "string" }, "description": "Filter by code quality classification label (partial match)", "example": "Maintainability" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Code quality issues retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } } } } } } } } } }, "/scan/{scan_id}/issues/quality": { "get": { "summary": "Get Code Quality Issues for Scan", "operationId": "getScanCodeQualityIssues", "tags": [ "Issues" ], "description": "Retrieve code quality findings for a specific scan.", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" }, { "name": "classification", "in": "query", "schema": { "type": "string" }, "description": "Filter by code quality classification label (partial match)", "example": "Maintainability" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Code quality issues retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } } } } } } }, "404": { "description": "Scan not found" } } } }, "/scan/{scan_id}/issues": { "get": { "summary": "Get Issues for Scan", "operationId": "getScanIssues", "tags": [ "Issues" ], "description": "Retrieves a list of issues for a specific scan", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "urgency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by urgency levels (comma-separated). Valid values: CR, HI, ME, LO", "example": "CR,HI" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by status (comma-separated). Valid values: fixed, false_positive, accepted_risk, open, fix_in_progress, duplicate", "example": "open,fix_in_progress" }, { "name": "show_false_positives", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include issues marked as false positives (manual or AI). By default false positives are excluded.", "example": true }, { "name": "include_reachability", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include endpoint reachability summary for each issue." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by programming language (case-insensitive)", "example": "python" }, { "name": "file_path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by file path (partial match)", "example": "src/auth" }, { "name": "classification", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by classification/CWE (partial match)", "example": "CWE-89" }, { "name": "sla_status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by SLA status (comma-separated). Valid values: overdue, escalated", "example": "overdue" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "urgency", "-urgency", "status", "-status", "classification", "-classification" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "-created_at" } ], "responses": { "200": { "description": "Issues retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } } } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Scan not found" } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/scan/{scan_id}/issues/groups": { "get": { "summary": "List Security Issue Groups for a Scan", "operationId": "listSecurityIssueGroupsForScan", "tags": [ "Issues", "Scans" ], "description": "Retrieve a scan's security issues collapsed into groups with a count per group, so a client can render a summary without downloading every issue. Accepts the same filters as GET /scan/{scan_id}/issues.", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The scan to group issues for" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cwe", "file_path" ], "default": "cwe" }, "description": "How to group the issues. cwe groups by CWE classification, file_path groups by the exact file each issue was found in.", "example": "file_path" }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include per-urgency and per-status counts on each group" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "The number of groups per page" } ], "responses": { "200": { "description": "Issue groups retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_groups": { "type": "integer" }, "groups": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/IssueCweGroup" }, { "$ref": "#/components/schemas/IssueFileGroup" } ] } } } } } } }, "400": { "description": "Invalid group_by value" }, "404": { "description": "Scan not found" } } } }, "/scan/{scan_id}/issues/sca/groups": { "get": { "summary": "List SCA Issue Groups for a Scan", "operationId": "listScaIssueGroupsForScan", "tags": [ "Issues", "SCA", "Scans" ], "description": "Retrieve a scan's SCA issues collapsed into groups with a count per group, so a client can render a summary without downloading every issue. Accepts the same filters as GET /scan/{scan_id}/issues/sca.", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The scan to group SCA issues for" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "package" ], "default": "package" }, "description": "How to group the SCA issues. Currently only package is supported." }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include per-severity and per-status counts on each group" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "The number of groups per page" } ], "responses": { "200": { "description": "SCA issue groups retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_groups": { "type": "integer" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/SCAIssuePackageGroup" } } } } } } }, "400": { "description": "Invalid group_by value" }, "404": { "description": "Scan not found" } } } }, "/issue/{issue_id}": { "get": { "summary": "Get Issue", "operationId": "getIssue", "tags": [ "Issues" ], "description": "Retrieves details of a specific issue", "parameters": [ { "name": "issue_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the issue" }, { "name": "show_full_code", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include the full code in the response" }, { "name": "include_reachability", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include endpoint reachability details for the issue." }, { "name": "generate_fix", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Whether to start generating an eligible missing fix in the background. Set to false to return the current issue state without starting fix generation." }, { "name": "wait_for_the_fix", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Wait for background fix generation before returning. Only applies when generate_fix is true and an eligible fix is missing. The wait is bounded (120 seconds by default); if generation is still pending, the response reports generating. Fetch the issue again to check for the completed fix." } ], "responses": { "200": { "description": "Issue details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "issue": { "$ref": "#/components/schemas/IssueDetail" } } } } } }, "404": { "description": "Issue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Issue not found" } } } } } } } } }, "/issues/sca/{issue_id}": { "get": { "summary": "Get SCA Issue", "operationId": "getScaIssue", "tags": [ "Issues", "SCA" ], "description": "Retrieve details for a specific Software Composition Analysis (SCA) issue, including dependency reachability information.", "parameters": [ { "name": "issue_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the SCA issue" } ], "responses": { "200": { "description": "SCA issue details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "issue": { "$ref": "#/components/schemas/SCAIssueDetail" } } } } } }, "404": { "description": "SCA issue not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "SCA issue not found" } } } } } } } } }, "/issues/sca": { "get": { "summary": "Get SCA Issues", "operationId": "listScaIssues", "tags": [ "Issues", "SCA" ], "description": "Retrieve a list of Software Composition Analysis (SCA) issues", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter SCA issues by project name" }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter SCA issues by repository URL" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter SCA issues by branch name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by severity levels (comma-separated). Valid values: CRITICAL, HIGH, MEDIUM, LOW", "example": "CRITICAL,HIGH" }, { "name": "package", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package name (partial match)", "example": "lodash" }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package ecosystem (case-insensitive)", "example": "npm" }, { "name": "cve", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by CVE identifier (partial match)", "example": "CVE-2021" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by file path (partial match)", "example": "package.json" }, { "name": "has_fix", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by whether a fix is available (true/false)", "example": true }, { "name": "reachability", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "not_direct_dependency", "pending", "vulnerable_usage_reachable", "vulnerable_usage_unreachable", "dead_dependency" ] }, "description": "Filter SCA issues by dependency reachability status", "example": "vulnerable_usage_reachable" }, { "name": "include_reachability", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include dependency reachability status and description for each SCA issue." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "severity", "-severity", "package", "-package", "ecosystem", "-ecosystem" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "-severity" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by triage status (comma-separated). Valid values: open, fixed, false_positive, accepted_risk, duplicate", "example": "open" }, { "name": "package_exact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by an exact package name. Unlike package, this does not match packages that merely contain the value (lodash will not match lodash.merge), which makes it safe for drilling into a package group.", "example": "lodash" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across package name, CVE identifier, summary, details, path and classification", "example": "lodash" } ], "responses": { "200": { "description": "SCA issues retrieved successfully or no project found", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/SCAIssue" } } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "no_project_found" } } } ] } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/issues/sca/groups": { "get": { "summary": "List SCA Issue Groups", "operationId": "listScaIssueGroups", "tags": [ "Issues", "SCA" ], "description": "Retrieve SCA issues collapsed into groups with a count per group, so a client can render a summary without downloading every issue. Accepts the same filters as GET /issues/sca. Drill into a group by re-issuing those filters against GET /issues/sca with package_exact.", "parameters": [ { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "package" ], "default": "package" }, "description": "How to group the SCA issues. Currently only package is supported." }, { "name": "breakdown", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include per-severity and per-status counts on each group" }, { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter SCA issues by project name" }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter SCA issues by repository URL" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter SCA issues by branch name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "The number of groups per page" } ], "responses": { "200": { "description": "SCA issue groups retrieved successfully or no project found", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_groups": { "type": "integer" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/SCAIssuePackageGroup" } } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "no_project_found" } } } ] } } } }, "400": { "description": "Invalid group_by value" } } } }, "/issues/iac": { "get": { "summary": "Get IaC Issues", "operationId": "listIacIssues", "tags": [ "Issues", "IaC" ], "description": "Retrieve Infrastructure-as-Code (IaC) security issues from the latest matching processed scan.", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by project name" }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by repository URL" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by branch name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by severity levels (comma-separated). Valid values: CRITICAL, HIGH, MEDIUM, LOW", "example": "CRITICAL,HIGH" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by cloud or platform provider", "example": "aws" }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by affected service", "example": "s3" }, { "name": "iac_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by IaC format", "example": "terraform" }, { "name": "rule_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by rule identifier", "example": "AVD-AWS-0001" }, { "name": "avd_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by AVD identifier", "example": "AVD-AWS-0001" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by file path (partial match)", "example": "infra/main.tf" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search across title, description, message, rule ID, and AVD ID", "example": "encryption" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "severity", "-severity", "provider", "-provider", "service", "-service", "path", "-path" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "-severity" } ], "responses": { "200": { "description": "Get IaC Issues retrieved successfully or no project found", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/IaCIssue" } } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "no_project_found" } } } ] } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/triage/findings": { "patch": { "summary": "Bulk triage findings", "operationId": "bulkTriageFindings", "tags": ["Triage"], "x-mint": {"href": "/api-reference/triage/bulk-triage-findings"}, "description": "Preview or apply a rule-based status change to as many as 5,000 accessible SAST or SCA findings. Accepted-risk actions that meet the company's approval threshold return 202 and remain pending until a different company admin approves them.", "requestBody": { "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/BulkTriageRequest"} } } }, "responses": { "200": { "description": "Action previewed or applied", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TriageActionResponse"}}} }, "202": { "description": "Action created and awaiting approval", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TriageActionResponse"}}} }, "400": {"description": "Invalid request or more than 5,000 findings matched"}, "403": {"description": "The token lacks permission to change one or more selected finding types"} } } }, "/triage/actions/{action_id}": { "get": { "summary": "Get a triage action", "operationId": "getTriageAction", "tags": ["Triage"], "description": "Retrieve a bulk triage action and its paginated, immutable finding audit records.", "parameters": [ {"name": "action_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1, "default": 1}}, {"name": "page_size", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}} ], "responses": { "200": { "description": "Triage action and finding audit records", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TriageActionDetailResponse"}}} }, "400": {"description": "Invalid pagination parameters"}, "404": {"description": "Action not found or not accessible"} } }, "patch": { "summary": "Review a triage action", "operationId": "reviewTriageAction", "tags": ["Triage"], "description": "Approve or reject a pending action. The reviewer must be a different company admin with permission to change every selected finding type.", "parameters": [ {"name": "action_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "required": ["decision"], "additionalProperties": false, "properties": {"decision": {"type": "string", "enum": ["approve", "reject"]}} }}} }, "responses": { "200": { "description": "Action approved and applied, or rejected", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TriageActionResponse"}}} }, "400": {"description": "Invalid decision or action state"}, "403": {"description": "Reviewer is not an eligible company admin"}, "404": {"description": "Action not found"} } } }, "/triage/approval-policy": { "get": { "summary": "Get the triage approval policy", "operationId": "getTriageApprovalPolicy", "tags": ["Triage"], "description": "Return the accepted-risk thresholds that require approval. Company admin access is required.", "responses": { "200": {"description": "Current approval policy", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TriageApprovalPolicyResponse"}}}}, "403": {"description": "Company admin access is required"} } }, "patch": { "summary": "Update the triage approval policy", "operationId": "updateTriageApprovalPolicy", "tags": ["Triage"], "description": "Partially update the accepted-risk approval thresholds. Set a threshold to null to disable it. Company admin access is required.", "requestBody": { "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TriageApprovalPolicy"}}} }, "responses": { "200": {"description": "Updated approval policy", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TriageApprovalPolicyResponse"}}}}, "400": {"description": "Invalid threshold or unknown field"}, "403": {"description": "Company admin access is required"} } } }, "/dependencies": { "get": { "summary": "Get Dependencies", "operationId": "listDependencies", "tags": [ "Dependencies" ], "description": "Retrieve software dependencies (SBOM) from the latest matching processed scan.", "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by project name" }, { "name": "repo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by repository URL" }, { "name": "branch", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by branch name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by dependency name (partial match)", "example": "django" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by dependency version", "example": "4.2.0" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by dependency ecosystem or package type", "example": "pypi" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by file path (partial match)", "example": "requirements.txt" }, { "name": "purl", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package URL (partial match)", "example": "pkg:pypi/django" }, { "name": "license", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by license", "example": "MIT" }, { "name": "dep_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "direct", "transitive", "all" ], "default": "all" }, "description": "Filter by dependency relationship type", "example": "direct" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search across dependency name, version, and package URL", "example": "lodash" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "version", "-version", "type", "-type", "created_at", "-created_at" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "name" } ], "responses": { "200": { "description": "Get Dependencies retrieved successfully or no project found", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_dependencies": { "type": "integer" }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/Dependency" } } } }, { "type": "object", "properties": { "status": { "type": "string", "example": "no_project_found" } } } ] } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } }, "400": { "description": "Invalid dependency type filter", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid dep_type. Must be one of: direct, transitive, all." } } } } } } } } }, "/scan/{scan_id}/issues/sca": { "get": { "summary": "Get SCA Issues for Scan", "operationId": "getScanScaIssues", "tags": [ "Issues", "SCA" ], "description": "Retrieve SCA issues for a specific scan", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by severity levels (comma-separated). Valid values: CRITICAL, HIGH, MEDIUM, LOW", "example": "CRITICAL,HIGH" }, { "name": "package", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package name (partial match)", "example": "lodash" }, { "name": "ecosystem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package ecosystem (case-insensitive)", "example": "npm" }, { "name": "cve", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by CVE identifier (partial match)", "example": "CVE-2021" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by file path (partial match)", "example": "package.json" }, { "name": "has_fix", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by whether a fix is available (true/false)", "example": true }, { "name": "reachability", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "not_direct_dependency", "pending", "vulnerable_usage_reachable", "vulnerable_usage_unreachable", "dead_dependency" ] }, "description": "Filter SCA issues by dependency reachability status", "example": "vulnerable_usage_reachable" }, { "name": "include_reachability", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include dependency reachability status and description for each SCA issue." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "severity", "-severity", "package", "-package", "ecosystem", "-ecosystem" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "-severity" } ], "responses": { "200": { "description": "SCA issues retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/SCAIssue" } } } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Scan not found" } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/scan/{scan_id}/issues/iac": { "get": { "summary": "Get IaC Issues for Scan", "operationId": "getScanIacIssues", "tags": [ "Issues", "IaC" ], "description": "Retrieve Infrastructure-as-Code (IaC) security issues for a specific scan.", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by severity levels (comma-separated). Valid values: CRITICAL, HIGH, MEDIUM, LOW", "example": "CRITICAL,HIGH" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by cloud or platform provider", "example": "aws" }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by affected service", "example": "s3" }, { "name": "iac_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by IaC format", "example": "terraform" }, { "name": "rule_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by rule identifier", "example": "AVD-AWS-0001" }, { "name": "avd_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by AVD identifier", "example": "AVD-AWS-0001" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by file path (partial match)", "example": "infra/main.tf" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search across title, description, message, rule ID, and AVD ID", "example": "encryption" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "severity", "-severity", "provider", "-provider", "service", "-service", "path", "-path" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "-severity" } ], "responses": { "200": { "description": "Get IaC Issues for Scan retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_issues": { "type": "integer" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/IaCIssue" } } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Scan not found" } } } } } } } } }, "/scan/{scan_id}/dependencies": { "get": { "summary": "Get Dependencies for Scan", "operationId": "getScanDependencies", "tags": [ "Dependencies" ], "description": "Retrieve software dependencies (SBOM) for a specific scan.", "parameters": [ { "name": "scan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the scan" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by dependency name (partial match)", "example": "django" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by dependency version", "example": "4.2.0" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by dependency ecosystem or package type", "example": "pypi" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by file path (partial match)", "example": "requirements.txt" }, { "name": "purl", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by package URL (partial match)", "example": "pkg:pypi/django" }, { "name": "license", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by license", "example": "MIT" }, { "name": "dep_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "direct", "transitive", "all" ], "default": "all" }, "description": "Filter by dependency relationship type", "example": "direct" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search across dependency name, version, and package URL", "example": "lodash" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "version", "-version", "type", "-type", "created_at", "-created_at" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "name" } ], "responses": { "200": { "description": "Get Dependencies for Scan retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_dependencies": { "type": "integer" }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/Dependency" } } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } }, "400": { "description": "Invalid dependency type filter", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid dep_type. Must be one of: direct, transitive, all." } } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Scan not found" } } } } } } } } }, "/start-scan": { "post": { "summary": "Start New Scan", "operationId": "startScan", "tags": [ "Starting Corgea Scan" ], "description": "Starts a BLAST chunked upload. Send `scan_type=blast` as a form field and exactly one `files` part. The archive name must use `.zip`, `.tar`, `.json`, `.fpr`, `.sarif`, or `.xml`. The part body may be empty; send archive bytes with PATCH. BLAST scanning must be enabled for your company.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "files" ], "properties": { "scan_type": { "type": "string", "enum": [ "blast" ], "default": "blast", "description": "Currently only blast scan is supported. If omitted, the server defaults to blast." }, "files": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "format": "binary" }, "description": "Exactly one archive part for BLAST. An empty body is valid when initiating a chunked upload." } } } } } }, "responses": { "200": { "description": "Chunked upload initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Successfully initiated upload at /tmp/uploads/transfer_id" }, "transfer_id": { "type": "string", "format": "uuid", "example": "c9b0a8c7-f9b4-4c10-9d58-cd4c7e1c9c52" }, "status": { "type": "string", "enum": [ "OK" ], "example": "OK" } } } } } }, "400": { "description": "Bad request - validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "No files uploaded for blast. Please upload the required files." } } }, "examples": { "no_files": { "summary": "No files uploaded", "value": { "status": "error", "message": "No files uploaded for blast. Please upload the required files." } }, "multiple_files": { "summary": "Multiple files for BLAST scan", "value": { "status": "error", "message": "Multiple files uploaded for blast. Please upload only one file." } }, "scan_not_enabled": { "summary": "Scan type not enabled", "value": { "status": "error", "message": "Only Blast scan is currently enabled by the API" } }, "blast_not_enabled": { "summary": "BLAST scanning is not enabled for the company", "value": { "status": "error", "message": "Blast Scan is not enabled for your account." } }, "file_validation_error": { "summary": "File validation failed", "value": { "status": "error", "message": "Invalid file type. Only ZIP, TAR, JSON, and FPR files are allowed." } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/start-scan/{transfer_id}/": { "patch": { "summary": "Continue Scan Upload", "operationId": "continueScanUpload", "tags": [ "Starting Corgea Scan" ], "description": "Continue a BLAST chunked upload. This path requires a trailing slash. Intermediate responses include the `Upload-Offset` header and no `scan_id`. When the last chunk completes the archive, the JSON body includes `scan_id` and `project_id` and does not set `Upload-Offset`.", "parameters": [ { "name": "transfer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The transfer ID from the initial scan request" }, { "name": "Upload-Offset", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Current byte offset of the upload" }, { "name": "Upload-Length", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Total size of the file in bytes" }, { "name": "Upload-Name", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Name of the file being uploaded" }, { "name": "CORGEA-SOURCE", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "api", "cli", "vscode", "vs2022", "intellij" ], "default": "api" }, "description": "Identifies the client that triggered the scan. Requests without this header are attributed to the API." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "chunk_data" ], "properties": { "chunk_data": { "type": "string", "format": "binary", "description": "The next chunk of data for the scan" }, "project_name": { "type": "string" }, "branch": { "type": "string" }, "repo_url": { "type": "string" }, "sha": { "type": "string" }, "partial_scan": { "type": "string", "enum": [ "true" ], "description": "Omit this field for a full scan. Send `true` only for a partial scan. The API treats any non-empty form value as a partial scan, including the string `false`." }, "files_to_scan": { "type": "string", "description": "Comma-separated list of files to scan" }, "metadata": { "type": "string", "description": "User-supplied scan metadata as a JSON object string, e.g. {\"pipeline_url\":\"https://ci.example/run/123\"}. Validated on every chunk request and attached to the scan once the upload completes. Must be a JSON object of at most 16,384 bytes; otherwise the request fails with 400." }, "dirty": { "type": "string", "enum": [ "true", "false" ], "description": "Whether the uploaded worktree is dirty. The CLI sends true or false when it has repo info. Omit the field if dirtiness is unknown." }, "scan_configs": { "type": "string", "description": "Comma-separated scan-type tokens applied when the upload completes (base, malicious, policy, secrets, pii, and others). The CLI maps --scan-type blast to base. Omit for server defaults." }, "target_policies": { "type": "string", "description": "Comma-separated policy IDs applied when the upload completes. Invalid IDs return 400." } } } } } }, "responses": { "200": { "description": "Chunk accepted. Intermediate responses set `Upload-Offset`. Completing and already-in-progress responses do not.", "headers": { "Upload-Offset": { "schema": { "type": "integer" }, "description": "Next byte offset. Set on intermediate chunk responses only." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" }, "message": { "type": "string" }, "scan_id": { "type": "string", "format": "uuid", "description": "Present when the last chunk completes and a scan starts.", "example": "1a5afaa3-72ac-458f-a492-ac40ffc88e76" }, "project_id": { "type": "integer", "description": "Present with scan_id when a scan starts." } } }, "examples": { "intermediate": { "summary": "Intermediate chunk", "value": { "status": "ok", "message": "Chunk received." } }, "complete": { "summary": "Upload complete", "value": { "status": "ok", "message": "Upload complete and file processed successfully.", "scan_id": "1a5afaa3-72ac-458f-a492-ac40ffc88e76", "project_id": 1 } }, "in_progress": { "summary": "Scan already in progress", "value": { "status": "ok", "message": "A scan for this commit is already in progress." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid request: 'chunk_data' file not found." }, "internal_detail": { "type": "string" } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } }, "head": { "summary": "Check Upload Status", "operationId": "checkUploadStatus", "tags": [ "Starting Corgea Scan" ], "description": "Return the current upload offset for a transfer. This path requires a trailing slash. Does not return `scan_id`.", "parameters": [ { "name": "transfer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The transfer ID to check" } ], "responses": { "200": { "description": "Upload offset retrieved. An unknown or empty transfer returns Upload-Offset: 0.", "headers": { "Upload-Offset": { "schema": { "type": "integer" }, "description": "Current upload offset in bytes" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" }, "message": { "type": "string", "example": "Offset calculated" } } } } } }, "400": { "description": "Chunk storage could not be read. Unknown transfer IDs return 200 with Upload-Offset: 0, not this error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Transfer not found or error accessing chunks" } } } } } } } } }, "/scan-upload": { "post": { "summary": "Upload Scan", "operationId": "scanUpload", "tags": [ "Uploading 3rd Party Scan" ], "description": "Upload a completed scan report from CLI tools. Upload at least one source file with `/code-upload` for the same `run_id` before calling this endpoint. This endpoint receives pre-generated scan results from Semgrep, Snyk, Checkmarx, CodeQL, and Fortify and integrates them into the system.", "parameters": [ { "name": "run_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ID of the run associated with the scan report" }, { "name": "engine", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "checkmarx", "codeql", "fortify", "semgrep", "snyk" ] }, "description": "The engine used for the scan" }, { "name": "project", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The name of the project" }, { "name": "repo_data", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded JSON string containing repository information (branch_name, integration_url, etc.)" }, { "name": "CORGEA-SOURCE", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "api", "cli", "vscode", "vs2022", "intellij" ], "default": "api" }, "description": "Identifies the client that triggered the scan. Requests without this header are attributed to the API." } ], "requestBody": { "required": true, "description": "The scan report content as UTF-8 text (typically SARIF or JSON format)", "content": { "text/plain": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Scan report uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } }, "400": { "description": "Invalid request, missing source code, or invalid content", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "invalid content" }, "message": { "type": "string", "example": "No source code was uploaded for this run_id. Upload the scanned files to code-upload before uploading the report." } } }, "examples": { "missing_source_code": { "summary": "Source code was not uploaded first", "value": { "status": "error", "message": "No source code was uploaded for this run_id. Upload the scanned files to code-upload before uploading the report." } } } } } } } } }, "/git-config-upload": { "post": { "summary": "Upload Git Config", "operationId": "gitConfigUpload", "tags": [ "Uploading 3rd Party Scan" ], "description": "Upload Git configuration data for a specific scan run to help with repository URL parsing and analysis.", "parameters": [ { "name": "run_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The scan run ID associated with this Git configuration" } ], "requestBody": { "required": true, "description": "Raw Git configuration data as UTF-8 text", "content": { "text/plain": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Git config uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad request - validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "missing run_id" } } }, "examples": { "missing_run_id": { "summary": "Missing run_id parameter", "value": { "status": "missing run_id" } }, "invalid_content": { "summary": "Content validation failed", "value": { "status": "invalid content" } } } } } } } } }, "/code-upload": { "post": { "summary": "Upload Source Code File", "operationId": "codeUpload", "tags": [ "Uploading 3rd Party Scan" ], "description": "Upload individual source code files for a specific scan run. This is used to upload the actual source files that will be analyzed.", "parameters": [ { "name": "run_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The scan run ID associated with this file" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The repository path of the file being uploaded" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The source code file to upload" } } } } } }, "responses": { "200": { "description": "Source code file uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad request - validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "missing run_id" } } }, "examples": { "missing_run_id": { "summary": "Missing run_id parameter", "value": { "status": "missing run_id" } }, "missing_path": { "summary": "Missing path parameter", "value": { "status": "missing path" } }, "no_file_provided": { "summary": "No file uploaded", "value": { "status": "no_file_provided" } }, "invalid_content": { "summary": "File content validation failed", "value": { "status": "invalid content" } } } } } } } } }, "/ci-data-upload": { "post": { "summary": "Upload CI/CD Data", "operationId": "ciDataUpload", "tags": [ "Uploading 3rd Party Scan" ], "description": "Upload CI/CD pipeline metadata and context information for a specific scan run.", "parameters": [ { "name": "run_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The scan run ID associated with this CI data" }, { "name": "platform", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The CI/CD platform name (e.g., jenkins, github-actions, gitlab-ci)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "CI/CD pipeline metadata and context information", "additionalProperties": true } } } }, "responses": { "200": { "description": "CI data uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad request - JSON parsing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Invalid JSON format" } } } } } }, "404": { "description": "Scan not found for the provided run_id", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "unable to find scan associated to this run id" } } } } } } } } }, "/skills": { "get": { "summary": "List Skills", "operationId": "listSkills", "tags": [ "Skills" ], "description": "Retrieve skills in the authenticated user's company. Use status=approved to return only skills with an approved, installable version.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "approved" ] }, "description": "When set to approved, only return skills with an approved version." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "The number of results per page" } ], "responses": { "200": { "description": "Skills retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_skills": { "type": "integer" }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } } } } }, "/skills/{slug}": { "get": { "summary": "Get Skill", "operationId": "getSkill", "tags": [ "Skills" ], "description": "Retrieve a single skill by slug. By default, the latest approved version is returned when one exists. A specific version can be requested with the version query parameter. Version content is included only when the selected version is approved.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The skill slug" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Specific skill version to retrieve" } ], "responses": { "200": { "description": "Skill retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "skill": { "$ref": "#/components/schemas/Skill" }, "version": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SkillVersion" } ] } } }, "examples": { "approved": { "summary": "Approved skill version", "value": { "status": "ok", "skill": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "secure-review", "slug": "secure-review", "description": "Review code for security issues.", "status": "approved", "is_installable": true, "latest_version": "1.0.0", "latest_approved_version": "1.0.0", "created_at": "2026-06-11T12:00:00+00:00", "updated_at": "2026-06-11T12:00:00+00:00" }, "version": { "id": "8c23448e-f629-47c5-9f56-9f26f7ad3d01", "version": "1.0.0", "status": "approved", "is_installable": true, "security_concerns": "", "created_at": "2026-06-11T12:00:00+00:00", "content": "---\nname: secure-review\ndescription: Review code for security issues.\n---\n\n# Instructions" } } }, "pending": { "summary": "Pending skill version", "value": { "status": "ok", "skill": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "secure-review", "slug": "secure-review", "description": "Review code for security issues.", "status": "pending_review", "is_installable": false, "latest_version": "1.0.1", "latest_approved_version": null, "created_at": "2026-06-11T12:00:00+00:00", "updated_at": "2026-06-11T12:05:00+00:00" }, "version": { "id": "8c23448e-f629-47c5-9f56-9f26f7ad3d01", "version": "1.0.1", "status": "pending_review", "is_installable": false, "security_concerns": "", "created_at": "2026-06-11T12:05:00+00:00" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } }, "404": { "description": "Skill or version not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "not_found" }, "error": { "type": "string", "example": "No skill named 'secure-review' found" } } } } } } } } }, "/projects": { "get": { "summary": "List Projects", "operationId": "listProjects", "tags": [ "Projects" ], "description": "Retrieve a list of projects for the authenticated user's company", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter projects by name (case-insensitive partial match)" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by tags (comma-separated)", "example": "production,backend" }, { "name": "repo_url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter projects by repository URL (case-insensitive partial match)", "example": "github.com/corgea/backend-api" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 }, "description": "The number of results per page" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "name", "-name" ] }, "description": "Sort results by field (prefix with '-' for descending order)", "example": "-created_at" } ], "responses": { "200": { "description": "Projects retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_projects": { "type": "integer" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } } }, "401": { "description": "Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "API key is missing" } } }, "examples": { "missing_token": { "summary": "API key header is missing", "value": { "error": "API key is missing" } }, "invalid_token": { "summary": "API key is invalid", "value": { "error": "Invalid API key" } } } } } } } } }, "/projects/{project_id}/tags": { "patch": { "summary": "Update Project Tags", "operationId": "updateProjectTags", "tags": [ "Projects" ], "description": "Add, remove, or replace tags for a project. Incoming tags are trimmed, lowercased, empty values are ignored, and duplicate values are removed before the update is applied.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The ID of the project to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "tags" ], "properties": { "operation": { "type": "string", "enum": [ "add", "remove", "replace" ], "description": "How to apply the provided tags to the current project tag list" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags to add, remove, or replace after normalization" } } } } } }, "responses": { "200": { "description": "Project tags updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "project": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "repo_url": { "type": "string", "nullable": true, "description": "The repository URL associated with the project, when available" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Normalized project tags after the update" } } } } } } } }, "400": { "description": "Bad request - validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "tags must be a list" } } }, "examples": { "invalid_json": { "summary": "Request body is not valid JSON", "value": { "error": "Invalid JSON body" } }, "invalid_operation": { "summary": "Operation is not supported", "value": { "error": "operation must be one of: add, remove, replace" } }, "tags_not_list": { "summary": "Tags field is not an array", "value": { "error": "tags must be a list" } }, "tag_not_string": { "summary": "One or more tags are not strings", "value": { "error": "all tags must be strings" } } } } } }, "401": { "description": "Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "API key is missing" } } }, "examples": { "missing_token": { "summary": "API key header is missing", "value": { "error": "API key is missing" } }, "invalid_token": { "summary": "API key is invalid", "value": { "error": "Invalid API key" } } } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } }, "404": { "description": "Project is hidden by Project Access Control", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Project doesn't exist" } } } } } } } } }, "/blocking-rules": { "get": { "summary": "List Blocking Rules", "operationId": "listBlockingRules", "tags": [ "Policies" ], "description": "Retrieve all blocking rules for the authenticated user's company", "responses": { "200": { "description": "Blocking rules retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "blocking_rules": { "type": "array", "items": { "$ref": "#/components/schemas/BlockingRule" } } } } } } }, "401": { "description": "Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing or invalid authorization header" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "An error occurred while fetching blocking rules" } } } } } } } } }, "/policies": { "get": { "summary": "List Policies", "operationId": "listPolicies", "tags": [ "Policies" ], "description": "Retrieve policies for the authenticated user's company. Results are ordered by newest first.", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter to policies that apply to a project. Company-wide policies are included." }, { "name": "policy_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by one or more comma-separated policy types.", "example": "false_positive,fix" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by active status" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "The page number for pagination" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 30 }, "description": "The number of results per page" } ], "responses": { "200": { "description": "Policies retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create Policy", "operationId": "createPolicy", "tags": [ "Policies" ], "description": "Create a policy for the authenticated user's company.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" } } } }, "responses": { "201": { "description": "Policy created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/policies/{policy_id}": { "get": { "summary": "Get Policy", "operationId": "getPolicy", "tags": [ "Policies" ], "description": "Retrieve a policy by ID.", "parameters": [ { "$ref": "#/components/parameters/PolicyId" } ], "responses": { "200": { "description": "Policy retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update Policy", "operationId": "updatePolicy", "tags": [ "Policies" ], "description": "Partially update a policy. Updates to policy content create a new version; changing only active status updates the same policy.", "parameters": [ { "$ref": "#/components/parameters/PolicyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicyRequest" } } } }, "responses": { "200": { "description": "Policy updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Deactivate Policy", "operationId": "deactivatePolicy", "tags": [ "Policies" ], "description": "Deactivate a policy by ID.", "parameters": [ { "$ref": "#/components/parameters/PolicyId" } ], "responses": { "200": { "description": "Policy deactivated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "policy": { "$ref": "#/components/schemas/Policy" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/notifications/types": { "get": { "summary": "List Notification Types", "operationId": "listNotificationTypes", "tags": [ "Notifications" ], "description": "Retrieve active notification types available to the authenticated user.", "responses": { "200": { "description": "Notification types retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "types": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationType" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/notifications/preferences": { "get": { "summary": "List Notification Preferences", "operationId": "listNotificationPreferences", "tags": [ "Notifications" ], "description": "Retrieve resolved email notification preferences for the authenticated user.", "responses": { "200": { "description": "Notification preferences retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "preferences": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationPreference" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/notifications/preferences/{type_code}": { "patch": { "summary": "Update Notification Preference", "operationId": "updateNotificationPreference", "tags": [ "Notifications" ], "description": "Set or reset the authenticated user's email preference for a notification type. Use null to inherit the company default.", "parameters": [ { "name": "type_code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Notification type code, such as scheduled_scan.daily_report" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationPreferenceRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/OkStatus" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/UnknownNotificationType" } } }, "post": { "summary": "Update Notification Preference", "operationId": "postNotificationPreference", "tags": [ "Notifications" ], "description": "Set or reset the authenticated user's email preference for a notification type. Use null to inherit the company default.", "parameters": [ { "name": "type_code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Notification type code, such as scheduled_scan.daily_report" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationPreferenceRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/OkStatus" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/UnknownNotificationType" } } } }, "/notifications/company-defaults": { "get": { "summary": "List Company Notification Defaults", "operationId": "listCompanyNotificationDefaults", "tags": [ "Notifications" ], "description": "Retrieve company-level email and webhook defaults for active notification types. Company admin access is required.", "responses": { "200": { "description": "Company notification defaults retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "defaults": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyNotificationDefault" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/AdminRequired" } } } }, "/notifications/company-defaults/{type_code}": { "patch": { "summary": "Update Company Notification Default", "operationId": "updateCompanyNotificationDefault", "tags": [ "Notifications" ], "description": "Partially update company-level email or webhook defaults for a notification type. Use null to inherit the platform default. Company admin access is required.", "parameters": [ { "name": "type_code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Notification type code, such as scheduled_scan.daily_report" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyNotificationDefaultRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/OkStatus" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/AdminRequired" }, "404": { "$ref": "#/components/responses/UnknownNotificationType" } } }, "post": { "summary": "Update Company Notification Default", "operationId": "postCompanyNotificationDefault", "tags": [ "Notifications" ], "description": "Partially update company-level email or webhook defaults for a notification type. Use null to inherit the platform default. Company admin access is required.", "parameters": [ { "name": "type_code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Notification type code, such as scheduled_scan.daily_report" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyNotificationDefaultRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/OkStatus" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/AdminRequired" }, "404": { "$ref": "#/components/responses/UnknownNotificationType" } } } }, "/teams": { "get": { "summary": "List teams", "operationId": "listTeams", "tags": ["Teams"], "description": "Lists active teams for the authenticated user's company. Requires the `user_management.change_content_access` permission.", "parameters": [ { "name": "search", "in": "query", "description": "Filter teams by team name or member name or email.", "schema": {"type": "string"} }, { "name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1, "default": 1} }, { "name": "page_size", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20} } ], "responses": { "200": { "description": "Teams retrieved successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamListResponse"} } } }, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"} } }, "post": { "summary": "Create a team", "operationId": "createTeam", "tags": ["Teams"], "description": "Creates a team and optionally assigns members, explicit projects, project-tag selectors, and repository URL fragment selectors. Requires the `user_management.change_content_access` permission.", "requestBody": { "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/CreateTeamRequest"} } } }, "responses": { "201": { "description": "Team created successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamResponse"} } } }, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "One or more users or projects were not found"}, "409": {"description": "A team with this name already exists"} } } }, "/teams/{team_id}": { "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": {"type": "integer"} } ], "get": { "summary": "Get a team", "operationId": "getTeam", "tags": ["Teams"], "description": "Retrieves an active team for the authenticated user's company.", "responses": { "200": { "description": "Team retrieved successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamResponse"} } } }, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "Team not found"} } }, "patch": { "summary": "Update a team", "operationId": "updateTeam", "tags": ["Teams"], "description": "Updates any supplied team fields. Selector lists replace their current values; omit a field to leave it unchanged. Requires the `user_management.change_content_access` permission.", "requestBody": { "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/UpdateTeamRequest"} } } }, "responses": { "200": { "description": "Team updated successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamResponse"} } } }, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "Team, user, or project not found"}, "409": {"description": "A team with this name already exists"} } }, "delete": { "summary": "Delete a team", "operationId": "deleteTeam", "tags": ["Teams"], "description": "Permanently deletes a team. Requires the `user_management.change_content_access` permission.", "responses": { "200": {"$ref": "#/components/responses/OkStatus"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "Team not found"} } } }, "/teams/{team_id}/members": { "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": {"type": "integer"} } ], "post": { "summary": "Add team members", "operationId": "addTeamMembers", "tags": ["Teams"], "requestBody": { "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamMembersRequest"} } } }, "responses": { "200": { "description": "Members added successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamResponse"} } } }, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "Team or user not found"} } }, "delete": { "summary": "Remove team members", "operationId": "removeTeamMembers", "tags": ["Teams"], "description": "Removes the supplied users from the team. Company administrators cannot be removed.", "requestBody": { "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamMembersRequest"} } } }, "responses": { "200": { "description": "Members removed successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamResponse"} } } }, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "Team or user not found"}, "409": {"description": "A company administrator cannot be removed from a team"} } } }, "/teams/{team_id}/projects": { "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "Team ID", "schema": {"type": "integer"} } ], "get": { "summary": "List projects accessible to a team", "operationId": "listTeamProjects", "tags": ["Teams"], "description": "Resolves projects granted through explicit assignment, project tags, or repository URL fragments. Use `sources` to see every matching access path.", "responses": { "200": { "description": "Resolved team projects retrieved successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/TeamProjectsResponse"} } } }, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "Team not found"} } } }, "/integrations/harness": { "get": { "summary": "List Harness integrations", "operationId": "listHarnessIntegrations", "tags": ["Harness integrations"], "description": "Lists Harness Code SCM integrations for your company. Requires the `integrations.view_integration` permission.", "parameters": [ { "name": "page", "in": "query", "schema": {"type": "integer", "minimum": 1, "default": 1} }, { "name": "page_size", "in": "query", "description": "Number of integrations per page (maximum 50).", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20} } ], "responses": { "200": { "description": "Harness integrations retrieved successfully", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/HarnessIntegrationListResponse"} } } }, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"description": "API access or required permission denied"} } }, "post": { "summary": "Create a Harness integration", "operationId": "createHarnessIntegration", "tags": ["Harness integrations"], "description": "Creates a Harness Code SCM integration after verifying its PAT or Service Account Token. Requires the `integrations.manage_integration` permission. An account can have multiple integrations when each uses a different organization allowlist.", "requestBody": { "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/CreateHarnessIntegrationRequest"} } } }, "responses": { "201": { "description": "Harness integration created and credentials verified", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/HarnessIntegrationWriteResponse"} } } }, "400": {"description": "Invalid request or credentials could not be verified"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"description": "API access or required permission denied"}, "409": {"description": "An integration already exists for this account and organization allowlist"} } } }, "/integrations/harness/{integration_uuid}": { "parameters": [ { "name": "integration_uuid", "in": "path", "required": true, "description": "Harness integration UUID", "schema": {"type": "string", "format": "uuid"} } ], "get": { "summary": "Get a Harness integration", "operationId": "getHarnessIntegration", "tags": ["Harness integrations"], "description": "Retrieves a Harness Code SCM integration for your company. Requires the `integrations.view_integration` permission.", "responses": { "200": { "description": "Harness integration retrieved successfully", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HarnessIntegrationResponse"}}} }, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"description": "API access or required permission denied"}, "404": {"description": "Integration not found"} } }, "patch": { "summary": "Update a Harness integration", "operationId": "updateHarnessIntegration", "tags": ["Harness integrations"], "description": "Updates selected fields. Changing the token, base URL, or gateway prefix re-verifies the credentials. A replacement token must belong to the existing Harness account. Requires the `integrations.manage_integration` permission.", "requestBody": { "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UpdateHarnessIntegrationRequest"}}} }, "responses": { "200": { "description": "Harness integration updated successfully", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HarnessIntegrationWriteResponse"}}} }, "400": {"description": "Invalid request, account mismatch, or credentials could not be verified"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"description": "API access or required permission denied"}, "404": {"description": "Integration not found"}, "409": {"description": "An integration already exists for this account and organization allowlist"} } }, "delete": { "summary": "Delete a Harness integration", "operationId": "deleteHarnessIntegration", "tags": ["Harness integrations"], "description": "Deletes a Harness Code SCM integration and attempts to remove its registered webhooks. Requires the `integrations.manage_integration` permission.", "responses": { "200": {"description": "Harness integration deleted successfully"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"description": "API access or required permission denied"}, "404": {"description": "Integration not found"} } } } }, "components": { "securitySchemes": { "CorgeaToken": { "type": "apiKey", "in": "header", "name": "CORGEA-TOKEN", "description": "API key for authentication" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth2 access token (JWT) in the Authorization header" } }, "parameters": { "PolicyId": { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The ID of the policy" } }, "responses": { "OkStatus": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } }, "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid JSON body" } } } } } }, "Unauthorized": { "description": "Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing or invalid authorization header" } } } } } }, "Forbidden": { "description": "Permission denied or feature unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Permission denied" } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Policy not found" } } } } } }, "Conflict": { "description": "Request conflicts with an existing resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "A policy with this name already exists" } } } } } }, "AdminRequired": { "description": "Company admin access is required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Admin permission required" } } } } } }, "UnknownNotificationType": { "description": "Notification type was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unknown notification type" } } } } } } }, "schemas": { "BulkTriageRequest": { "type": "object", "required": ["target_status", "justification", "rule"], "additionalProperties": false, "properties": { "target_status": { "type": "string", "enum": ["open", "fixed", "false_positive", "accepted_risk", "duplicate", "fix_in_progress"], "description": "fix_in_progress is available only when finding_types contains only sast." }, "justification": {"type": "string", "minLength": 1}, "apply": {"type": "boolean", "default": true, "description": "Set to false to create a preview without changing findings."}, "expiry_date": {"type": "string", "format": "date-time", "nullable": true, "description": "Future expiry time for accepted_risk actions only."}, "rule": {"$ref": "#/components/schemas/BulkTriageRule"} } }, "BulkTriageRule": { "type": "object", "additionalProperties": false, "description": "Select a scope with company_wide, project_ids, or team_ids. Filters use match to combine applicable criteria; CWE filters apply to SAST and CVE and reachability filters apply to SCA.", "properties": { "company_wide": {"type": "boolean", "default": false}, "project_ids": {"type": "array", "uniqueItems": true, "items": {"type": "integer"}}, "team_ids": {"type": "array", "uniqueItems": true, "items": {"type": "integer"}}, "finding_types": {"type": "array", "minItems": 1, "default": ["sast", "sca"], "items": {"type": "string", "enum": ["sast", "sca"]}}, "cwes": {"type": "array", "items": {"type": "string", "example": "CWE-79"}}, "cves": {"type": "array", "items": {"type": "string", "example": "CVE-2026-1000"}}, "path_patterns": {"type": "array", "items": {"type": "string", "example": "tests/**"}}, "severities": {"type": "array", "items": {"type": "string", "enum": ["LO", "ME", "HI", "CR", "LOW", "MEDIUM", "HIGH", "CRITICAL"]}}, "reachability": {"type": "string", "nullable": true, "enum": ["true", "false", "unsure"]}, "match": {"type": "string", "enum": ["all", "any"], "default": "all"} } }, "TriageAction": { "type": "object", "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["preview", "pending_approval", "applied", "rejected", "failed"]}, "source": {"type": "string", "enum": ["api", "cli", "cxone"]}, "target_status": {"type": "string"}, "justification": {"type": "string"}, "accepted_risk_expiry_date": {"type": "string", "format": "date-time", "nullable": true}, "rule": {"type": "object"}, "source_metadata": {"type": "object"}, "requires_approval": {"type": "boolean"}, "requested_by": {"type": "integer", "nullable": true}, "approved_by": {"type": "integer", "nullable": true}, "rejected_by": {"type": "integer", "nullable": true}, "created_at": {"type": "string", "format": "date-time"}, "reviewed_at": {"type": "string", "format": "date-time", "nullable": true}, "applied_at": {"type": "string", "format": "date-time", "nullable": true}, "counts": { "type": "object", "properties": { "matched": {"type": "integer"}, "unmatched": {"type": "integer"}, "ambiguous": {"type": "integer"}, "applied": {"type": "integer"}, "conflicts": {"type": "integer"} } } } }, "TriageActionResponse": { "type": "object", "properties": {"status": {"type": "string", "example": "ok"}, "action": {"$ref": "#/components/schemas/TriageAction"}} }, "TriageFindingAudit": { "type": "object", "properties": { "id": {"type": "string", "format": "uuid"}, "finding_type": {"type": "string", "enum": ["sast", "sca"]}, "finding_id": {"type": "string", "format": "uuid", "nullable": true}, "project_id": {"type": "integer", "nullable": true}, "previous_status": {"type": "string", "nullable": true}, "previous_status_comment": {"type": "string", "nullable": true}, "previous_accepted_risk_expiry_date": {"type": "string", "format": "date-time", "nullable": true}, "new_status": {"type": "string"}, "new_status_comment": {"type": "string", "nullable": true}, "severity": {"type": "string", "nullable": true}, "application_status": {"type": "string", "enum": ["pending", "applied", "conflict", "unmatched", "ambiguous"]}, "match_evidence": {"type": "object"}, "source_record": {"type": "object"}, "applied_at": {"type": "string", "format": "date-time", "nullable": true} } }, "TriageActionDetailResponse": { "allOf": [ {"$ref": "#/components/schemas/TriageActionResponse"}, {"type": "object", "properties": { "findings": {"type": "array", "items": {"$ref": "#/components/schemas/TriageFindingAudit"}}, "pagination": {"type": "object", "properties": {"page": {"type": "integer"}, "page_size": {"type": "integer"}, "total_pages": {"type": "integer"}, "total_findings": {"type": "integer"}}} }} ] }, "TriageApprovalPolicy": { "type": "object", "additionalProperties": false, "properties": { "finding_count_threshold": {"type": "integer", "minimum": 1, "nullable": true, "description": "Require approval when an accepted-risk action matches at least this many findings."}, "severity_threshold": {"type": "string", "nullable": true, "enum": ["LO", "ME", "HI", "CR", "LOW", "MEDIUM", "HIGH", "CRITICAL"], "description": "Require approval when an accepted-risk action includes this severity or higher."} } }, "TriageApprovalPolicyResponse": { "type": "object", "properties": {"status": {"type": "string", "example": "ok"}, "policy": {"$ref": "#/components/schemas/TriageApprovalPolicy"}} }, "TeamMember": { "type": "object", "required": ["id", "email", "first_name", "last_name"], "properties": { "id": {"type": "integer"}, "email": {"type": "string", "format": "email"}, "first_name": {"type": "string"}, "last_name": {"type": "string"} } }, "Team": { "type": "object", "required": [ "id", "name", "active", "members", "project_ids", "project_tags", "repo_url_patterns", "project_count", "created_at", "updated_at" ], "properties": { "id": {"type": "integer"}, "name": {"type": "string"}, "active": {"type": "boolean"}, "members": { "type": "array", "items": {"$ref": "#/components/schemas/TeamMember"} }, "project_ids": { "type": "array", "description": "Projects assigned explicitly to the team.", "items": {"type": "integer"} }, "project_tags": { "type": "array", "description": "A project matches when it contains any listed tag.", "items": {"type": "string"} }, "repo_url_patterns": { "type": "array", "description": "A project matches when its repository URL contains any listed fragment, case-insensitively.", "items": {"type": "string", "minLength": 3} }, "project_count": { "type": "integer", "description": "Distinct projects currently resolved through explicit assignment or selectors." }, "created_at": {"type": "string", "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"} } }, "TeamResponse": { "type": "object", "required": ["team"], "properties": { "team": {"$ref": "#/components/schemas/Team"} } }, "TeamListResponse": { "type": "object", "required": ["status", "teams", "page", "total_pages", "total_teams"], "properties": { "status": {"type": "string", "enum": ["ok"]}, "teams": { "type": "array", "items": {"$ref": "#/components/schemas/Team"} }, "page": {"type": "integer"}, "total_pages": {"type": "integer"}, "total_teams": {"type": "integer"} } }, "CreateTeamRequest": { "type": "object", "required": ["name"], "additionalProperties": false, "properties": { "name": {"type": "string"}, "member_ids": { "type": "array", "items": {"type": "integer"} }, "project_ids": { "type": "array", "description": "Project IDs to assign explicitly.", "items": {"type": "integer"} }, "project_tags": { "type": "array", "description": "Tags that dynamically grant access to matching projects.", "items": {"type": "string"} }, "repo_url_patterns": { "type": "array", "description": "Repository URL fragments that dynamically grant access to matching projects.", "items": {"type": "string", "minLength": 3} } }, "example": { "name": "Payments Team", "member_ids": [12, 34], "project_ids": [101], "project_tags": ["payments", "backend"], "repo_url_patterns": ["github.com/acme/payments-"] } }, "UpdateTeamRequest": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "name": {"type": "string"}, "member_ids": { "type": "array", "description": "Replaces all team members.", "items": {"type": "integer"} }, "project_ids": { "type": "array", "description": "Replaces all explicit project assignments.", "items": {"type": "integer"} }, "project_tags": { "type": "array", "description": "Replaces all project-tag selectors.", "items": {"type": "string"} }, "repo_url_patterns": { "type": "array", "description": "Replaces all repository URL fragment selectors.", "items": {"type": "string", "minLength": 3} } } }, "TeamMembersRequest": { "type": "object", "required": ["member_ids"], "additionalProperties": false, "properties": { "member_ids": { "type": "array", "items": {"type": "integer"} } } }, "TeamProject": { "type": "object", "required": ["id", "name", "repo_url", "tags", "source", "sources"], "properties": { "id": {"type": "integer"}, "name": {"type": "string"}, "repo_url": {"type": "string", "format": "uri", "nullable": true}, "tags": { "type": "array", "items": {"type": "string"} }, "source": { "type": "string", "description": "Primary match source.", "enum": ["explicit", "tag", "repo_url"] }, "sources": { "type": "array", "description": "All access paths through which this project matches.", "items": { "type": "string", "enum": ["explicit", "tag", "repo_url"] } } } }, "TeamProjectsResponse": { "type": "object", "required": ["team_id", "project_count", "projects"], "properties": { "team_id": {"type": "integer"}, "project_count": {"type": "integer"}, "projects": { "type": "array", "items": {"$ref": "#/components/schemas/TeamProject"} } } }, "HarnessIntegration": { "type": "object", "description": "A Harness Code SCM integration. Credential values are never returned.", "required": ["id", "uuid", "type", "name", "account_id", "account_name", "org_allowlist", "base_url", "gateway_prefix", "expired"], "properties": { "id": {"type": "integer"}, "uuid": {"type": "string", "format": "uuid"}, "type": {"type": "string", "enum": ["harness"]}, "name": {"type": "string"}, "account_id": {"type": "string", "description": "Harness account ID derived from the token."}, "account_name": {"type": "string"}, "org_allowlist": { "type": "array", "description": "Harness organization identifiers available to this integration. An empty list allows every organization accessible to the token.", "items": {"type": "string"} }, "base_url": {"type": "string", "format": "uri"}, "gateway_prefix": {"type": "string"}, "expired": {"type": "boolean"}, "created_at": {"type": "string", "format": "date-time", "nullable": true}, "updated_at": {"type": "string", "format": "date-time", "nullable": true} } }, "CreateHarnessIntegrationRequest": { "type": "object", "required": ["secure_token"], "properties": { "secure_token": {"type": "string", "writeOnly": true, "description": "Harness PAT or Service Account Token."}, "name": {"type": "string", "default": "Harness"}, "org_allowlist": {"type": "array", "items": {"type": "string"}, "default": []}, "base_url": {"type": "string", "format": "uri", "default": "https://app.harness.io"}, "gateway_prefix": {"type": "string", "default": "/gateway"} } }, "UpdateHarnessIntegrationRequest": { "type": "object", "properties": { "secure_token": {"type": "string", "writeOnly": true, "description": "Replacement PAT or Service Account Token for the same Harness account."}, "name": {"type": "string"}, "org_allowlist": {"type": "array", "items": {"type": "string"}}, "base_url": {"type": "string", "format": "uri"}, "gateway_prefix": {"type": "string"} } }, "HarnessIntegrationResponse": { "type": "object", "required": ["status", "integration"], "properties": { "status": {"type": "string", "enum": ["ok"]}, "integration": {"$ref": "#/components/schemas/HarnessIntegration"} } }, "HarnessIntegrationWriteResponse": { "allOf": [ {"$ref": "#/components/schemas/HarnessIntegrationResponse"}, { "type": "object", "required": ["credentials_verified"], "properties": {"credentials_verified": {"type": "boolean", "enum": [true]}} } ] }, "HarnessIntegrationListResponse": { "type": "object", "required": ["status", "integrations", "page", "total_pages", "total_integrations"], "properties": { "status": {"type": "string", "enum": ["ok"]}, "integrations": {"type": "array", "items": {"$ref": "#/components/schemas/HarnessIntegration"}}, "page": {"type": "integer"}, "total_pages": {"type": "integer"}, "total_integrations": {"type": "integer"} } }, "NotificationType": { "type": "object", "properties": { "code": { "type": "string", "example": "scheduled_scan.daily_report" }, "name": { "type": "string", "example": "Daily Scheduled Scan Report" }, "description": { "type": "string", "example": "Summary email sent once per day with new issues discovered by scheduled scans." }, "category": { "type": "string", "example": "scheduled_scans" }, "audience": { "type": "string", "enum": [ "company_admins", "all_users" ] }, "default_email_enabled": { "type": "boolean" }, "default_webhook_enabled": { "type": "boolean" } } }, "NotificationPreference": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/NotificationType" }, "email_enabled": { "type": "boolean", "description": "Resolved email preference for the authenticated user" }, "source": { "type": "string", "description": "Where the resolved preference came from", "enum": [ "user", "company", "type" ] } } }, "CompanyNotificationDefault": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/NotificationType" }, "email_enabled": { "type": "boolean", "nullable": true, "description": "Company email default; null inherits the platform default" }, "webhook_enabled": { "type": "boolean", "nullable": true, "description": "Company webhook default; null inherits the platform default" } } }, "UpdateNotificationPreferenceRequest": { "type": "object", "required": [ "email_enabled" ], "properties": { "email_enabled": { "type": "boolean", "nullable": true, "description": "Set true or false, or null to inherit the company default" } } }, "UpdateCompanyNotificationDefaultRequest": { "type": "object", "minProperties": 1, "properties": { "email_enabled": { "type": "boolean", "nullable": true, "description": "Set true or false, or null to inherit the platform default" }, "webhook_enabled": { "type": "boolean", "nullable": true, "description": "Set true or false, or null to inherit the platform default" } } }, "Skill": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "secure-review" }, "slug": { "type": "string", "example": "secure-review" }, "description": { "type": "string", "example": "Review code for security issues." }, "status": { "type": "string", "nullable": true, "enum": [ "pending_review", "approved", "rejected", "failed" ] }, "is_installable": { "type": "boolean", "description": "Whether the skill has an approved version that can be installed" }, "latest_version": { "type": "string", "nullable": true, "example": "1.0.1" }, "latest_approved_version": { "type": "string", "nullable": true, "example": "1.0.0" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SkillVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string", "example": "1.0.0" }, "status": { "type": "string", "enum": [ "pending_review", "approved", "rejected", "failed" ] }, "is_installable": { "type": "boolean" }, "security_concerns": { "type": "string", "description": "Review concern when a version is rejected" }, "created_at": { "type": "string", "format": "date-time" }, "content": { "type": "string", "description": "SKILL.md content. Included only when the selected version is approved." } } }, "Issue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "classification": { "type": "object", "properties": { "id": { "type": "string", "example": "CWE-123" }, "name": { "type": "string", "example": "Vulnerability Name" }, "description": { "type": "string", "nullable": true } } }, "urgency": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "open", "in_progress", "fixed", "accepted_risk", "false_positive" ] }, "sla_status": { "type": "string", "enum": [ "on_track", "due", "overdue" ] }, "location": { "$ref": "#/components/schemas/IssueLocation" }, "auto_triage": { "$ref": "#/components/schemas/AutoTriage" }, "auto_fix_suggestion": { "$ref": "#/components/schemas/AutoFixSuggestion" }, "assigned_to": { "$ref": "#/components/schemas/AssignedTo" }, "scanner_metadata": { "type": "object", "description": "Scanner-provided metadata attached to the issue.", "additionalProperties": { "type": "string" } }, "reachability": { "$ref": "#/components/schemas/IssueReachabilitySummary" } } }, "IssueDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scan_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "in_progress", "fixed", "accepted_risk", "false_positive" ] }, "urgency": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "created_at": { "type": "string", "format": "date-time" }, "classification": { "type": "object", "properties": { "id": { "type": "string", "example": "CWE-123" }, "name": { "type": "string", "example": "Vulnerability Name" }, "description": { "type": "string", "nullable": true } } }, "location": { "$ref": "#/components/schemas/IssueLocation" }, "details": { "type": "object", "properties": { "explanation": { "type": "string" } } }, "auto_triage": { "$ref": "#/components/schemas/AutoTriage" }, "auto_fix_suggestion": { "$ref": "#/components/schemas/AutoFixSuggestion" }, "assigned_to": { "$ref": "#/components/schemas/AssignedTo" }, "reachability": { "$ref": "#/components/schemas/IssueReachabilityDetail" } } }, "AssignedTo": { "type": "object", "nullable": true, "description": "User assigned to the issue, or null when the issue is unassigned.", "properties": { "id": { "type": "string", "description": "Assigned user's ID." }, "email": { "type": "string", "format": "email", "description": "Assigned user's email address." }, "name": { "type": "string", "nullable": true, "description": "Assigned user's display name, or null when unavailable." } } }, "IssueLocation": { "type": "object", "properties": { "file": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" }, "path": { "type": "string" } } }, "project": { "type": "object", "properties": { "name": { "type": "string" }, "branch": { "type": "string" }, "git_sha": { "type": "string" } } }, "line_number": { "type": "integer" } } }, "AutoTriage": { "type": "object", "properties": { "false_positive_detection": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "valid", "false_positive", "pending" ] }, "reasoning": { "type": "string" } } } } }, "AutoFixSuggestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "fix_available", "no_fix", "generating", "false_positive", "on_hold", "unsupported", "plan" ], "description": "Current fix availability. Getting an issue starts eligible missing fix generation in the background by default. While that generation is pending, the status is generating; fetch the issue again until generation finishes. If generation is disabled or no fix is produced, the status is no_fix." }, "patch": { "type": "object", "properties": { "diff": { "type": "string", "description": "Unified diff format patch" }, "explanation": { "type": "string", "description": "Explanation of how the fix addresses the vulnerability" } } } } }, "SCAIssue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "details": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "cve": { "type": "string", "description": "CVE identifier if available" }, "package": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "ecosystem": { "type": "string" }, "fix_version": { "type": "string", "description": "Version that fixes the vulnerability" } } }, "location": { "type": "object", "properties": { "path": { "type": "string", "description": "Path to the file containing the vulnerable package" } } }, "reachability": { "$ref": "#/components/schemas/SCAReachability" } } }, "IssueGroupBreakdown": { "type": "object", "description": "Counts within the group, present only when breakdown is true.", "properties": { "by_urgency": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "CR": 5, "HI": 10, "ME": 20, "LO": 7 } }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "open": 30, "fixed": 5, "false_positive": 2, "accepted_risk": 1, "fix_in_progress": 3, "duplicate": 1 } } } }, "IssueCweGroup": { "type": "object", "description": "A group of issues sharing a CWE classification, returned when group_by is cwe.", "properties": { "cwe": { "type": "object", "properties": { "id": { "type": "string", "example": "CWE-89" }, "name": { "type": "string" }, "description": { "type": "string" } } }, "issue_count": { "type": "integer", "example": 42 }, "breakdown": { "$ref": "#/components/schemas/IssueGroupBreakdown" } } }, "IssueFileGroup": { "type": "object", "description": "A group of issues sharing a file path, returned when group_by is file_path.", "properties": { "file": { "type": "object", "properties": { "path": { "type": "string", "example": "src/api/auth.py" }, "name": { "type": "string", "example": "auth.py" } } }, "issue_count": { "type": "integer", "example": 7 }, "breakdown": { "$ref": "#/components/schemas/IssueGroupBreakdown" } } }, "SCAIssueGroupBreakdown": { "type": "object", "description": "Counts within the group, present only when breakdown is true.", "properties": { "by_severity": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "CRITICAL": 1, "HIGH": 2, "MEDIUM": 1, "LOW": 0 } }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "open": 3, "fixed": 1, "false_positive": 0, "accepted_risk": 0, "duplicate": 0 } } } }, "SCAIssuePackageGroup": { "type": "object", "description": "A group of SCA issues sharing a package name.", "properties": { "package": { "type": "object", "properties": { "name": { "type": "string", "example": "lodash" }, "ecosystems": { "type": "array", "items": { "type": "string" }, "example": [ "npm" ] } } }, "issue_count": { "type": "integer", "example": 4 }, "breakdown": { "$ref": "#/components/schemas/SCAIssueGroupBreakdown" } } }, "IssueReachabilitySummary": { "type": "object", "description": "Endpoint reachability summary returned when include_reachability is true.", "properties": { "is_reachable": { "type": "boolean" }, "endpoint_count": { "type": "integer" } } }, "IssueReachabilityDetail": { "type": "object", "description": "Endpoint reachability details returned when include_reachability is true.", "properties": { "is_reachable": { "type": "boolean" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/IssueReachabilityEndpoint" } } } }, "IssueReachabilityEndpoint": { "type": "object", "properties": { "path": { "type": "string" }, "method": { "type": "string" }, "file_path": { "type": "string", "nullable": true }, "line_number": { "type": "integer", "nullable": true }, "pathways": { "type": "array", "items": { "$ref": "#/components/schemas/IssueReachabilityPathway" } } } }, "IssueReachabilityPathway": { "type": "object", "properties": { "pathway_id": { "type": "string" }, "total_depth": { "type": "integer" }, "confidence_score": { "type": "number" }, "target": { "type": "object", "additionalProperties": true }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/IssueReachabilityStep" } } } }, "IssueReachabilityStep": { "type": "object", "properties": { "depth": { "type": "integer" }, "file_path": { "type": "string" }, "line_number": { "type": "integer" }, "function_name": { "type": "string" }, "target_line_number": { "type": "integer" } } }, "SCAReachability": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_direct_dependency", "pending", "vulnerable_usage_reachable", "vulnerable_usage_unreachable", "dead_dependency" ] }, "description": { "type": "string" } } }, "SCAIssueDetail": { "allOf": [ { "$ref": "#/components/schemas/SCAIssue" }, { "type": "object", "properties": { "cvss_score": { "type": "number", "nullable": true }, "status": { "type": "string", "enum": [ "open", "fixed", "false_positive", "accepted_risk", "duplicate" ] }, "reachability": { "allOf": [ { "$ref": "#/components/schemas/SCAReachability" }, { "type": "object", "properties": { "usages": { "type": "array", "items": { "$ref": "#/components/schemas/SCAIssueUsage" } } } } ] } } } ] }, "SCAIssueUsage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "code_line": { "type": "string", "nullable": true }, "is_function_reachable": { "type": "string", "nullable": true, "enum": [ "true", "false", "unsure" ] }, "reasoning": { "type": "string" } } }, "Policy": { "type": "object", "properties": { "id": { "type": "integer" }, "policy_type": { "type": "string", "enum": [ "BLAST", "scan", "false_positive", "fix" ] }, "description": { "type": "string" }, "cwes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "excludes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "projects": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Project names that scope the policy. Empty or null means company-wide." }, "company": { "type": "integer" }, "active": { "type": "boolean" }, "approved": { "type": "boolean" }, "approved_by": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "glob_pattern": { "type": "string", "nullable": true }, "source_type": { "type": "string", "example": "Web" }, "repo_policy_file": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "guidance_text": { "type": "string", "nullable": true }, "version": { "type": "integer" }, "archived": { "type": "boolean" }, "parent_policy": { "type": "integer", "nullable": true }, "instruction_type": { "type": "string", "enum": [ "overwrite", "append" ] }, "read_only": { "type": "boolean" }, "created_by_corgea": { "type": "boolean" } } }, "PolicyResponse": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/Policy" } } }, "PolicyListResponse": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "type": "object", "properties": { "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "current_page": { "type": "integer" }, "page_size": { "type": "integer" } } } } }, "CreatePolicyRequest": { "type": "object", "required": [ "policy_type", "description", "name" ], "additionalProperties": false, "properties": { "policy_type": { "type": "string", "enum": [ "BLAST", "scan", "false_positive", "fix" ] }, "description": { "type": "string", "minLength": 10 }, "name": { "type": "string", "minLength": 3 }, "cwes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "excludes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "projects": { "type": "array", "nullable": true, "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "description": "Project names or IDs that scope the policy. Empty or null creates a company-wide policy." }, "active": { "type": "boolean", "default": true }, "instruction_type": { "type": "string", "enum": [ "overwrite", "append" ], "default": "overwrite" }, "glob_pattern": { "type": "string", "nullable": true, "maxLength": 255 }, "guidance_text": { "type": "string", "nullable": true, "maxLength": 3000 } } }, "UpdatePolicyRequest": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "policy_type": { "type": "string", "enum": [ "BLAST", "scan", "false_positive", "fix" ] }, "description": { "type": "string", "minLength": 10 }, "name": { "type": "string", "minLength": 3 }, "cwes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "excludes": { "type": "array", "nullable": true, "items": { "type": "string" } }, "projects": { "type": "array", "nullable": true, "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "description": "Project names or IDs that scope the policy. Empty or null makes the policy company-wide." }, "active": { "type": "boolean" }, "instruction_type": { "type": "string", "enum": [ "overwrite", "append" ] }, "glob_pattern": { "type": "string", "nullable": true, "maxLength": 255 }, "guidance_text": { "type": "string", "nullable": true, "maxLength": 3000 } } }, "BlockingRule": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string", "description": "URL-safe slug generated from the rule name; used with corgea scan --block-on for CI rules" }, "description": { "type": "string" }, "rule_type": { "type": "string", "enum": [ "code", "sca", "license" ] }, "applies_to": { "type": "string", "enum": [ "pr", "ci" ], "description": "Where the rule is enforced. pr rules gate pull request checks automatically; ci rules run only when named with corgea scan --block-on" }, "code_finding_type": { "type": "string", "enum": [ "all", "vulnerability", "code_quality" ], "description": "Finding type matched by a code vulnerability rule. Defaults to all; dependency vulnerability rules always return all." }, "urgencies": { "type": "array", "items": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] } }, "classifications": { "type": "array", "items": { "type": "string" } }, "denied_licenses": { "type": "array", "items": { "type": "string" }, "description": "SPDX license IDs denied by a license compliance rule" }, "denied_families": { "type": "array", "items": { "type": "string", "enum": [ "copyleft", "permissive", "commercial" ] }, "description": "License families denied by a license compliance rule" }, "projects": { "type": "array", "items": { "type": "string" } }, "project_tags": { "type": "array", "items": { "type": "string" }, "description": "Project tags that scope this blocking rule" }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Project": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "repo_url": { "type": "string", "nullable": true, "description": "The repository URL associated with the project, when available" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags associated with the project" }, "created_at": { "type": "string", "format": "date-time" } } }, "IaCIssue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "description": { "type": "string" }, "message": { "type": "string" }, "resolution": { "type": "string" }, "severity": { "type": "string", "nullable": true, "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW" ] }, "rule_id": { "type": "string" }, "avd_id": { "type": "string" }, "primary_url": { "type": "string" }, "references": { "type": "array", "items": {} }, "provider": { "type": "string" }, "service": { "type": "string" }, "iac_type": { "type": "string" }, "location": { "type": "object", "properties": { "path": { "type": "string" }, "raw_path": { "type": "string" }, "start_line": { "type": "integer", "nullable": true }, "end_line": { "type": "integer", "nullable": true } } }, "scan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "branch": { "type": "string", "nullable": true }, "project": { "type": "string", "nullable": true } } } } }, "Dependency": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "version": { "type": "string" }, "type": { "type": "string" }, "purl": { "type": "string" }, "path": { "type": "string" }, "licenses": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "array", "items": {} }, "is_direct": { "type": "boolean" }, "parent_id": { "type": "string", "nullable": true }, "source_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "scan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "branch": { "type": "string", "nullable": true }, "project": { "type": "string", "nullable": true } } } } } } } }