{ "openapi": "3.0.3", "info": { "title": "CodeAnt AI API", "description": "API for code analysis (SAST, SCA, secrets, IaC) and developer productivity metrics. Supports GitHub, GitLab, Bitbucket, and Azure DevOps.", "version": "1.0.0" }, "servers": [ { "url": "https://api.codeant.ai", "description": "Production server" } ], "paths": { "/api/analysis/start": { "post": { "summary": "Start Analysis", "description": "Initiates a background analysis task for a repository", "operationId": "startAnalysis", "tags": [ "Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisStartRequest" }, "examples": { "github": { "summary": "GitHub repository example", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github", "branch": "main", "include_files": "src/**/*.py,lib/**/*.js,app/**/*.ts", "exclude_files": "tests/**,node_modules/**,dist/**" } }, "azuredevops": { "summary": "Azure DevOps repository example", "value": { "repo": "organization/project/repository", "commit_id": "abc123def456", "access_token": "pat_xxxxxxxxxxxx", "service": "azuredevops", "branch": "main", "include_files": "src/**/*.cs,src/**/*.js", "exclude_files": "tests/**,bin/**,obj/**" } } } } } }, "responses": { "200": { "description": "Analysis successfully started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "message": "Analysis started" } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Error running analysis" } } } } } } }, "/api/analysis/results": { "post": { "summary": "Get Analysis Results", "description": "Retrieves the analysis results for a specific repository and commit", "operationId": "getAnalysisResults", "tags": [ "Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisResultsRequest" }, "examples": { "github": { "summary": "GitHub repository example", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github" } }, "azuredevops": { "summary": "Azure DevOps repository example", "value": { "repo": "organization/project/repository", "commit_id": "abc123def456", "access_token": "pat_xxxxxxxxxxxx", "service": "azuredevops" } } } } } }, "responses": { "200": { "description": "Analysis results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisResults" }, "example": { "security_issues": [ { "type": "SQL Injection", "severity": "high", "file": "src/database.py", "line": 42, "description": "Potential SQL injection vulnerability" } ], "summary": { "total_issues": 1, "high_severity": 1, "medium_severity": 0, "low_severity": 0 } } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid" } } } }, "404": { "description": "No scan results found for the provided branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "No scan results found for branch 'main'", "message": "No scans have been run for this branch" } } } } } } }, "/api/analysis/results/sbom": { "post": { "summary": "Get SBOM Results", "description": "Retrieves the Software Bill of Materials (SBOM) results for a specific repository and commit", "operationId": "getSBOMResults", "tags": [ "Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SBOMRequest" }, "examples": { "github": { "summary": "GitHub repository example", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github" } } } } } }, "responses": { "200": { "description": "SBOM results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SBOMResponse" }, "example": { "results": { "rootFolder": "/mnt/lambda/owner/repository/abc123def456", "timestamp": null, "sboms": [ { "language": "Python", "sourceFile": "/tmp/requirements.txt", "packages": [ { "name": "requests", "version": "2.28.0", "licenseDeclared": "Apache-2.0", "licenseConcluded": "Apache-2.0", "licenseReason": "NOASSERTION", "licenseStandard": true, "copyleftStrength": "permissive", "policyLevel": "allow", "policyNote": "Permissive license: keep license and notices", "spdxId": "Apache-2.0" } ], "packagesCount": 1 } ] }, "status": "done", "commit_id": "abc123def456" } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Error retrieving SBOM results" } } } } } } }, "/api/analysis/results/secrets": { "post": { "summary": "Get Secrets Scan Results", "description": "Retrieves the secrets scanning results for a specific repository and commit", "operationId": "getSecretsResults", "tags": [ "Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretsRequest" }, "examples": { "github": { "summary": "GitHub repository example", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github" } } } } } }, "responses": { "200": { "description": "Secrets scan results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretsResponse" }, "example": { "results": { "secrets": [ { "type": "Secret Keyword", "filename": "/mnt/lambda/owner/repository/abc123def456/src/config.py", "hashed_secret": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684", "is_verified": false, "line_number": 14, "confidence_score": "FALSE_POSITIVE" } ], "secretsCount": 1 }, "status": "done", "commit_id": "abc123def456" } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Error retrieving secrets scan results" } } } } } } }, "/api/analysis/results/antipatterns": { "post": { "summary": "Get Anti-patterns Results", "description": "Retrieves the code anti-patterns and code smell detection results for a specific repository and commit", "operationId": "getAntiPatternsResults", "tags": [ "Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AntiPatternsRequest" }, "examples": { "github": { "summary": "GitHub repository example", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github" } } } } } }, "responses": { "200": { "description": "Anti-patterns results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AntiPatternsResponse" }, "example": { "results": { "owner/repository/abc123def456/src/utils.py/anti_patterns.json": [ { "line_number": 42, "endLine": null, "issue_text": "TODO: Implement timeout for requests", "type": "CODE_SMELL", "message-id": "W0511", "fixAvailable": false, "symbol": "fixme", "column": 9, "endColumn": null, "severity": "Minor", "context_code_block": "def fetch_data(url):\n headers = {\"Authorization\": f\"Bearer {token}\"}\n # TODO: Implement timeout for requests\n response = requests.get(url, headers=headers)\n if response.status_code == 200:\n return response.json()\n return None" } ] } } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Error retrieving anti-patterns results" } } } } } } }, "/api/analysis/results/iac": { "post": { "summary": "Get IaC Scan Results", "description": "Retrieves Infrastructure as Code (IaC) security scanning results for a specific repository and commit", "operationId": "getIaCResults", "tags": [ "Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IaCRequest" }, "examples": { "github": { "summary": "GitHub repository example", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github" } } } } } }, "responses": { "200": { "description": "IaC scan results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IaCResponse" }, "example": { "results": [ { "check_type": "terraform", "results": { "failed_checks": [ { "bc_check_id": "BC_AWS_NETWORKING_31", "check_id": "CKV_AWS_23", "check_name": "Ensure every security group and rule has a description", "file_path": "/owner/repository/abc123def456/terraform/main.tf", "file_line_range": [ 2, 25 ], "check_class": "checkov.terraform.checks.resource.aws.SecurityGroupRuleDescription", "code_block": [ [ 2, "resource \"aws_security_group\" \"web\" {\n" ], [ 3, " name_prefix = \"web-sg\"\n" ], [ 4, "\n" ], [ 5, " ingress {\n" ], [ 6, " from_port = 22\n" ], [ 7, " to_port = 22\n" ], [ 8, " protocol = \"tcp\"\n" ], [ 9, " cidr_blocks = [\"0.0.0.0/0\"]\n" ], [ 10, " }\n" ], [ 11, "\n" ], [ 12, " ingress {\n" ], [ 13, " from_port = 80\n" ], [ 14, " to_port = 80\n" ], [ 15, " protocol = \"tcp\"\n" ], [ 16, " cidr_blocks = [\"0.0.0.0/0\"]\n" ], [ 17, " }\n" ], [ 18, "\n" ], [ 19, " egress {\n" ], [ 20, " from_port = 0\n" ], [ 21, " to_port = 0\n" ], [ 22, " protocol = \"-1\"\n" ], [ 23, " cidr_blocks = [\"0.0.0.0/0\"]\n" ], [ 24, " }\n" ], [ 25, "}\n" ] ], "resource": "aws_security_group.web", "start_line": 2, "end_line": 25 } ] } } ] } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Error retrieving IaC scan results" } } } } } } }, "/api/analysis/results/full_report": { "post": { "summary": "Get Full Analysis Report", "description": "Generates a sectioned CSV analysis report for a specific repository and commit, covering up to ten categories: SAST, Secrets, SCA, IaC, Anti-Patterns, Complex Functions, Docstring, Duplicate Code, Dead Code, and SBOM. Each category is emitted as its own labeled section with category-specific columns. By default, issues dismissed via the admin UI's dismiss-alerts workflow and issues flagged as false positives are excluded - use `include_dismissed` / `include_false_positives` to override. Returns a presigned URL for the resulting CSV.", "operationId": "getFullReport", "tags": [ "Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullReportRequest" }, "examples": { "github": { "summary": "GitHub repository example with default fields", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github", "branch": "main", "fields": [ "Static Application Security Testing (SAST)", "Secrets", "Software Composition Analysis (SCA)", "Infrastructure as Code", "Anti-Patterns", "Complex Functions", "Docstring", "Duplicate Code", "Dead Code", "SBOM" ] } }, "githubIncludeDismissed": { "summary": "Include dismissed issues and false positives", "value": { "repo": "owner/repository", "commit_id": "abc123def456", "access_token": "ghp_xxxxxxxxxxxx", "service": "github", "branch": "main", "include_dismissed": true, "include_false_positives": true } }, "azuredevops": { "summary": "Azure DevOps repository example", "value": { "repo": "organization/project/repository", "commit_id": "abc123def456", "access_token": "pat_xxxxxxxxxxxx", "service": "azuredevops", "branch": "develop", "azure_devops_base_url": "https://dev.azure.com" } }, "gitlab": { "summary": "GitLab repository example", "value": { "repo": "group/repository", "commit_id": "abc123def456", "access_token": "glpat_xxxxxxxxxxxx", "service": "gitlab", "branch": "main", "gitlab_base_url": "https://gitlab.com" } }, "bitbucket": { "summary": "Bitbucket repository example", "value": { "repo": "workspace/repository", "commit_id": "abc123def456", "access_token": "bitbucket_token", "service": "bitbucket", "branch": "main", "bitbucket_base_url": "https://api.bitbucket.org/2.0" } } } } } }, "responses": { "200": { "description": "Full report generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullReportResponse" }, "example": { "report_url": "https://storage.example.com/reports/owner-repository-abc123def456.html", "status": "success", "commit_id": "abc123def456", "branch": "main" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing required parameters: repo, commit_id, access_token, service" } } } }, "401": { "description": "Invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Error generating full report: Failed to fetch analysis results" } } } } } } }, "/api/analysis/scan-history": { "post": { "summary": "Get Scan History", "description": "Retrieves the scan history for a repository, returning the last analysis results for each commit that has been scanned", "operationId": "getScanHistory", "tags": [ "Analysis" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanHistoryRequest" }, "examples": { "github": { "summary": "GitHub repository example", "value": { "repo": "owner/repository", "platform": "github", "org": "owner", "github_base_url": "https://github.com" } }, "gitlab": { "summary": "GitLab repository example", "value": { "repo": "group/repository", "platform": "gitlab", "org": "group", "gitlab_base_url": "https://gitlab.com" } }, "azuredevops": { "summary": "Azure DevOps repository example", "value": { "repo": "organization/project/repository", "platform": "azuredevops", "org": "organization", "azure_devops_base_url": "https://dev.azure.com" } } } } } }, "responses": { "200": { "description": "Scan history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanHistoryResponse" }, "example": { "repo": "owner/repository", "last_analysis_results": [ { "commit_id": "abc123def456", "branch": "main", "timestamp": "2025-01-15T10:30:00Z", "status": "completed" } ] } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing required parameter: repo" } } } }, "401": { "description": "Invalid or missing access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid or does not have access to this organization" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/create": { "post": { "summary": "Create Team", "description": "Creates a new developer team. Teams can be organized around **developers** (by adding members), **repositories** (by assigning repos), or **both**. You can also create empty teams and add members/repos later via the update and member endpoints.\n\nUse cases:\n- **Developer-based team**: Pass `members` to group developers (e.g. a frontend squad). You can optionally pass `repositories` as a filter to scope metrics to specific repos for this team.\n- **Repository-based team**: Pass only `repositories` to group repos (e.g. all microservices). No members - metrics are aggregated across the listed repos.\n- **Mixed team**: Pass both `members` and `repositories` - metrics are scoped to these members across these repos.\n- **Disabled lists**: Create special teams named `codeant-disabled-members` or `codeant-disabled-repos` to exclude specific developers or repositories from all metrics calculations across the organization.\n\nOptionally assign one or more `team_leads` (by login) and categorize teams with `tags`. Teams can be nested using `parent_team_id`.", "operationId": "createTeam", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" }, "examples": { "github": { "summary": "GitHub - developer-based team", "value": { "platform": "github", "org": "my-org", "name": "Backend Squad", "description": "Backend API developers", "members": [ { "user_login": "jane@example.com", "user_name": "Jane Doe", "role": "lead" }, { "user_login": "john@example.com", "user_name": "John Smith", "role": "member" } ], "team_leads": [ "jane@example.com" ] } }, "gitlab": { "summary": "GitLab - repository-based team", "value": { "platform": "gitlab", "org": "my-group", "name": "Microservices", "description": "All microservice repositories", "repositories": [ "my-group/auth-service", "my-group/payment-service", "my-group/user-service" ] } }, "bitbucket": { "summary": "Bitbucket - mixed team (members + repos)", "value": { "platform": "bitbucket", "org": "my-workspace", "name": "Platform Team", "description": "Platform engineering team and their repos", "members": [ { "user_login": "alice@example.com", "user_name": "Alice", "role": "lead" } ], "repositories": [ "my-workspace/infra", "my-workspace/ci-tools" ], "tags": [ "platform", "infra" ] } }, "azure_devops": { "summary": "Azure DevOps - empty team (add members later)", "value": { "platform": "azure_devops", "org": "my-org", "name": "New Project Team", "description": "Team for the upcoming project" } } } } } }, "responses": { "201": { "description": "Team created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Team created successfully" }, "team": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/list": { "post": { "summary": "List Teams", "description": "Returns all teams for the given organization. By default only active teams are returned; set `include_inactive: true` to include soft-deleted teams.", "operationId": "listTeams", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DevMetricsBaseRequest" }, { "type": "object", "properties": { "include_inactive": { "type": "boolean", "default": false, "description": "Include soft-deleted (inactive) teams" } } } ] }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org" } } } } } }, "responses": { "200": { "description": "List of teams", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "total_count": { "type": "integer", "description": "Number of teams returned" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/get": { "post": { "summary": "Get Team", "description": "Retrieves a single team by its ID, including full member list and repository assignments.", "operationId": "getTeam", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamIdRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } } } } } }, "responses": { "200": { "description": "Team details", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "team": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Team not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/update": { "post": { "summary": "Update Team", "description": "Updates team metadata such as name, description, color, team leads, tags, or assigned repositories. Only include the fields you want to change - omitted fields are left unchanged.", "operationId": "updateTeam", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamRequest" }, "examples": { "github": { "summary": "GitHub - rename + update leads", "value": { "platform": "github", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "name": "Backend Team v2", "description": "Updated description", "team_leads": [ "alice", "bob" ] } }, "gitlab": { "summary": "GitLab - change color + repos", "value": { "platform": "gitlab", "org": "my-group", "gitlab_base_url": "https://gitlab.com", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "color": "#EF4444", "repositories": [ "my-group/api", "my-group/web" ] } }, "bitbucket": { "summary": "Bitbucket - rename", "value": { "platform": "bitbucket", "org": "my-workspace", "bitbucket_base_url": "https://api.bitbucket.org/2.0", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "name": "Backend Team v2" } }, "azure_devops": { "summary": "Azure DevOps - update tags", "value": { "platform": "azure_devops", "org": "my-org", "azure_devops_base_url": "https://dev.azure.com", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "tags": [ "backend", "infrastructure" ] } } } } } }, "responses": { "200": { "description": "Team updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Team updated successfully" }, "team": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Team not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/delete": { "post": { "summary": "Delete Team", "description": "Deletes a team. By default performs a **soft delete** (marks the team as inactive). Set `hard_delete: true` to permanently remove the team and its data.", "operationId": "deleteTeam", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTeamRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d" } } } } } }, "responses": { "200": { "description": "Team deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "success", "message": "Team deleted successfully" } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Team not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/members/add": { "post": { "summary": "Add Team Member", "description": "Adds a new member to a team. The `user_login` must be unique within the team.", "operationId": "addTeamMember", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "user_name": "Jane Doe", "role": "member" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "user_name": "Jane Doe", "role": "member" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "user_name": "Jane Doe", "role": "member" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "user_name": "Jane Doe", "role": "member" } } } } } }, "responses": { "200": { "description": "Member added", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Member added successfully" }, "member": { "$ref": "#/components/schemas/TeamMember" }, "team": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Team not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/members/remove": { "post": { "summary": "Remove Team Member", "description": "Removes a member from a team by their `user_login`.", "operationId": "removeTeamMember", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com" } } } } } }, "responses": { "200": { "description": "Member removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Member removed successfully" }, "team": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Team not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/teams/members/update": { "post": { "summary": "Update Team Member", "description": "Updates a team member's role or display name.", "operationId": "updateTeamMember", "tags": [ "Developer Metrics - Teams" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "role": "lead" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "role": "lead" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "role": "lead" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "team_id": "15884668-91e2-4def-9d20-b7cf4698117d", "user_login": "jane@example.com", "role": "lead" } } } } } }, "responses": { "200": { "description": "Member updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Member updated successfully" }, "team": { "$ref": "#/components/schemas/Team" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Team not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/comparison/get": { "post": { "summary": "Get Developer Comparison", "description": "Retrieves a developer's productivity metrics compared against the organization average. Includes commit activity, PR statistics, code review contributions, and more. Useful for individual performance dashboards and 1:1 reviews.", "operationId": "getDevComparison", "tags": [ "Developer Metrics" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevComparisonRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "author": "janedoe", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "author": "janedoe", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "author": "janedoe", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "author": "janedoe", "start_date": "2025-01-01", "end_date": "2025-03-01" } } } } } }, "responses": { "200": { "description": "Developer comparison data", "content": { "application/json": { "schema": { "type": "object", "properties": { "metric": { "type": "string", "example": "dev_comparison" }, "platform": { "type": "string" }, "org": { "type": "string" }, "author": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "org_context": { "type": "object", "description": "Organization-wide averages and context data" }, "developer": { "type": "object", "description": "Individual developer metrics and activity data" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/summary/get": { "post": { "summary": "Get Developer Summary", "description": "Generates an AI-powered natural-language summary of a developer's contributions across the specified repositories and date range. Includes PR descriptions and an overall narrative of work done. If `repositories` is omitted, all repositories under the organization are used.", "operationId": "getDevSummary", "tags": [ "Developer Metrics" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevSummaryRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "author": "janedoe", "repositories": [ "my-org/backend-api" ], "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "author": "janedoe", "repositories": [ "my-group/backend-api" ], "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "author": "janedoe", "repositories": [ "my-workspace/backend-api" ], "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "author": "janedoe", "repositories": [ "my-org/backend-api" ], "start_date": "2025-01-01", "end_date": "2025-03-01" } } } } } }, "responses": { "200": { "description": "Developer summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "metric": { "type": "string", "example": "dev_summary" }, "platform": { "type": "string" }, "org": { "type": "string" }, "author": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "summary": { "type": "string", "description": "AI-generated natural-language summary of the developer's work" }, "pr_descriptions": { "type": "array", "items": { "type": "string" }, "description": "Descriptions of PRs included in the analysis" }, "execution_time": { "type": "number", "description": "Time taken to generate the summary (seconds)" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: author, start_date, end_date" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "404": { "description": "No repositories found for the organization (when `repositories` is omitted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "No repositories found for this organization" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/devs/active/get": { "post": { "summary": "Get Active Developers", "description": "Returns all developers who made commits in the organization during the specified date range. Includes per-developer statistics: commit counts, lines added/deleted, language breakdown, coding day distribution, and repository contributions. Useful for team activity dashboards and headcount tracking.", "operationId": "getActiveDevs", "tags": [ "Developer Metrics" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DateRangeRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "start_date": "2025-01-01", "end_date": "2025-03-01" } } } } } }, "responses": { "200": { "description": "Active developers list", "content": { "application/json": { "schema": { "type": "object", "properties": { "metric": { "type": "string", "example": "active_developers" }, "platform": { "type": "string" }, "org": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "active_developers": { "type": "array", "items": { "$ref": "#/components/schemas/ActiveDeveloper" } }, "total_count": { "type": "integer", "description": "Number of active developers" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/metrics/developer/prs/get": { "post": { "summary": "Get Developer PR Data", "description": "Returns pull request activity for all developers in the organization during the specified date range. Includes open/merged/closed PR counts, code change statistics, and detailed PR listings per developer. Useful for code review dashboards and throughput analysis.", "operationId": "getDeveloperPRData", "tags": [ "Developer Metrics" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DateRangeRequest" }, "examples": { "github": { "summary": "GitHub", "value": { "platform": "github", "org": "my-org", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "gitlab": { "summary": "GitLab", "value": { "platform": "gitlab", "org": "my-group", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "bitbucket": { "summary": "Bitbucket", "value": { "platform": "bitbucket", "org": "my-workspace", "start_date": "2025-01-01", "end_date": "2025-03-01" } }, "azure_devops": { "summary": "Azure DevOps", "value": { "platform": "azure_devops", "org": "my-org", "start_date": "2025-01-01", "end_date": "2025-03-01" } } } } } }, "responses": { "200": { "description": "Developer PR data", "content": { "application/json": { "schema": { "type": "object", "properties": { "metric": { "type": "string", "example": "developer_pr_data" }, "platform": { "type": "string" }, "org": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "developer_pr_data": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperPRData" } }, "total_count": { "type": "integer", "description": "Number of developers with PR activity" } } } } } }, "400": { "description": "Bad request - missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "example": { "error": "Missing required parameters: platform, org" } } } }, "401": { "description": "Unauthorized - missing, invalid, or insufficient access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsErrorResponse" }, "examples": { "missing_token": { "summary": "Missing Authorization header", "value": { "error": "Missing Authorization header. Use 'Bearer '" } }, "invalid_token": { "summary": "Invalid or insufficient token", "value": { "error": "Access token invalid or does not have access to this organization" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevMetricsStatusResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } } } }, "/api/agents/scan/start": { "post": { "summary": "Start Agent Scan", "description": "Initiates an AI-powered agent analysis for a repository. The agent uses LLM-based code exploration to perform deep security threat hunting, bug finding, or custom analysis based on user-provided instructions. Files are filtered by extension, size (≤400KB), and line count (≤5000 lines), with a maximum of 500 files per scan.", "operationId": "startAgentScan", "tags": [ "Agent Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentScanStartRequest" }, "examples": { "threat_hunting": { "summary": "Threat hunting scan on a GitHub repository", "value": { "service": "github", "repo": "owner/repository", "accessToken": "ghp_xxxxxxxxxxxx", "branch": "main", "instructionPrompt": "threat_hunting", "includeFiles": "src/**/*.py,lib/**/*.js", "excludeFiles": "tests/**,node_modules/**" } } } } } }, "responses": { "200": { "description": "Agent scan successfully started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentScanStartResponse" }, "example": { "message": "Scan started successfully", "scanId": "aB3xK9mP2q", "filesQueued": 142 } } } }, "400": { "description": "Missing required parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing required parameter: instructionPrompt" } } } }, "500": { "description": "Failed to start scan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Failed to start scan" } } } } } } }, "/api/agents/scan/results": { "post": { "summary": "Get Agent Scan Results", "description": "Retrieves the results of an agent analysis scan. If the scan is still in progress, returns a status of `in_progress`. Once complete, returns deduplicated issues found across all analyzed files. Issues are deduplicated using LLM-based analysis to remove duplicate findings across files.", "operationId": "getAgentScanResults", "tags": [ "Agent Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentScanResultsRequest" }, "example": { "repo": "owner/repository", "scanId": "aB3xK9mP2q" } } } }, "responses": { "200": { "description": "Scan results retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentScanResultsResponse" }, "examples": { "completed": { "summary": "Completed scan with results", "value": { "scanId": "aB3xK9mP2q", "repoName": "owner/repository", "status": "completed", "results": [ { "file": "src/auth/login.py", "scan_id": "aB3xK9mP2q", "issues": [ { "relevant_file": "src/auth/login.py", "language": "python", "suggestion_content": "The `authenticate` function does not validate the length of the password parameter before passing it to the bcrypt hashing function. Extremely long passwords (>72 bytes) are silently truncated by bcrypt, which could lead to collision vulnerabilities.", "start_line": 45, "end_line": 52, "one_sentence_summary": "Password length not validated before bcrypt hashing", "label": "Security", "severity": "medium", "cwe_id": "CWE-916", "agent_instructions": "threat_hunting" } ] } ], "totalIssues": 1 } }, "in_progress": { "summary": "Scan still in progress", "value": { "scanId": "aB3xK9mP2q", "repoName": "owner/repository", "status": "in_progress", "results": [], "totalIssues": 0 } } } } } }, "404": { "description": "Scan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Scan not found" } } } }, "500": { "description": "Failed to retrieve scan results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Failed to retrieve scan results" } } } } } } }, "/api/agents/scan/history": { "post": { "summary": "Get Agent Scan History", "description": "Retrieves the history of all agent analysis scans for a repository, sorted by most recent first. Each entry includes metadata about the scan such as the branch, commit, prompt used, and number of files analyzed.", "operationId": "getAgentScanHistory", "tags": [ "Agent Analysis" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentScanHistoryRequest" }, "example": { "repo": "owner/repository" } } } }, "responses": { "200": { "description": "Scan history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentScanHistoryResponse" }, "example": { "scans": [ { "service": "github", "repo_name": "owner/repository", "branch": "main", "commit_id": "abc123def456", "scan_id": "aB3xK9mP2q", "prompt": "threat_hunting", "timestamp": "2025-03-15T10:30:00Z", "num_files": 142 }, { "service": "github", "repo_name": "owner/repository", "branch": "develop", "commit_id": "def456ghi789", "scan_id": "zY8wV7uT6s", "prompt": "bug_finding", "timestamp": "2025-03-14T08:15:00Z", "num_files": 98 } ] } } } }, "400": { "description": "Missing or invalid repo parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing or invalid repo parameter" } } } }, "500": { "description": "Failed to retrieve scan history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Failed to retrieve scan history" } } } } } } }, "/api/audit/events": { "post": { "summary": "List Audit Events", "description": "Retrieves your organization's audit events oldest-first with cursor pagination. Designed for incremental ingestion: pass `since` (or the previous `next_cursor`) on each run to fetch only new events. Authenticate with a CodeAnt API token (requires the `settings_organization: read` permission when token scoping is configured). Every call to this endpoint is itself recorded in the audit log as `audit_log.api_read`.", "operationId": "listAuditEvents", "tags": [ "Audit Logs" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventsRequest" }, "examples": { "basic": { "summary": "Last 7 days (default range)", "value": { "platform": "github", "org": "Example-Org" } }, "incremental": { "summary": "Incremental ETL pull since a timestamp", "value": { "platform": "github", "org": "Example-Org", "since": "2026-07-30T00:00:00Z", "limit": 1000 } }, "ndjson": { "summary": "NDJSON file for a custom range", "value": { "platform": "gitlab", "org": "example-group", "start_date": "2026-07-01", "end_date": "2026-07-31", "format": "ndjson" } } } } } }, "responses": { "200": { "description": "Audit events retrieved successfully. With `format: ndjson` or `csv` the body is the raw file instead, and paging moves to the `X-Next-Cursor` and `X-Has-More` response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventsResponse" }, "example": { "org": "Example-Org", "service": "github", "base_url_domain": "github.com", "start_date": "2026-07-24", "end_date": "2026-07-31", "retention_days": 180, "count": 2, "has_more": false, "next_cursor": "Y29kZWFudC1hdWRpdC1sb2dzLzIwMjYtMDctMzAvLi4u", "events": [ { "event_id": "a3f9c2e1b4d84f7a9c0e5d6b7a8f9012", "timestamp": "2026-07-30T09:14:03.512345Z", "action": "rbac.role_update", "description": "Access control: role update", "actor_type": "user", "actor_id": "harshit-dubey", "actor_email": "admin@example.com", "org": "Example-Org", "service": "github", "base_url_domain": "github.com", "source": "ui", "target_type": "rbac", "target_id": "role_7d2f", "target_name": "Security Reviewer", "outcome": "success", "status_code": 200, "method": "POST", "path": "/settings/rbac/roles/update", "ip": "203.0.113.42", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)", "request_id": "req_01J1ZX2Y3A4B5C6D", "changes": { "permissions": { "before": "read", "after": "write" } }, "details": { "role_name": "Security Reviewer" } }, { "event_id": "c1a2b3d4e5f60718293a4b5c6d7e8f90", "timestamp": "2026-07-30T10:00:00.000000Z", "action": "analysis.scan_trigger", "description": "Analysis: scan trigger", "actor_type": "system", "actor_id": "codeant-internal-queue", "actor_email": null, "org": "Example-Org", "service": "github", "base_url_domain": "github.com", "source": "scheduled_job", "target_type": "analysis", "target_id": null, "target_name": "example-org/payments-api", "outcome": "success", "status_code": 200, "method": "POST", "path": "/doAnalysis", "ip": "10.0.4.18", "user_agent": "python-requests/2.32.0", "request_id": "req_01J1ZXB2C3D4E5F6", "changes": null, "details": { "reponame": "example-org/payments-api", "branch": "main" } } ] } } } }, "400": { "description": "Invalid parameters (e.g. malformed `since` timestamp)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Invalid `since` — use an ISO 8601 timestamp" } } } }, "401": { "description": "Invalid or missing access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Access token invalid or does not have access to this organization" } } } } } } } }, "components": { "schemas": { "AnalysisStartRequest": { "type": "object", "required": [ "repo", "commit_id", "access_token", "service" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "commit_id": { "type": "string", "description": "Git commit SHA or identifier", "example": "abc123def456" }, "access_token": { "type": "string", "description": "Authentication token for the service", "example": "ghp_xxxxxxxxxxxx" }, "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" }, "branch": { "type": "string", "description": "Git branch name", "example": "main" }, "include_files": { "type": "string", "description": "Comma-separated file patterns to include in analysis", "example": "src/**/*.py,lib/**/*.js,app/**/*.ts" }, "exclude_files": { "type": "string", "description": "Comma-separated file patterns to exclude from analysis", "example": "tests/**,node_modules/**,dist/**" } } }, "AnalysisResultsRequest": { "type": "object", "required": [ "repo", "access_token", "service" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "commit_id": { "type": "string", "description": "Git commit SHA or identifier. Either commit_id or branch is required. If both are provided, commit_id takes precedence.", "example": "abc123def456" }, "branch": { "type": "string", "description": "Git branch name. When provided without commit_id, the service resolves the latest commit from scan history for this branch. Either commit_id or branch is required.", "example": "main" }, "access_token": { "type": "string", "description": "Authentication token for the service", "example": "ghp_xxxxxxxxxxxx" }, "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" } } }, "SBOMRequest": { "type": "object", "required": [ "repo", "access_token", "service" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "commit_id": { "type": "string", "description": "Git commit SHA or identifier. Either commit_id or branch is required. If both are provided, commit_id takes precedence.", "example": "abc123def456" }, "branch": { "type": "string", "description": "Git branch name. When provided without commit_id, the service resolves the latest commit from scan history for this branch. Either commit_id or branch is required.", "example": "main" }, "access_token": { "type": "string", "description": "Authentication token for the service", "example": "ghp_xxxxxxxxxxxx" }, "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" }, "gitlab_base_url": { "type": "string", "description": "Base URL for the service (optional for GitHub, required for GitLab)", "example": "https://gitlab.com" } } }, "SecretsRequest": { "type": "object", "required": [ "repo", "access_token", "service" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "commit_id": { "type": "string", "description": "Git commit SHA or identifier. Either commit_id or branch is required. If both are provided, commit_id takes precedence.", "example": "abc123def456" }, "branch": { "type": "string", "description": "Git branch name. When provided without commit_id, the service resolves the latest commit from scan history for this branch. Either commit_id or branch is required.", "example": "main" }, "access_token": { "type": "string", "description": "Authentication token for the service", "example": "ghp_xxxxxxxxxxxx" }, "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" }, "gitlab_base_url": { "type": "string", "description": "Base URL for the service (optional for GitHub, required for GitLab)", "example": "https://gitlab.com" } } }, "AntiPatternsRequest": { "type": "object", "required": [ "repo", "access_token", "service" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "commit_id": { "type": "string", "description": "Git commit SHA or identifier. Either commit_id or branch is required. If both are provided, commit_id takes precedence.", "example": "abc123def456" }, "branch": { "type": "string", "description": "Git branch name. When provided without commit_id, the service resolves the latest commit from scan history for this branch. Either commit_id or branch is required.", "example": "main" }, "access_token": { "type": "string", "description": "Authentication token for the service", "example": "ghp_xxxxxxxxxxxx" }, "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" }, "gitlab_base_url": { "type": "string", "description": "Base URL for the service (optional for GitHub, required for GitLab)", "example": "https://gitlab.com" } } }, "IaCRequest": { "type": "object", "required": [ "repo", "access_token", "service" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "commit_id": { "type": "string", "description": "Git commit SHA or identifier. Either commit_id or branch is required. If both are provided, commit_id takes precedence.", "example": "abc123def456" }, "branch": { "type": "string", "description": "Git branch name. When provided without commit_id, the service resolves the latest commit from scan history for this branch. Either commit_id or branch is required.", "example": "main" }, "access_token": { "type": "string", "description": "Authentication token for the service", "example": "ghp_xxxxxxxxxxxx" }, "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" }, "gitlab_base_url": { "type": "string", "description": "Base URL for the service (optional for GitHub, required for GitLab)", "example": "https://gitlab.com" } } }, "ScanHistoryRequest": { "type": "object", "required": [ "repo", "platform", "org" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by platform)", "example": "owner/repository" }, "platform": { "type": "string", "description": "Version control platform", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" }, "org": { "type": "string", "description": "Organization or workspace name", "example": "owner" }, "github_base_url": { "type": "string", "description": "GitHub base URL (for self-hosted instances)", "default": "https://github.com" }, "gitlab_base_url": { "type": "string", "description": "GitLab base URL (for self-hosted instances)", "default": "https://gitlab.com" }, "azure_devops_base_url": { "type": "string", "description": "Azure DevOps base URL", "default": "https://dev.azure.com" }, "bitbucket_base_url": { "type": "string", "description": "Bitbucket base URL (for self-hosted instances)", "default": "https://api.bitbucket.org/2.0" } } }, "ScanHistoryResponse": { "type": "object", "properties": { "repo": { "type": "string", "description": "Repository identifier" }, "last_analysis_results": { "type": "array", "description": "List of last analysis results for each scanned commit", "items": { "type": "object" } } } }, "SuccessResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } }, "AnalysisResults": { "type": "object", "description": "Analysis results containing security issues and summary", "properties": { "security_issues": { "type": "array", "description": "List of security issues found", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of security issue" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ], "description": "Severity level of the issue" }, "file": { "type": "string", "description": "File path where issue was found" }, "line": { "type": "integer", "description": "Line number where issue was found" }, "description": { "type": "string", "description": "Detailed description of the issue" } } } }, "summary": { "type": "object", "description": "Summary statistics of the analysis", "properties": { "total_issues": { "type": "integer", "description": "Total number of issues found" }, "critical_severity": { "type": "integer", "description": "Number of critical severity issues" }, "high_severity": { "type": "integer", "description": "Number of high severity issues" }, "medium_severity": { "type": "integer", "description": "Number of medium severity issues" }, "low_severity": { "type": "integer", "description": "Number of low severity issues" }, "info_severity": { "type": "integer", "description": "Number of informational issues" } } } } }, "SBOMResponse": { "type": "object", "description": "Software Bill of Materials (SBOM) response containing package and license information", "properties": { "results": { "type": "object", "description": "SBOM analysis results", "properties": { "rootFolder": { "type": "string", "description": "Root folder path where the analysis was performed", "example": "/mnt/lambda/owner/repository/abc123def456" }, "timestamp": { "type": "string", "nullable": true, "description": "Timestamp of the analysis", "example": null }, "sboms": { "type": "array", "description": "List of SBOM entries for different languages", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "Programming language of the packages", "example": "Python" }, "sourceFile": { "type": "string", "description": "Source file containing package information", "example": "/tmp/superRequirements.txt" }, "packages": { "type": "array", "description": "List of packages found in the source file", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Package name", "example": "@alloc/quick-lru" }, "version": { "type": "string", "description": "Package version or hash", "example": "5.2.0" }, "licenseDeclared": { "type": "string", "description": "Declared license for the package", "example": "MIT" }, "licenseConcluded": { "type": "string", "description": "Concluded license after analysis", "example": "MIT" }, "licenseReason": { "type": "string", "description": "Reason for license determination", "example": "NOASSERTION" }, "licenseStandard": { "type": "boolean", "description": "Whether the license is a standard license", "example": true }, "copyleftStrength": { "type": "string", "description": "Copyleft strength classification", "enum": [ "permissive", "weak", "strong", "proprietary_or_unknown" ], "example": "permissive" }, "policyLevel": { "type": "string", "description": "Policy compliance level", "enum": [ "allow", "review", "deny" ], "example": "allow" }, "policyNote": { "type": "string", "description": "Notes about policy requirements", "example": "Permissive license: keep license and notices" }, "spdxId": { "type": "string", "nullable": true, "description": "SPDX identifier for the license", "example": "MIT" }, "badTerms": { "type": "array", "description": "List of concerning license terms", "items": { "type": "object", "properties": { "tag": { "type": "string", "description": "Tag identifying the concerning term", "example": "modifications_must_be_public" }, "start": { "type": "integer", "description": "Start position of the term in license text", "example": 246 }, "end": { "type": "integer", "description": "End position of the term in license text", "example": 268 }, "evidence": { "type": "string", "description": "Excerpt of the concerning text", "example": "out limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell co" } } } } } } }, "packagesCount": { "type": "integer", "description": "Total number of packages found", "example": 1 } } } } } }, "status": { "type": "string", "description": "Status of the SBOM analysis", "enum": [ "pending", "processing", "done", "failed" ], "example": "done" }, "commit_id": { "type": "string", "description": "Git commit SHA that was analyzed", "example": "abc123def456" } } }, "SecretsResponse": { "type": "object", "description": "Secrets scanning response containing detected secrets and sensitive information", "properties": { "results": { "type": "object", "description": "Secrets scanning results", "properties": { "secrets": { "type": "array", "description": "List of secrets detected", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of secret detected", "example": "Secret Keyword" }, "filename": { "type": "string", "description": "Full file path where secret was found", "example": "/mnt/lambda/owner/repository/abc123def456/src/config.py" }, "hashed_secret": { "type": "string", "description": "SHA-1 hash of the detected secret", "example": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684" }, "is_verified": { "type": "boolean", "description": "Whether the secret has been verified", "example": false }, "line_number": { "type": "integer", "description": "Line number where secret was found", "example": 14 }, "confidence_score": { "type": "string", "description": "Confidence level of the detection", "enum": [ "TRUE_POSITIVE", "FALSE_POSITIVE", "UNKNOWN" ], "example": "FALSE_POSITIVE" } } } }, "secretsCount": { "type": "integer", "description": "Total number of secrets found", "example": 1 } } }, "status": { "type": "string", "description": "Status of the secrets scan", "enum": [ "pending", "processing", "done", "failed" ], "example": "done" }, "commit_id": { "type": "string", "description": "Git commit SHA that was analyzed", "example": "abc123def456" } } }, "AntiPatternsResponse": { "type": "object", "description": "Anti-patterns response containing detected code smells and anti-patterns", "properties": { "results": { "type": "object", "description": "Anti-patterns analysis results organized by file path", "additionalProperties": { "type": "array", "description": "List of anti-patterns detected in the file", "items": { "type": "object", "properties": { "line_number": { "type": "integer", "description": "Starting line number where anti-pattern was found", "example": 42 }, "endLine": { "type": "integer", "nullable": true, "description": "Ending line number where anti-pattern was found", "example": null }, "issue_text": { "type": "string", "description": "Description of the anti-pattern issue", "example": "TODO: Implement timeout for requests" }, "type": { "type": "string", "description": "Type of issue detected", "enum": [ "CODE_SMELL", "BUG", "VULNERABILITY", "SECURITY_HOTSPOT" ], "example": "CODE_SMELL" }, "message-id": { "type": "string", "description": "Unique identifier for the message type", "example": "W0511" }, "fixAvailable": { "type": "boolean", "description": "Whether an automated fix is available", "example": false }, "symbol": { "type": "string", "description": "Symbol or code identifier for the issue", "example": "fixme" }, "column": { "type": "integer", "description": "Starting column number", "example": 9 }, "endColumn": { "type": "integer", "nullable": true, "description": "Ending column number", "example": null }, "severity": { "type": "string", "description": "Severity level of the anti-pattern", "enum": [ "Critical", "Major", "Minor", "Info" ], "example": "Minor" }, "context_code_block": { "type": "string", "description": "Code block providing context around the issue", "example": "def fetch_data(url):\n headers = {\"Authorization\": f\"Bearer {token}\"}\n # TODO: Implement timeout for requests\n response = requests.get(url, headers=headers)\n if response.status_code == 200:\n return response.json()\n return None" } } } }, "example": { "owner/repository/abc123def456/src/utils.py/anti_patterns.json": [ { "line_number": 42, "endLine": null, "issue_text": "TODO: Implement timeout for requests", "type": "CODE_SMELL", "message-id": "W0511", "fixAvailable": false, "symbol": "fixme", "column": 9, "endColumn": null, "severity": "Minor", "context_code_block": "def fetch_data(url):\n headers = {\"Authorization\": f\"Bearer {token}\"}\n # TODO: Implement timeout for requests\n response = requests.get(url, headers=headers)\n if response.status_code == 200:\n return response.json()\n return None" } ] } } } }, "IaCResponse": { "type": "object", "description": "Infrastructure as Code (IaC) scanning response containing security check results", "properties": { "results": { "type": "array", "description": "List of IaC scan results by check type", "items": { "type": "object", "properties": { "check_type": { "type": "string", "description": "Type of IaC framework checked", "example": "terraform" }, "results": { "type": "object", "description": "Check results for this framework", "properties": { "failed_checks": { "type": "array", "description": "List of failed security checks", "items": { "type": "object", "properties": { "bc_check_id": { "type": "string", "description": "Bridgecrew check identifier", "example": "BC_AWS_NETWORKING_31" }, "check_id": { "type": "string", "description": "Checkov check identifier", "example": "CKV_AWS_23" }, "check_name": { "type": "string", "description": "Human-readable name of the security check", "example": "Ensure every security group and rule has a description" }, "file_path": { "type": "string", "description": "Path to the file with the issue", "example": "/owner/repository/abc123def456/terraform/main.tf" }, "file_line_range": { "type": "array", "description": "Line range where the issue occurs", "items": { "type": "integer" }, "example": [ 2, 25 ] }, "check_class": { "type": "string", "description": "Full class path of the check", "example": "checkov.terraform.checks.resource.aws.SecurityGroupRuleDescription" }, "code_block": { "type": "array", "description": "Code lines with line numbers", "items": { "type": "array", "description": "Array containing line number and line content", "minItems": 2, "maxItems": 2 }, "example": [ [ 2, "resource \"aws_security_group\" \"web\" {\n" ], [ 3, " name_prefix = \"web-sg\"\n" ] ] }, "resource": { "type": "string", "description": "Resource identifier in IaC file", "example": "aws_security_group.web" }, "start_line": { "type": "integer", "description": "Starting line number", "example": 2 }, "end_line": { "type": "integer", "description": "Ending line number", "example": 25 } } } } } } } } } } }, "FullReportRequest": { "type": "object", "required": [ "repo", "access_token", "service" ], "properties": { "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "commit_id": { "type": "string", "description": "Git commit SHA or identifier. Either commit_id or branch is required. If both are provided, commit_id takes precedence.", "example": "abc123def456" }, "access_token": { "type": "string", "description": "Authentication token for the service", "example": "ghp_xxxxxxxxxxxx" }, "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "azuredevops", "gitlab", "bitbucket" ], "example": "github" }, "branch": { "type": "string", "description": "Git branch name. When provided without commit_id, the service resolves the latest commit from scan history for this branch. Either commit_id or branch is required.", "example": "main" }, "fields": { "type": "array", "description": "List of analysis categories to include in the sectioned CSV report. Each category becomes its own section with category-specific columns.", "items": { "type": "string", "enum": [ "Static Application Security Testing (SAST)", "Secrets", "Software Composition Analysis (SCA)", "Infrastructure as Code", "Anti-Patterns", "Complex Functions", "Docstring", "Duplicate Code", "Dead Code", "SBOM" ] }, "default": [ "Static Application Security Testing (SAST)", "Secrets", "Software Composition Analysis (SCA)", "Infrastructure as Code", "Anti-Patterns", "Complex Functions", "Docstring", "Duplicate Code", "Dead Code", "SBOM" ], "example": [ "Static Application Security Testing (SAST)", "Secrets", "Software Composition Analysis (SCA)", "Infrastructure as Code", "Anti-Patterns", "Complex Functions", "Docstring", "Duplicate Code", "Dead Code", "SBOM" ] }, "include_dismissed": { "type": "boolean", "description": "When true, dismissed issues (those marked as dismissed via the admin UI's dismiss-alerts workflow) are included in the report. Defaults to false, matching the admin UI behavior where dismissed issues are hidden.", "default": false, "example": false }, "include_false_positives": { "type": "boolean", "description": "When true, issues flagged as false positives are included - specifically SAST issues with false_positive=true and Secrets with confidence_score=FALSE_POSITIVE. Defaults to false.", "default": false, "example": false }, "gitlab_base_url": { "type": "string", "description": "Base URL for GitLab service (optional)", "default": "https://gitlab.com", "example": "https://gitlab.com" }, "github_base_url": { "type": "string", "description": "Base URL for GitHub service (optional)", "default": "https://github.com", "example": "https://github.com" }, "azure_devops_base_url": { "type": "string", "description": "Base URL for Azure DevOps service (optional)", "default": "https://dev.azure.com", "example": "https://dev.azure.com" }, "bitbucket_base_url": { "type": "string", "description": "Base URL for Bitbucket service (optional)", "default": "https://api.bitbucket.org/2.0", "example": "https://api.bitbucket.org/2.0" } } }, "FullReportResponse": { "type": "object", "description": "Full analysis report response containing the report URL and status", "properties": { "report_url": { "type": "string", "description": "URL to access the generated HTML report", "example": "https://storage.example.com/reports/owner-repository-abc123def456.html" }, "status": { "type": "string", "description": "Status of the report generation", "enum": [ "success", "failed" ], "example": "success" }, "commit_id": { "type": "string", "description": "Git commit SHA that was analyzed", "example": "abc123def456" }, "branch": { "type": "string", "description": "Git branch name that was analyzed", "example": "main" } } }, "DevMetricsErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } } }, "DevMetricsStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "error" ] }, "message": { "type": "string", "description": "Human-readable status message" } } }, "DevMetricsBaseRequest": { "type": "object", "required": [ "platform", "org" ], "properties": { "platform": { "type": "string", "description": "Version control platform", "enum": [ "github", "gitlab", "bitbucket", "azure_devops", "azuredevops" ], "example": "github" }, "org": { "type": "string", "description": "Organization, workspace, or group name on the platform", "example": "my-org" }, "github_base_url": { "type": "string", "description": "Base URL for GitHub (use for GitHub Enterprise Server)", "default": "https://github.com", "example": "https://github.com" }, "gitlab_base_url": { "type": "string", "description": "Base URL for GitLab (use for self-hosted GitLab instances)", "default": "https://gitlab.com", "example": "https://gitlab.com" }, "azure_devops_base_url": { "type": "string", "description": "Base URL for Azure DevOps (use for Azure DevOps Server)", "default": "https://dev.azure.com", "example": "https://dev.azure.com" }, "bitbucket_base_url": { "type": "string", "description": "Base URL for Bitbucket (use for Bitbucket Data Center/Server)", "default": "https://api.bitbucket.org/2.0", "example": "https://api.bitbucket.org/2.0" } } }, "TeamMember": { "type": "object", "description": "A member of a team", "properties": { "user_login": { "type": "string", "description": "Unique login/email identifier of the member", "example": "jane@example.com" }, "user_name": { "type": "string", "description": "Display name of the member", "example": "Jane Doe" }, "joined_at": { "type": "string", "format": "date-time", "description": "When the member joined the team" }, "role": { "type": "string", "enum": [ "member", "lead" ], "description": "Role within the team", "example": "member" } } }, "Team": { "type": "object", "description": "A developer team with members, metadata, and repository assignments", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique team identifier" }, "name": { "type": "string", "description": "Team name", "example": "Backend Team" }, "description": { "type": "string", "description": "Team description", "example": "Responsible for API services" }, "color": { "type": "string", "description": "Hex color for UI display", "example": "#1570EF" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "team_leads": { "type": "array", "items": { "type": "string" }, "description": "List of team lead identifiers" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } }, "tags": { "type": "array", "items": { "type": "string" } }, "parent_team_id": { "type": "string", "description": "Parent team ID for nested teams" }, "repositories": { "type": "array", "items": { "type": "string" }, "description": "Assigned repository names", "example": [ "my-org/backend-api" ] }, "is_active": { "type": "boolean", "description": "Whether the team is active" } } }, "CreateTeamRequest": { "allOf": [ { "$ref": "#/components/schemas/DevMetricsBaseRequest" }, { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "description": "Team name (min 2 characters)", "example": "Backend Team" }, "description": { "type": "string", "description": "Team description", "example": "Responsible for API services" }, "color": { "type": "string", "description": "Hex color code", "example": "#1570EF" }, "team_leads": { "type": "array", "items": { "type": "string" }, "example": [ "lead@example.com" ] }, "repositories": { "type": "array", "items": { "type": "string" }, "example": [ "my-org/backend-api" ] }, "members": { "type": "array", "description": "Initial team members to add at creation. You can create a team with members, repositories, or both.", "items": { "type": "object", "required": [ "user_login" ], "properties": { "user_login": { "type": "string", "description": "Unique login or email of the developer", "example": "jane@example.com" }, "user_name": { "type": "string", "description": "Display name (defaults to user_login if omitted)", "example": "Jane Doe" }, "role": { "type": "string", "enum": [ "member", "lead" ], "default": "member", "description": "Role within the team" } } }, "example": [ { "user_login": "jane@example.com", "user_name": "Jane Doe", "role": "lead" }, { "user_login": "john@example.com", "user_name": "John Smith", "role": "member" } ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorizing the team", "example": [ "backend", "api" ] }, "parent_team_id": { "type": "string", "format": "uuid", "description": "Parent team ID for creating nested/sub-teams", "example": "" }, "created_by": { "type": "string", "description": "Identifier of who created the team", "default": "system", "example": "admin@example.com" } } } ] }, "UpdateTeamRequest": { "allOf": [ { "$ref": "#/components/schemas/DevMetricsBaseRequest" }, { "type": "object", "required": [ "team_id" ], "properties": { "team_id": { "type": "string", "format": "uuid", "description": "ID of the team to update" }, "name": { "type": "string", "minLength": 2, "description": "New team name" }, "description": { "type": "string" }, "color": { "type": "string" }, "team_leads": { "type": "array", "items": { "type": "string" }, "description": "Array of team lead logins/emails. Replaces the entire list when provided.", "example": [ "lead1@example.com", "lead2@example.com" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "repositories": { "type": "array", "items": { "type": "string" } } } } ] }, "TeamIdRequest": { "allOf": [ { "$ref": "#/components/schemas/DevMetricsBaseRequest" }, { "type": "object", "required": [ "team_id" ], "properties": { "team_id": { "type": "string", "format": "uuid", "description": "ID of the team" } } } ] }, "DeleteTeamRequest": { "allOf": [ { "$ref": "#/components/schemas/DevMetricsBaseRequest" }, { "type": "object", "required": [ "team_id" ], "properties": { "team_id": { "type": "string", "format": "uuid", "description": "ID of the team to delete" }, "hard_delete": { "type": "boolean", "default": false, "description": "If true, permanently removes the team. If false (default), soft-deletes by marking inactive." } } } ] }, "TeamMemberRequest": { "allOf": [ { "$ref": "#/components/schemas/DevMetricsBaseRequest" }, { "type": "object", "required": [ "team_id", "user_login" ], "properties": { "team_id": { "type": "string", "format": "uuid" }, "user_login": { "type": "string", "description": "Login/email of the member", "example": "jane@example.com" }, "user_name": { "type": "string", "description": "Display name (for add/update)", "example": "Jane Doe" }, "role": { "type": "string", "enum": [ "member", "lead" ], "default": "member", "description": "Member role (for add/update)" } } } ] }, "DateRangeRequest": { "allOf": [ { "$ref": "#/components/schemas/DevMetricsBaseRequest" }, { "type": "object", "required": [ "start_date", "end_date" ], "properties": { "start_date": { "type": "string", "format": "date", "description": "Start of the date range (YYYY-MM-DD)", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "description": "End of the date range (YYYY-MM-DD)", "example": "2025-03-01" } } } ] }, "DevComparisonRequest": { "allOf": [ { "$ref": "#/components/schemas/DateRangeRequest" }, { "type": "object", "required": [ "author" ], "properties": { "author": { "type": "string", "description": "Git author login/email to analyze", "example": "janedoe" } } } ] }, "DevSummaryRequest": { "allOf": [ { "$ref": "#/components/schemas/DateRangeRequest" }, { "type": "object", "required": [ "author" ], "properties": { "author": { "type": "string", "description": "Git author login/email to analyze", "example": "janedoe" }, "repositories": { "type": "array", "items": { "type": "string" }, "description": "List of repository names to scope the summary. If omitted, all repositories under the organization are used.", "example": [ "my-org/backend-api" ] } } } ] }, "ActiveDeveloper": { "type": "object", "description": "An active developer with commit activity and code statistics", "properties": { "login": { "type": "string", "description": "Developer's git login/email" }, "name": { "type": "string", "description": "Developer's display name" }, "commit_count": { "type": "integer", "description": "Total commits in the date range" }, "repositories": { "type": "array", "items": { "type": "string" }, "description": "Repositories the developer contributed to" }, "repository_commits": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Commit count per repository" }, "coding_days": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Commits per day (date → count)" }, "total_additions": { "type": "integer" }, "total_deletions": { "type": "integer" }, "total_files_changed": { "type": "integer" }, "languages": { "type": "object", "description": "Breakdown by file extension", "additionalProperties": { "type": "object", "properties": { "additions": { "type": "integer" }, "deletions": { "type": "integer" }, "files": { "type": "integer" } } } }, "commit_times": { "type": "object", "description": "Commits by time of day", "properties": { "morning": { "type": "integer" }, "afternoon": { "type": "integer" }, "evening": { "type": "integer" }, "night": { "type": "integer" } } }, "repository_count": { "type": "integer" }, "avg_commit_size": { "type": "number" }, "net_code_impact": { "type": "integer", "description": "additions - deletions" }, "test_ratio": { "type": "number", "description": "Ratio of test code changes" } } }, "DeveloperPRData": { "type": "object", "description": "A developer's pull request activity and statistics", "properties": { "login": { "type": "string" }, "name": { "type": "string" }, "total_prs": { "type": "integer" }, "open_prs": { "type": "integer" }, "closed_prs": { "type": "integer" }, "merged_prs": { "type": "integer" }, "total_additions": { "type": "integer" }, "total_deletions": { "type": "integer" }, "total_files_changed": { "type": "integer" }, "repositories": { "type": "array", "items": { "type": "string" } }, "repository_prs": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "PR count per repository" }, "pr_creation_dates": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "PRs created per day" }, "prs_detail": { "type": "array", "description": "Detailed list of individual PRs", "items": { "type": "object", "properties": { "repository": { "type": "string" }, "pr_number": { "type": "integer" }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "closed", "merged" ] }, "additions": { "type": "integer" }, "deletions": { "type": "integer" }, "files_changed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "merged_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "AgentScanStartRequest": { "type": "object", "required": [ "service", "repo", "accessToken", "branch", "instructionPrompt" ], "properties": { "service": { "type": "string", "description": "Version control service provider", "enum": [ "github", "gitlab", "azuredevops", "bitbucket" ], "example": "github" }, "repo": { "type": "string", "description": "Repository identifier (format varies by service)", "example": "owner/repository" }, "accessToken": { "type": "string", "description": "OAuth or personal access token for the VCS service", "example": "ghp_xxxxxxxxxxxx" }, "branch": { "type": "string", "description": "Git branch to analyze", "example": "main" }, "instructionPrompt": { "type": "string", "description": "Analysis type. Use `threat_hunting` for security threat detection.", "example": "threat_hunting" }, "commitId": { "type": "string", "description": "Specific commit SHA to analyze. If omitted, the latest commit on the branch is used.", "default": "", "example": "abc123def456" }, "includeFiles": { "type": "string", "description": "Comma-separated glob patterns for files to include in analysis", "default": "", "example": "src/**/*.py,lib/**/*.js,app/**/*.ts" }, "excludeFiles": { "type": "string", "description": "Comma-separated glob patterns for files to exclude from analysis", "default": "", "example": "tests/**,node_modules/**,dist/**" }, "azureDevopsBaseUrl": { "type": "string", "description": "Base URL for Azure DevOps (for self-hosted instances)", "default": "https://dev.azure.com" }, "gitlab_base_url": { "type": "string", "description": "Base URL for GitLab (for self-hosted instances)", "default": "https://gitlab.com" }, "github_base_url": { "type": "string", "description": "Base URL for GitHub (for GitHub Enterprise Server)", "default": "https://github.com" }, "bitbucket_base_url": { "type": "string", "description": "Base URL for Bitbucket (for Bitbucket Data Center)", "default": "https://api.bitbucket.org/2.0" } } }, "AgentScanStartResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message", "example": "Scan started successfully" }, "scanId": { "type": "string", "description": "Unique identifier for the scan. Use this to retrieve results and check status.", "example": "aB3xK9mP2q" }, "filesQueued": { "type": "integer", "description": "Number of files queued for analysis", "example": 142 } } }, "AgentScanResultsRequest": { "type": "object", "required": [ "repo", "scanId" ], "properties": { "repo": { "type": "string", "description": "Repository identifier", "example": "owner/repository" }, "scanId": { "type": "string", "description": "Scan identifier returned from the start scan endpoint", "example": "aB3xK9mP2q" } } }, "AgentScanResultsResponse": { "type": "object", "properties": { "scanId": { "type": "string", "description": "Scan identifier", "example": "aB3xK9mP2q" }, "repoName": { "type": "string", "description": "Repository name", "example": "owner/repository" }, "status": { "type": "string", "description": "Current status of the scan", "enum": [ "completed", "in_progress" ], "example": "completed" }, "results": { "type": "array", "description": "List of file results with issues found", "items": { "type": "object", "properties": { "file": { "type": "string", "description": "File path where issues were found", "example": "src/auth/login.py" }, "scan_id": { "type": "string", "description": "Scan identifier" }, "issues": { "type": "array", "description": "List of issues found in the file", "items": { "$ref": "#/components/schemas/AgentIssue" } } } } }, "totalIssues": { "type": "integer", "description": "Total number of deduplicated issues found across all files", "example": 5 } } }, "AgentIssue": { "type": "object", "description": "An issue found by the AI agent during analysis", "properties": { "relevant_file": { "type": "string", "description": "File path where the issue was found", "example": "src/auth/login.py" }, "language": { "type": "string", "description": "Programming language of the file", "example": "python" }, "suggestion_content": { "type": "string", "description": "Detailed description of the issue in markdown format, including the problem, impact, and suggested fix", "example": "The `authenticate` function does not validate the length of the password parameter before passing it to the bcrypt hashing function." }, "start_line": { "type": "integer", "description": "Starting line number of the issue", "example": 45 }, "end_line": { "type": "integer", "description": "Ending line number of the issue", "example": 52 }, "one_sentence_summary": { "type": "string", "description": "Brief one-sentence summary of the issue", "example": "Password length not validated before bcrypt hashing" }, "label": { "type": "string", "description": "Category label for the issue (e.g., Security, Bug, Performance)", "example": "Security" }, "severity": { "type": "string", "description": "Severity level of the issue", "enum": [ "low", "medium", "high", "critical" ], "example": "medium" }, "cwe_id": { "type": "string", "description": "Common Weakness Enumeration (CWE) identifier, when applicable", "example": "CWE-916" }, "exploitability": { "type": "string", "description": "Assessment of how exploitable the issue is (included for security findings)", "example": "Requires attacker to know the truncation behavior of bcrypt" }, "agent_instructions": { "type": "string", "description": "The analysis instructions or prompt that the agent used when it found this issue (e.g., threat_hunting, bug_finding, or custom rules)", "example": "threat_hunting" } } }, "AgentScanHistoryRequest": { "type": "object", "required": [ "repo" ], "properties": { "repo": { "type": "string", "description": "Repository identifier", "example": "owner/repository" } } }, "AgentScanHistoryResponse": { "type": "object", "properties": { "scans": { "type": "array", "description": "List of past agent scans, sorted by most recent first", "items": { "type": "object", "properties": { "service": { "type": "string", "description": "VCS service used for the scan", "example": "github" }, "repo_name": { "type": "string", "description": "Repository name", "example": "owner/repository" }, "branch": { "type": "string", "description": "Branch that was scanned", "example": "main" }, "commit_id": { "type": "string", "description": "Commit SHA that was scanned", "example": "abc123def456" }, "scan_id": { "type": "string", "description": "Unique scan identifier", "example": "aB3xK9mP2q" }, "prompt": { "type": "string", "description": "Analysis prompt or type used for the scan", "example": "threat_hunting" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the scan was initiated", "example": "2025-03-15T10:30:00Z" }, "num_files": { "type": "integer", "description": "Number of files that were analyzed", "example": 142 } } } } } }, "AuditEvent": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Immutable unique event id (32-char hex)", "example": "a3f9c2e1b4d84f7a9c0e5d6b7a8f9012" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC", "example": "2026-07-30T09:14:03.512345Z" }, "action": { "type": "string", "description": "Stable machine action name (domain.verb)", "example": "rbac.role_update" }, "description": { "type": "string", "description": "Human-readable action description", "example": "Access control: role update" }, "actor_type": { "type": "string", "enum": [ "user", "system", "service_account", "integration" ], "description": "Never an unattributed 'unknown'" }, "actor_id": { "type": "string", "description": "User sub or stable system identity", "example": "harshit-dubey" }, "actor_email": { "type": "string", "nullable": true, "example": "admin@example.com" }, "org": { "type": "string", "example": "Example-Org" }, "service": { "type": "string", "enum": [ "github", "gitlab", "bitbucket", "azuredevops" ] }, "base_url_domain": { "type": "string", "description": "Git platform host (self-hosted aware)", "example": "github.com" }, "source": { "type": "string", "enum": [ "ui", "api", "scheduled_job", "system" ], "description": "Channel the action came from" }, "target_type": { "type": "string", "nullable": true, "example": "rbac" }, "target_id": { "type": "string", "nullable": true, "example": "role_7d2f" }, "target_name": { "type": "string", "nullable": true, "description": "Affected resource name/path/repository", "example": "Security Reviewer" }, "outcome": { "type": "string", "enum": [ "success", "denied", "failure" ] }, "status_code": { "type": "integer", "description": "HTTP status of the audited request", "example": 200 }, "method": { "type": "string", "example": "POST" }, "path": { "type": "string", "example": "/settings/rbac/roles/update" }, "ip": { "type": "string", "example": "203.0.113.42" }, "user_agent": { "type": "string", "description": "May contain commas or line breaks — always quoted in CSV output" }, "request_id": { "type": "string", "description": "Correlation id shared with server logs" }, "changes": { "type": "object", "nullable": true, "description": "Per-field before/after values for configuration, permission and security changes. Sensitive keys are ''.", "additionalProperties": { "type": "object", "properties": { "before": { "nullable": true }, "after": { "nullable": true } } } }, "details": { "type": "object", "nullable": true, "description": "Redacted, truncated request summary. Never raw payloads, tokens or secrets.", "additionalProperties": true } } }, "AuditEventsRequest": { "type": "object", "required": [ "platform", "org" ], "properties": { "platform": { "type": "string", "enum": [ "github", "gitlab", "bitbucket", "azure_devops" ], "description": "Git platform of the organization" }, "org": { "type": "string", "description": "Organization / workspace slug" }, "github_base_url": { "type": "string", "description": "Self-hosted instance URL (also gitlab_base_url / bitbucket_base_url / azure_devops_base_url). Defaults to the cloud host.", "example": "https://github.com" }, "start_date": { "type": "string", "format": "date", "description": "Inclusive UTC start date. Default: last 7 days; clamped to the 180-day retention window." }, "end_date": { "type": "string", "format": "date", "description": "Inclusive UTC end date. Default: today." }, "days": { "type": "integer", "description": "Alternative to explicit dates: lookback window in days (max 180)." }, "since": { "type": "string", "format": "date-time", "description": "Only events STRICTLY AFTER this ISO 8601 timestamp; also defaults the range to [since, today]. Use your last consumed event's timestamp for incremental pulls." }, "cursor": { "type": "string", "description": "Opaque cursor from a previous response — resume paging after it." }, "limit": { "type": "integer", "default": 100, "maximum": 1000, "description": "Events per page." }, "format": { "type": "string", "enum": [ "json", "ndjson", "csv" ], "default": "json", "description": "json returns the envelope below; ndjson/csv return the raw file body with paging in X-Next-Cursor / X-Has-More headers. CSV is RFC 4180 (fields with commas, quotes or line breaks are properly quoted)." } } }, "AuditEventsResponse": { "type": "object", "properties": { "org": { "type": "string" }, "service": { "type": "string" }, "base_url_domain": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "retention_days": { "type": "integer", "example": 180 }, "count": { "type": "integer", "description": "Events in this page" }, "has_more": { "type": "boolean", "description": "True when more pages match — call again with next_cursor" }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page; also a durable resume point" }, "events": { "type": "array", "description": "Events in ascending timestamp order (oldest first)", "items": { "$ref": "#/components/schemas/AuditEvent" } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "CodeAnt API token (`cdt_...`), created on the Settings → API Tokens page. Pass via `Authorization: Bearer ` header." } } }, "tags": [ { "name": "Analysis", "description": "Code analysis operations" }, { "name": "Agent Analysis", "description": "AI-powered agent analysis operations. Uses LLM-based code exploration agents to perform deep security threat hunting, bug finding, and custom analysis with reflection-based false positive filtering." }, { "name": "Developer Metrics - Teams", "description": "Manage developer teams: create, update, delete teams and manage team membership. Teams are used to organize developers and scope metrics." }, { "name": "Developer Metrics", "description": "Developer productivity and activity metrics: active developers, PR throughput, individual comparisons, and AI-generated summaries. All endpoints support GitHub, GitLab, Bitbucket, and Azure DevOps." }, { "name": "Audit Logs", "description": "Read-only access to your organization's audit trail for compliance, ETL and SIEM ingestion. Events are immutable, retained for 180 days, and cover security-relevant actions: user management, access control, credentials, scan triggers, configuration changes and data exports. Secrets and tokens are redacted and never appear in any response format." } ] }