{ "openapi": "3.1.1", "info": { "title": "Canine Code Analyzer API", "description": "Scans, runs, results, history, the finding lifecycle, account and usage. Every request carries an organisation's API key as a bearer token (Authorization: Bearer cca_...), holding the scope the endpoint names; a key reaches only its organisation's repositories.", "version": "v1" }, "servers": [ { "url": "https://api.canine.dev/" } ], "paths": { "/v1/account": { "get": { "tags": [ "account" ], "operationId": "V1Account", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountView" } } } } } } }, "/v1/account/usage": { "get": { "tags": [ "account" ], "operationId": "V1Usage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageView" } } } } } } }, "/v1/repositories": { "get": { "tags": [ "account" ], "operationId": "V1Repositories", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RepositoryView" } } } } } } }, "post": { "tags": [ "account" ], "operationId": "V1AddRepository", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddRepositoryBody" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryView" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/repositories/{repositoryId}/scans": { "post": { "tags": [ "scans" ], "operationId": "V1StartScan", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanStarted" } } } } } } }, "/v1/scans/{scanId}": { "get": { "tags": [ "runs" ], "operationId": "V1Scan", "parameters": [ { "name": "scanId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanView" } } } } } } }, "/v1/repositories/{repositoryId}/runs": { "get": { "tags": [ "runs" ], "operationId": "V1Runs", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "take", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunView" } } } } } } } }, "/v1/runs/{runId}": { "get": { "tags": [ "runs" ], "operationId": "V1Run", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunView" } } } } } } }, "/v1/repositories/{repositoryId}/trend": { "get": { "tags": [ "runs" ], "operationId": "V1Trend", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrendPoint" } } } } } } } }, "/v1/repositories/{repositoryId}/scores": { "get": { "tags": [ "results" ], "operationId": "V1Scores", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVerdict" } } } } } } }, "/v1/repositories/{repositoryId}/findings": { "get": { "tags": [ "results" ], "operationId": "V1Findings", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "dimension", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "offset", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFindingsResult" } } } } } } }, "/v1/repositories/{repositoryId}/findings/{fingerprint}": { "get": { "tags": [ "results" ], "operationId": "V1Finding", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fingerprint", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFinding" } } } } } } }, "/v1/runs/{runId}/bundle": { "get": { "tags": [ "results" ], "operationId": "V1Bundle", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/runs/{runId}/sarif": { "get": { "tags": [ "results" ], "operationId": "V1Sarif", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/repositories/{repositoryId}/findings/{fingerprint}/claim": { "post": { "tags": [ "findings" ], "operationId": "V1Claim", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fingerprint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workerId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimOutcome" } } } } } } }, "/v1/repositories/{repositoryId}/findings/{fingerprint}/release": { "post": { "tags": [ "findings" ], "operationId": "V1Release", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fingerprint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workerId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimOutcome" } } } } } } }, "/v1/repositories/{repositoryId}/findings/{fingerprint}/resolve": { "post": { "tags": [ "findings" ], "operationId": "V1Resolve", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fingerprint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workerId", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResolveBody" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimOutcome" } } } } } } }, "/v1/repositories/{repositoryId}/findings/{fingerprint}/dispute": { "post": { "tags": [ "findings" ], "operationId": "V1Dispute", "parameters": [ { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fingerprint", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DisputeBody" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDisputeOutcome" } } } } } } } }, "components": { "schemas": { "AccountView": { "required": [ "organizationId", "name", "plan", "status", "comped", "key" ], "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "name": { "type": [ "null", "string" ] }, "plan": { "type": "string" }, "status": { "type": "string" }, "comped": { "type": "boolean" }, "key": { "$ref": "#/components/schemas/KeyView" } } }, "AddRepositoryBody": { "required": [ "provider", "fullName" ], "type": "object", "properties": { "provider": { "type": [ "null", "string" ] }, "fullName": { "type": [ "null", "string" ] } } }, "AgentClaimOutcome": { "required": [ "ok", "error", "fingerprint", "state", "expiresAt", "note" ], "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": [ "null", "string" ] }, "fingerprint": { "type": "string" }, "state": { "type": [ "null", "string" ] }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time" }, "note": { "type": [ "null", "string" ] } } }, "AgentDependency": { "required": [ "package", "version", "advisory", "aliases", "reachability" ], "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": [ "null", "string" ] }, "advisory": { "type": [ "null", "string" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "reachability": { "type": "string" }, "reachabilityFile": { "type": [ "null", "string" ] }, "reachabilityLine": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "reachabilitySymbol": { "type": [ "null", "string" ] } } }, "AgentDisputeOutcome": { "required": [ "ok", "error", "fingerprint", "state", "created" ], "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": [ "null", "string" ] }, "fingerprint": { "type": "string" }, "state": { "type": "string" }, "created": { "type": "boolean" }, "groupId": { "type": [ "null", "string" ], "format": "uuid" }, "siblings": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AgentDisputeSiblingOutcome" } } } }, "AgentDisputeSiblingOutcome": { "required": [ "fingerprint", "ok", "state", "created", "error" ], "type": "object", "properties": { "fingerprint": { "type": "string" }, "ok": { "type": "boolean" }, "state": { "type": "string" }, "created": { "type": "boolean" }, "error": { "type": [ "null", "string" ] } } }, "AgentFinding": { "required": [ "fingerprint", "dimension", "level", "title", "file", "line", "commitSha", "state" ], "type": "object", "properties": { "fingerprint": { "type": "string" }, "dimension": { "type": "string" }, "level": { "type": "string" }, "title": { "type": "string" }, "file": { "type": [ "null", "string" ] }, "line": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "commitSha": { "type": [ "null", "string" ] }, "state": { "type": "string" }, "advisory": { "type": "boolean", "default": false }, "detail": { "type": [ "null", "string" ] }, "detector": { "type": [ "null", "string" ] }, "maintainerNote": { "type": [ "null", "string" ] }, "cwe": { "type": [ "null", "array" ], "items": { "type": "string" } }, "owaspCategory": { "type": [ "null", "string" ] }, "refusedResolution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentRefusedResolution" } ] }, "hiddenBy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HiddenBy" } ] }, "suggestedBy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SuggestedBy" } ] }, "ownerNote": { "type": [ "null", "string" ] }, "dependency": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AgentDependency" } ] }, "acceptedNote": { "type": [ "null", "string" ] } } }, "AgentFindingsResult": { "required": [ "runId", "findings" ], "type": "object", "properties": { "runId": { "type": [ "null", "string" ], "format": "uuid" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/AgentFinding" } }, "totalMatching": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "truncated": { "type": "boolean" } } }, "AgentRefusedResolution": { "required": [ "note", "agentName", "resolvedAt" ], "type": "object", "properties": { "note": { "type": [ "null", "string" ] }, "agentName": { "type": [ "null", "string" ] }, "resolvedAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "AgentVerdict": { "required": [ "repository", "commit", "measuredAt", "rubricVersion", "rubricContentHash", "cai", "band", "lenses", "dimensions" ], "type": "object", "properties": { "repository": { "type": "string" }, "commit": { "type": [ "null", "string" ] }, "measuredAt": { "type": [ "null", "string" ], "format": "date-time" }, "rubricVersion": { "type": [ "null", "string" ] }, "rubricContentHash": { "type": [ "null", "string" ] }, "cai": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "band": { "type": [ "null", "string" ] }, "lenses": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVerdictLens" } }, "dimensions": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AgentVerdictDimension" } } } }, "AgentVerdictDimension": { "required": [ "id", "name", "score", "scorePct", "band", "lens" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "scorePct": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "band": { "type": "string" }, "lens": { "type": "string" } } }, "AgentVerdictLens": { "required": [ "key", "label", "score", "band" ], "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "score": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "band": { "type": "string" } } }, "CreditEntryView": { "required": [ "sequence", "kind", "locScans", "at", "repositoryId", "runId", "funding", "expiresAt" ], "type": "object", "properties": { "sequence": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "kind": { "type": "string" }, "locScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "at": { "type": "string", "format": "date-time" }, "repositoryId": { "type": [ "null", "string" ], "format": "uuid" }, "runId": { "type": [ "null", "string" ], "format": "uuid" }, "funding": { "type": [ "null", "string" ] }, "expiresAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "CreditLotView": { "required": [ "id", "kind", "locScans", "remainingLocScans", "creditedAt", "expiresAt", "expired" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "locScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "remainingLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "creditedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "expired": { "type": "boolean" } } }, "CreditView": { "required": [ "balanceLocScans", "heldLocScans", "availableLocScans", "lots", "entries" ], "type": "object", "properties": { "balanceLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "heldLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "availableLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "lots": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLotView" } }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CreditEntryView" } } } }, "DisputeBody": { "required": [ "reason" ], "type": "object", "properties": { "reason": { "type": [ "null", "string" ] }, "siblingFingerprints": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "HiddenBy": { "required": [ "ruleId", "scope", "grain" ], "type": "object", "properties": { "ruleId": { "type": "string", "format": "uuid" }, "scope": { "type": "string" }, "grain": { "type": "string" } } }, "KeyView": { "required": [ "id", "name", "prefix", "scopes", "rateLimitPerMinute" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rateLimitPerMinute": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "RepositoryView": { "required": [ "id", "fullName", "displayName", "provider", "defaultBranch", "forgeHost" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fullName": { "type": "string" }, "displayName": { "type": "string" }, "provider": { "type": "string" }, "defaultBranch": { "type": "string" }, "forgeHost": { "type": [ "null", "string" ] } } }, "ResolveBody": { "required": [ "note" ], "type": "object", "properties": { "note": { "type": [ "null", "string" ] } } }, "RunView": { "required": [ "runId", "repositoryId", "status", "trigger", "commit", "rubricVersion", "scannerVersion", "measuredLoc", "requestedAt", "startedAt", "finishedAt", "reason", "hasResults" ], "type": "object", "properties": { "runId": { "type": "string", "format": "uuid" }, "repositoryId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "trigger": { "type": "string" }, "commit": { "type": [ "null", "string" ] }, "rubricVersion": { "type": [ "null", "string" ] }, "scannerVersion": { "type": [ "null", "string" ] }, "measuredLoc": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" }, "requestedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "null", "string" ], "format": "date-time" }, "finishedAt": { "type": [ "null", "string" ], "format": "date-time" }, "reason": { "type": [ "null", "string" ] }, "hasResults": { "type": "boolean" } } }, "ScanStarted": { "required": [ "scanId", "alreadyQueued", "status" ], "type": "object", "properties": { "scanId": { "type": "string", "format": "uuid" }, "alreadyQueued": { "type": "boolean" }, "status": { "type": "string" } } }, "ScanView": { "required": [ "scanId", "repositoryId", "status", "enqueuedAt", "runId", "reason" ], "type": "object", "properties": { "scanId": { "type": "string", "format": "uuid" }, "repositoryId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "enqueuedAt": { "type": "string", "format": "date-time" }, "runId": { "type": [ "null", "string" ], "format": "uuid" }, "reason": { "type": [ "null", "string" ] } } }, "SuggestedBy": { "required": [ "agentName", "reason", "suggestedAt" ], "type": "object", "properties": { "agentName": { "type": "string" }, "reason": { "type": "string" }, "suggestedAt": { "type": "string", "format": "date-time" } } }, "TrendPoint": { "required": [ "runId", "at", "trigger", "headline", "band", "codeHealth", "architecture", "maturity", "productionReadiness", "securityCompliance", "productionLoc", "rubricVersion" ], "type": "object", "properties": { "runId": { "type": "string", "format": "uuid" }, "at": { "type": "string", "format": "date-time" }, "trigger": { "type": "string" }, "headline": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "band": { "type": "string" }, "codeHealth": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "architecture": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "maturity": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "productionReadiness": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "securityCompliance": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "productionLoc": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "rubricVersion": { "type": [ "null", "string" ] } } }, "UsageLineView": { "required": [ "repositoryId", "repository", "trigger", "locScanned", "billedLocScans", "occurredAt" ], "type": "object", "properties": { "repositoryId": { "type": "string", "format": "uuid" }, "repository": { "type": "string" }, "trigger": { "type": "string" }, "locScanned": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "billedLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "occurredAt": { "type": "string", "format": "date-time" } } }, "UsageView": { "required": [ "budgetLocScans", "consumedLocScans", "configuredDemandLocScans", "lines" ], "type": "object", "properties": { "budgetLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "consumedLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "configuredDemandLocScans": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLineView" } }, "credit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreditView" } ] } } } } }, "tags": [ { "name": "account" }, { "name": "scans" }, { "name": "runs" }, { "name": "results" }, { "name": "findings" } ] }