{ "openapi": "3.1.0", "info": { "title": "Gecko Security API", "version": "1.0.0", "description": "Programmatic access to scans, vulnerabilities, repositories, schedules, integrations, and scanner image releases. Authenticate with an API key via the `X-API-Key` header or `Authorization: Bearer `." }, "servers": [ { "url": "https://app.gecko.security/api/v1" } ], "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "doc_url": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "doc_url", "request_id" ] } }, "required": [ "error" ] }, "ScanEndpoints": { "type": "object", "properties": { "object": { "const": "scan_endpoints" }, "scan_id": { "type": "string" }, "format": { "type": [ "string", "null" ], "enum": [ "json", "yaml", null ] }, "endpoints": { "type": [ "string", "null" ] }, "parsed": {} }, "required": [ "object", "scan_id", "format", "endpoints", "parsed" ] }, "Scan": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "scan" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "is_done": { "type": "boolean" }, "progress": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "programming_language": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "main", "pr", "fix" ] }, "branch": { "type": [ "string", "null" ] }, "commit_sha": { "type": [ "string", "null" ] }, "pull_request_number": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "repository": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "vulnerability_counts": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "high": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "medium": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "low": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "critical", "high", "medium", "low", "total" ], "additionalProperties": false }, "created_at": { "type": "string" }, "ended_at": { "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "status", "is_done", "progress", "programming_language", "kind", "branch", "commit_sha", "pull_request_number", "repository", "model", "vulnerability_counts", "created_at", "ended_at" ], "additionalProperties": false }, "Vulnerability": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "vulnerability" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scan_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "repository_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "fixed", "false_positive", "accepted_risk" ] }, "severity": { "type": "number" }, "severity_level": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "type": { "type": "string" }, "cwe": { "type": "string" }, "title": { "type": "string" }, "short_description": { "type": "string" }, "file_path": { "type": "string" }, "confidence_score": { "type": "number" }, "cvss_vector": { "type": "string" }, "created_at": { "type": "string" }, "scan": { "type": "object", "properties": { "object": { "type": "string", "const": "scan" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "is_done": { "type": "boolean" }, "progress": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "programming_language": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "main", "pr", "fix" ] }, "branch": { "type": [ "string", "null" ] }, "commit_sha": { "type": [ "string", "null" ] }, "pull_request_number": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "repository": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "vulnerability_counts": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "high": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "medium": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "low": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "critical", "high", "medium", "low", "total" ], "additionalProperties": false }, "created_at": { "type": "string" }, "ended_at": { "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "status", "is_done", "progress", "programming_language", "kind", "branch", "commit_sha", "pull_request_number", "repository", "model", "vulnerability_counts", "created_at", "ended_at" ], "additionalProperties": false }, "repository": { "type": "object", "properties": { "object": { "type": "string", "const": "repository" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "full_name": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "default_branch": { "type": "string" }, "web_url": { "type": [ "string", "null" ] }, "last_scan_at": { "type": [ "string", "null" ] }, "scan_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "open_vulnerability_counts": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "high": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "medium": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "low": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "critical", "high", "medium", "low" ], "additionalProperties": false }, "created_at": { "type": "string" } }, "required": [ "object", "id", "full_name", "name", "provider", "default_branch", "web_url", "last_scan_at", "scan_count", "open_vulnerability_counts", "created_at" ], "additionalProperties": false } }, "required": [ "object", "id", "scan_id", "repository_id", "status", "severity", "severity_level", "type", "cwe", "title", "short_description", "file_path", "confidence_score", "cvss_vector", "created_at" ], "additionalProperties": false }, "Repository": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "repository" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "full_name": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "default_branch": { "type": "string" }, "web_url": { "type": [ "string", "null" ] }, "last_scan_at": { "type": [ "string", "null" ] }, "scan_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "open_vulnerability_counts": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "high": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "medium": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "low": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "critical", "high", "medium", "low" ], "additionalProperties": false }, "created_at": { "type": "string" } }, "required": [ "object", "id", "full_name", "name", "provider", "default_branch", "web_url", "last_scan_at", "scan_count", "open_vulnerability_counts", "created_at" ], "additionalProperties": false }, "Schedule": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "schedule" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "repository_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "branch": { "type": [ "string", "null" ] }, "cron_expression": { "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "scan_mode": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "next_run_at": { "type": [ "string", "null" ] }, "last_run_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "object", "id", "name", "repository_ids", "branch", "cron_expression", "timezone", "scan_mode", "model", "is_active", "next_run_at", "last_run_at", "created_at" ], "additionalProperties": false }, "CreateScanRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "repository": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "branch": { "type": "string", "minLength": 1 }, "commit": { "description": "Scan exactly this commit instead of the branch tip. Full or abbreviated SHA; it must exist in the repository.", "type": "string", "pattern": "^[0-9a-f]{7,40}$" }, "base_commit": { "description": "Analyze only the files changed from this commit to `commit` (a diff scan). Requires `commit`; findings land as repository findings.", "type": "string", "pattern": "^[0-9a-f]{7,40}$" }, "model": { "type": "string", "enum": [ "haiku", "sonnet", "opus" ] } }, "required": [ "name", "repository" ], "additionalProperties": false }, "TriageVulnerabilityRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "enum": [ "dismiss", "accept_risk", "reopen", "confirm", "resolve" ] }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "action" ], "additionalProperties": false }, "UpdateRepositoryRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fail_on_severity": { "anyOf": [ { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, { "type": "null" } ] } }, "additionalProperties": false }, "CreateScheduleRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "repository_ids": {}, "cron_expression": { "type": "string", "minLength": 1 }, "branch": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "scan_mode": { "type": "string", "enum": [ "full", "diff" ] }, "model": { "type": "string", "enum": [ "haiku", "sonnet", "opus" ] } }, "required": [ "name", "repository_ids", "cron_expression" ], "additionalProperties": false }, "UpdateScheduleRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "repository_ids": {}, "cron_expression": { "type": "string", "minLength": 1 }, "branch": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "scan_mode": { "type": "string", "enum": [ "full", "diff" ] }, "model": { "anyOf": [ { "type": "string", "enum": [ "haiku", "sonnet", "opus" ] }, { "type": "null" } ] }, "is_active": { "type": "boolean" } }, "additionalProperties": false }, "GitHubIntegration": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "github_integration" }, "enabled": { "type": "boolean" }, "installations": { "type": "array", "items": { "type": "object", "properties": { "installation_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "account": { "type": "string" }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ok", "outdated", "broken" ], "description": "`outdated`: an organization owner has not accepted permissions the App now requests. `broken`: GitHub is rejecting the installation (suspended or uninstalled)." }, "status_reason": { "description": "Why the status is not `ok`, e.g. \"missing permissions: checks: write\".", "type": [ "string", "null" ] }, "settings_url": { "type": [ "string", "null" ] }, "connected_at": { "type": "string" } }, "required": [ "installation_id", "account", "enabled", "status", "status_reason", "settings_url", "connected_at" ], "additionalProperties": false } }, "tracked_repositories_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "object", "enabled", "installations", "tracked_repositories_count" ], "additionalProperties": false }, "GitLabIntegration": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "gitlab_integration" }, "enabled": { "type": "boolean" }, "instance_url": { "type": [ "string", "null" ] }, "auth_mode": { "anyOf": [ { "type": "string", "enum": [ "service_account_token", "oauth" ] }, { "type": "null" } ] }, "token_expires_at": { "type": [ "string", "null" ] }, "last_validated_at": { "type": [ "string", "null" ] }, "tracked_repositories_count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "object", "enabled", "instance_url", "auth_mode", "token_expires_at", "last_validated_at", "tracked_repositories_count" ], "additionalProperties": false }, "UpdateGitLabIntegrationRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1 }, "instance_url": { "type": "string", "minLength": 1 } }, "required": [ "access_token" ], "additionalProperties": false }, "ImageRelease": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "object": { "type": "string", "const": "image_release" }, "channel": { "type": "string", "description": "Release channel name. Channel names are shared privately by your Gecko account contact and are not listed publicly." }, "version": { "type": "string" }, "git_sha": { "type": "string" }, "image_digest": { "type": "string" }, "image_uri": { "type": "string" }, "image_ref": { "type": "string" }, "pull_command": { "type": "string" }, "pushed_at": { "type": "string" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "object", "channel", "version", "git_sha", "image_digest", "image_uri", "image_ref", "pull_command", "pushed_at", "notes" ], "additionalProperties": false } } }, "paths": { "/scans": { "get": { "summary": "List scans", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pull_request", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter to the PR/MR with this number; combine with `repository` to disambiguate across repos." }, { "name": "repository", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of scans", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Scan" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Trigger a scan (GitHub or GitLab)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Safely retry a POST/PATCH; a replayed key returns the original response.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScanRequest" } } } }, "responses": { "201": { "description": "Scan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scan" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scans/{id}": { "get": { "summary": "Get a scan", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scan" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scans/{id}/vulnerabilities": { "get": { "summary": "List a scan's vulnerabilities", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "severity", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "cwe", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated CWE ids; `CWE-79`, `cwe-79` and `79` are equivalent." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of vulnerabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vulnerability" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scans/{id}/endpoints": { "get": { "summary": "Get the API spec discovered by a scan", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanEndpoints" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scans/{id}/wiki": { "get": { "summary": "Get a scan's wiki (markdown)", "description": "The wiki of exactly this scan id (a retry's wiki is a separate scan). Bodies over 1,000,000 characters are cut and `X-Wiki-Truncated` is `true`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Markdown wiki", "headers": { "X-Wiki-Truncated": { "description": "`true` when the wiki exceeded the size cap and was cut.", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "text/markdown": {} } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities": { "get": { "summary": "List vulnerabilities", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "severity", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "cwe", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated CWE ids; `CWE-79`, `cwe-79` and `79` are equivalent." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "expand", "in": "query", "schema": { "type": "string" } }, { "name": "repository", "in": "query", "schema": { "type": "string" } }, { "name": "scan_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "pull_request", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter to the PR/MR with this number; combine with `repository` to disambiguate across repos." } ], "responses": { "200": { "description": "A list of vulnerabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vulnerability" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities/sarif": { "get": { "summary": "Export vulnerabilities as SARIF", "description": "The vulnerabilities matching the list filters as a SARIF 2.1.0 log, one run per repository, ready for GitHub code scanning. Fixed findings are left out, so uploading the log closes their alerts. Rather than truncate, the request fails with `export_too_large` when the filters match more than 10,000 vulnerabilities.", "parameters": [ { "name": "severity", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "cwe", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated CWE ids; `CWE-79`, `cwe-79` and `79` are equivalent." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "repository", "in": "query", "schema": { "type": "string" } }, { "name": "scan_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "pull_request", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter to the PR/MR with this number; combine with `repository` to disambiguate across repos." } ], "responses": { "200": { "description": "A SARIF 2.1.0 log", "content": { "application/sarif+json": {} } }, "400": { "description": "Invalid filters, or too many matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities/{id}": { "get": { "summary": "Get a vulnerability", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vulnerability" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Triage a vulnerability", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Safely retry a POST/PATCH; a replayed key returns the original response.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriageVulnerabilityRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vulnerability" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories": { "get": { "summary": "List repositories", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "A list of repositories", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Repository" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/{repository_id}": { "get": { "summary": "Get a repository by id", "parameters": [ { "name": "repository_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Repository id (from any repository resource); the collision-free canonical address." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Repository" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update repository settings by id", "parameters": [ { "name": "repository_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Repository id (from any repository resource); the collision-free canonical address." }, { "name": "Idempotency-Key", "in": "header", "description": "Safely retry a POST/PATCH; a replayed key returns the original response.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRepositoryRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Repository" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/{repository_id}/vulnerabilities": { "get": { "summary": "List a repository's vulnerabilities by repository id", "parameters": [ { "name": "repository_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Repository id (from any repository resource); the collision-free canonical address." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "severity", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "cwe", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated CWE ids; `CWE-79`, `cwe-79` and `79` are equivalent." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "expand", "in": "query", "schema": { "type": "string" } }, { "name": "pull_request", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter to the PR/MR with this number; combine with `repository` to disambiguate across repos." } ], "responses": { "200": { "description": "A list of vulnerabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vulnerability" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/{repository_id}/scans": { "get": { "summary": "List a repository's scans by repository id", "parameters": [ { "name": "repository_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Repository id (from any repository resource); the collision-free canonical address." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pull_request", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter to the PR/MR with this number; combine with `repository` to disambiguate across repos." } ], "responses": { "200": { "description": "A list of scans", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Scan" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/{owner}/{repo}": { "get": { "summary": "Get a repository", "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Repository name; may contain `/` segments for GitLab subgroup paths. A name whose final segment is literally `scans` or `vulnerabilities` collides with the sub-resource routes. Address that repository by id instead." }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "github", "gitlab", "zip" ] }, "description": "Disambiguates when the same full name is tracked on multiple providers." }, { "name": "resource", "in": "query", "schema": { "type": "string", "enum": [ "repository" ] }, "description": "Pass `repository` to pin the whole path as the repository name when it ends in `scans` or `vulnerabilities`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Repository" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update repository settings", "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Repository name; may contain `/` segments for GitLab subgroup paths. A name whose final segment is literally `scans` or `vulnerabilities` collides with the sub-resource routes. Address that repository by id instead." }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "github", "gitlab", "zip" ] }, "description": "Disambiguates when the same full name is tracked on multiple providers." }, { "name": "resource", "in": "query", "schema": { "type": "string", "enum": [ "repository" ] }, "description": "Pass `repository` to pin the whole path as the repository name when it ends in `scans` or `vulnerabilities`." }, { "name": "Idempotency-Key", "in": "header", "description": "Safely retry a POST/PATCH; a replayed key returns the original response.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRepositoryRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Repository" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/{owner}/{repo}/vulnerabilities": { "get": { "summary": "List a repository's vulnerabilities", "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Repository name; may contain `/` segments for GitLab subgroup paths. A name whose final segment is literally `scans` or `vulnerabilities` collides with the sub-resource routes. Address that repository by id instead." }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "github", "gitlab", "zip" ] }, "description": "Disambiguates when the same full name is tracked on multiple providers." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "severity", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "cwe", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated CWE ids; `CWE-79`, `cwe-79` and `79` are equivalent." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "expand", "in": "query", "schema": { "type": "string" } }, { "name": "pull_request", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter to the PR/MR with this number; combine with `repository` to disambiguate across repos." } ], "responses": { "200": { "description": "A list of vulnerabilities", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vulnerability" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/repositories/{owner}/{repo}/scans": { "get": { "summary": "List a repository's scans", "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Repository name; may contain `/` segments for GitLab subgroup paths. A name whose final segment is literally `scans` or `vulnerabilities` collides with the sub-resource routes. Address that repository by id instead." }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "github", "gitlab", "zip" ] }, "description": "Disambiguates when the same full name is tracked on multiple providers." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pull_request", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter to the PR/MR with this number; combine with `repository` to disambiguate across repos." } ], "responses": { "200": { "description": "A list of scans", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Scan" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schedules": { "get": { "summary": "List schedules", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "A list of schedules", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a schedule", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Safely retry a POST/PATCH; a replayed key returns the original response.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schedules/{id}": { "get": { "summary": "Get a schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Safely retry a POST/PATCH; a replayed key returns the original response.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/github": { "get": { "summary": "Get the GitHub integration", "description": "Current GitHub App installations for the team, one per organization, with the same connection health the dashboard shows. Never returns credentials.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubIntegration" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/gitlab": { "get": { "summary": "Get the GitLab integration", "description": "Current GitLab connection state for the team, including the stored token expiry date. Never returns credentials.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabIntegration" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rotate the GitLab service-account token", "description": "Validates the token against the GitLab instance (including the required \"api\" scope) before storing it. Omit `instance_url` to keep the currently connected instance.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Safely retry a POST/PATCH; a replayed key returns the original response.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGitLabIntegrationRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabIntegration" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/releases/{channel}": { "get": { "summary": "List image releases for a channel", "description": "Newest-first history of published scanner images. Pin pulls to the returned digest-pinned `image_ref`, never a mutable tag. Unknown channel names return `not_found`.", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string", "description": "Release channel name. Channel names are shared privately by your Gecko account contact and are not listed publicly." } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "A list of image releases", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageRelease" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor" ] } }, "required": [ "object", "data", "pagination" ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/releases/{channel}/latest": { "get": { "summary": "Get the latest image release for a channel", "description": "Unknown channel names return `not_found`.", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string", "description": "Release channel name. Channel names are shared privately by your Gecko account contact and are not listed publicly." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRelease" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/releases/{channel}/{version}": { "get": { "summary": "Resolve a version to its image release", "description": "Looks up one release by version within a channel. The path version matches either the customer release version (for example `1.1`) or the Gecko scanner version (for example `1.1.0`). When the same scanner version was pushed more than once, the newest release is returned. Pull the digest-pinned `image_ref`, never a mutable tag.", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string", "description": "Release channel name. Channel names are shared privately by your Gecko account contact and are not listed publicly." } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "description": "Either the customer release version (for example `1.1`) or the Gecko scanner version (for example `1.1.0`)." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRelease" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }