{ "openapi": "3.1.0", "x-generated": "This document is generated. Manual edits will be overwritten.", "info": { "title": "Qlty API", "version": "1.0.0", "description": "The Qlty API is organized around REST. It provides predictable, resource-oriented URLs, accepts JSON-encoded request bodies, and returns JSON-encoded responses." }, "servers": [ { "url": "https://api.qlty.sh" } ], "security": [ { "Bearer": [] } ], "tags": [ { "name": "Service", "description": "Service status and API discovery operations" }, { "name": "User", "description": "Operations for the authenticated user" }, { "name": "Workspaces", "description": "Operations for managing workspaces" }, { "name": "Projects", "description": "Operations for managing projects" }, { "name": "Issues", "description": "Operations for managing issues" }, { "name": "Metrics", "description": "Operations for retrieving metrics" }, { "name": "Components", "description": "Operations for retrieving components" }, { "name": "Coverage", "description": "Operations for retrieving code coverage data" } ], "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "description": "Generate an API token at https://qlty.sh/user/settings/tokens" } }, "schemas": { "ComponentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } } }, "required": [ "data" ] }, "Component": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Backend API" }, "description": { "type": "string", "nullable": true, "example": "Core backend API services" }, "pathGlobs": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[^,\\r\\n]+$" }, "example": [ "src/api/*" ] }, "fileCount": { "type": "integer", "example": 42 } }, "required": [ "id", "name", "description", "pathGlobs", "fileCount" ] }, "Error": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "example": "400" }, "title": { "type": "string", "example": "Bad Request" }, "detail": { "type": "string", "example": "The request was invalid." } }, "required": [ "status", "title", "detail" ] } } }, "required": [ "errors" ] }, "ComponentDefinition": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Backend API" }, "description": { "type": "string", "nullable": true, "example": "Core backend API services" }, "pathGlobs": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[^,\\r\\n]+$" }, "example": [ "src/api/*" ] } }, "required": [ "id", "name", "description", "pathGlobs" ], "description": "A Component as defined for a Project, without computed fields such as fileCount" }, "ComponentInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Backend API" }, "description": { "type": "string", "nullable": true, "example": "Core backend API services" }, "pathGlobs": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "^[^,\\r\\n]+$" }, "minItems": 1, "example": [ "src/api/*" ], "description": "Glob patterns matching the Component's file paths, one glob per array element. `*` matches any characters, including `/`." } }, "required": [ "name", "pathGlobs" ] }, "ComponentMetricList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } }, "required": [ "data" ] }, "Metric": { "allOf": [ { "$ref": "#/components/schemas/MetricDescriptor" }, { "type": "object", "properties": { "value": { "oneOf": [ { "type": "number" }, { "type": "string", "enum": [ "XS", "S", "M", "L", "XL" ] }, { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] } ], "example": 42, "description": "The latest value of the metric" } }, "required": [ "value" ] } ] }, "MetricDescriptor": { "type": "object", "properties": { "key": { "type": "string", "example": "CMPLX" }, "name": { "type": "string", "example": "Cognitive Complexity" }, "description": { "type": "string", "example": "Measures how hard the code is to understand" }, "category": { "type": "string", "enum": [ "maintainability", "reliability", "security", "size", "coverage", "quality" ], "example": "maintainability" }, "inverted": { "type": "boolean", "example": true, "description": "When true, higher values are worse" }, "valueType": { "type": "string", "enum": [ "number", "percentage", "grade", "size", "duration", "count" ], "example": "number", "description": "How the metric's value should be interpreted" } }, "required": [ "key", "name", "category", "inverted", "valueType" ] }, "MetricSeriesList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" } }, "meta": { "$ref": "#/components/schemas/MetricSeriesMeta" } }, "required": [ "data", "meta" ] }, "MetricSeries": { "type": "object", "properties": { "metric": { "$ref": "#/components/schemas/MetricDescriptor" }, "dimensions": { "type": "object", "properties": {}, "description": "Reserved for future grouping dimensions; always empty" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/MetricPoint" } } }, "required": [ "metric", "dimensions", "points" ] }, "MetricPoint": { "type": "object", "properties": { "timestamp": { "type": "string", "example": "2026-01-11T23:59:59Z", "description": "Inclusive end of the interval bucket (RFC 3339, UTC). The final point labels the bucket containing `meta.to`, so its timestamp may be later than `meta.to` — including in the future for an interval still in progress." }, "value": { "oneOf": [ { "type": "number" }, { "type": "string", "enum": [ "XS", "S", "M", "L", "XL" ] }, { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] } ], "example": 42, "description": "The metric's value for the interval" } }, "required": [ "timestamp", "value" ] }, "MetricSeriesMeta": { "type": "object", "properties": { "from": { "type": "string", "example": "2025-12-01T00:00:00Z" }, "to": { "type": "string", "example": "2026-06-01T00:00:00Z" }, "interval": { "type": "string", "enum": [ "day", "week", "month" ], "example": "week" } }, "required": [ "from", "to", "interval" ] }, "GetFileCoverageResponse": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "example": [ "unit", "integration" ], "description": "Available coverage tags" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileCoverage" } } }, "required": [ "tags", "files" ] }, "FileCoverage": { "type": "object", "properties": { "path": { "type": "string", "example": "src/index.ts" }, "hits": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 0, 1, 1, 0 ], "description": "Line-by-line hit counts" }, "tag": { "type": "string", "example": "unit", "description": "Coverage tag (e.g., unit, integration)" }, "coveredLines": { "type": "integer", "example": 42 }, "missedLines": { "type": "integer", "example": 8 }, "omitLines": { "type": "integer", "example": 10 }, "totalLines": { "type": "integer", "example": 60 } }, "required": [ "path", "hits", "coveredLines", "missedLines", "omitLines", "totalLines" ] }, "IssueList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MiniIssue" } }, "meta": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true, "description": "Whether there are more items available beyond this page" } }, "required": [ "hasMore" ] } }, "required": [ "data", "meta" ] }, "MiniIssue": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "fingerprint": { "type": "string", "example": "abc123def456" }, "tool": { "type": "string", "example": "eslint" }, "ruleKey": { "type": "string", "example": "no-unused-vars" }, "message": { "type": "string", "example": "'foo' is defined but never used." }, "category": { "type": "string", "enum": [ "bug", "vulnerability", "structure", "duplication", "security_hotspot", "performance", "documentation", "type_check", "style", "anti_pattern", "accessibility", "dead_code", "lint", "secret", "dependency_alert" ], "example": "lint" }, "level": { "type": "string", "enum": [ "high", "medium", "low", "note", "fmt" ], "example": "medium" }, "status": { "type": "string", "enum": [ "open", "ignored" ], "example": "open" }, "documentationUrl": { "type": "string", "format": "uri", "example": "https://eslint.org/docs/rules/no-unused-vars" }, "location": { "type": "object", "properties": { "path": { "type": "string", "example": "src/index.ts" }, "startLine": { "type": "integer", "example": 42 }, "endLine": { "type": "integer", "example": 42 } }, "required": [ "path" ] } }, "required": [ "id", "fingerprint", "tool", "ruleKey", "message", "category", "level", "status", "location" ] }, "MetricList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } }, "required": [ "data" ] }, "FileMetricList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } }, "required": [ "data" ] }, "ProjectList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "meta": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true, "description": "Whether there are more items available beyond this page" } }, "required": [ "hasMore" ] } }, "required": [ "data", "meta" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "workspaceId": { "type": "string", "example": "ws_abc123" }, "providerUrl": { "type": "string", "example": "https://github.com/acme-corp/my-repo", "description": "URL to the repository on the provider" }, "key": { "type": "string", "example": "my-repo", "description": "Repository name" }, "workspaceKey": { "type": "string", "example": "acme-corp", "description": "Key of the workspace this project belongs to" } }, "required": [ "id", "workspaceId", "providerUrl", "key", "workspaceKey" ] }, "RateLimitResponse": { "type": "object", "properties": { "resources": { "type": "object", "properties": { "core": { "$ref": "#/components/schemas/RateLimitResource" } }, "required": [ "core" ], "description": "Rate limit information by resource type" } }, "required": [ "resources" ] }, "RateLimitResource": { "type": "object", "properties": { "limit": { "type": "integer", "example": 5000, "description": "Maximum number of requests allowed in the current window" }, "used": { "type": "integer", "example": 10, "description": "Number of requests used in the current window" }, "remaining": { "type": "integer", "example": 4990, "description": "Number of requests remaining in the current window" }, "reset": { "type": "integer", "example": 1734567890, "description": "Unix timestamp when the rate limit window resets" } }, "required": [ "limit", "used", "remaining", "reset" ] }, "AuthenticatedUser": { "type": "object", "properties": { "id": { "type": "string", "example": "usr_123" }, "login": { "type": "string", "example": "johndoe" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "avatarUrl": { "type": "string", "example": "https://avatars.githubusercontent.com/u/12345" }, "providerUrl": { "type": "string", "example": "https://github.com/johndoe" }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" } }, "required": [ "id", "login", "name", "email", "avatarUrl", "providerUrl", "createdAt", "updatedAt" ] }, "WorkspaceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "meta": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true, "description": "Whether there are more items available beyond this page" } }, "required": [ "hasMore" ] } }, "required": [ "data", "meta" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "example": "ws_abc123" }, "key": { "type": "string", "example": "my-workspace" }, "avatarUrl": { "type": "string", "example": "https://example.com/avatar.png" }, "providerUrl": { "type": "string", "example": "https://github.com/my-workspace" }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" } }, "required": [ "id", "key", "avatarUrl", "providerUrl", "createdAt", "updatedAt" ] } }, "parameters": {} }, "paths": { "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/components": { "get": { "operationId": "listComponents", "summary": "List components", "description": "Retrieve all Components defined for a Project. Supports JSON, newline-delimited JSON (`application/x-ndjson`), and CSV (`text/csv`) response formats via the `Accept` header.", "tags": [ "Components" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" } ], "responses": { "200": { "description": "List components for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentList" }, "example": { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Backend API", "description": "Core backend API services", "pathGlobs": [ "src/api/*" ], "fileCount": 42 } ] } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON) format" } }, "text/csv": { "schema": { "type": "string", "description": "CSV format with header row" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createComponent", "summary": "Create component", "description": "Create a Component for a Project. Requires admin access to the Project, and the Project must have Components enabled.", "tags": [ "Components" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" } ], "requestBody": { "description": "Component definition", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentInput" } } } }, "responses": { "201": { "description": "The created component", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDefinition" }, "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Backend API", "description": "Core backend API services", "pathGlobs": [ "src/api/*" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/components/{componentIdOrName}": { "put": { "operationId": "updateComponent", "summary": "Update component", "description": "Replace a Component's definition. Takes the same fields as create and fully replaces the existing definition; the Component's id and creator are preserved. Requires admin access to the Project, and the Project must have Components enabled.", "tags": [ "Components" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "backend-api", "description": "Component ID or name" }, "required": true, "description": "Component ID or name", "name": "componentIdOrName", "in": "path" } ], "requestBody": { "description": "Component definition", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentInput" } } } }, "responses": { "200": { "description": "The updated component", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDefinition" }, "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Backend API", "description": "Core backend API services", "pathGlobs": [ "src/api/*" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteComponent", "summary": "Delete component", "description": "Permanently delete a Component from a Project. Requires admin access to the Project, and the Project must have Components enabled.", "tags": [ "Components" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "backend-api", "description": "Component ID or name" }, "required": true, "description": "Component ID or name", "name": "componentIdOrName", "in": "path" } ], "responses": { "204": { "description": "Component deleted" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/components/{componentIdOrName}/metrics": { "get": { "operationId": "getComponentMetrics", "summary": "Get component metrics", "description": "Retrieve the latest value of every metric for a specific Component on the Project's default branch, covering maintainability, reliability, security, size, coverage, and quality indicators.", "tags": [ "Metrics" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "backend-api", "description": "Component ID or name" }, "required": true, "description": "Component ID or name", "name": "componentIdOrName", "in": "path" } ], "responses": { "200": { "description": "Retrieve metrics for a component", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentMetricList" }, "example": { "data": [ { "key": "CMPLX", "name": "Cognitive Complexity", "description": "Total cognitive complexity across all functions", "category": "maintainability", "value": 128, "inverted": true, "valueType": "number" }, { "key": "MNT", "name": "Maintainability Rating", "description": "Letter grade based on technical debt ratio", "category": "maintainability", "value": "A", "inverted": true, "valueType": "grade" }, { "key": "SEC", "name": "Security Rating", "description": "Overall security rating based on security vulnerabilities", "category": "security", "value": "A", "inverted": true, "valueType": "grade" }, { "key": "SIZE", "name": "Component Size", "description": "Overall component size classification", "category": "size", "value": "S", "inverted": false, "valueType": "size" }, { "key": "TDR", "name": "Technical Debt Ratio", "description": "Ratio of technical debt to total development cost", "category": "maintainability", "value": 4.2, "inverted": true, "valueType": "percentage" }, { "key": "COV", "name": "Coverage Rating", "description": "Letter grade based on test coverage", "category": "coverage", "value": "B", "inverted": true, "valueType": "grade" }, { "key": "LCOV", "name": "Line Coverage", "description": "Percentage of lines covered by tests", "category": "coverage", "value": 78.4, "inverted": false, "valueType": "percentage" }, { "key": "LOC", "name": "Lines of Code", "description": "Total lines of code", "category": "size", "value": 1204, "inverted": false, "valueType": "count" }, { "key": "FILES", "name": "Files", "description": "Number of files in the component", "category": "size", "value": 42, "inverted": false, "valueType": "count" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/components/{componentIdOrName}/metrics/series": { "get": { "operationId": "getComponentMetricSeries", "summary": "Get component metric series", "description": "Retrieve each metric's history for a specific Component on the Project's default branch as a time series over the requested window. Returns one series per metric — covering maintainability, reliability, security, size, coverage, and quality indicators — each with the metric's descriptor and one value per interval; narrow the result with the `metric` and `category` query parameters. Available as JSON, newline-delimited JSON (`application/x-ndjson`), or CSV (`text/csv`) via the `Accept` header. Buckets are UTC-aligned and labeled with the inclusive end of each interval; a bucket with no measurement carries the most recent prior value forward, and the final bucket (the one containing `to`) may be labeled later than `to` — including the future for an interval still in progress — with its value reflecting only measurements within the window.", "tags": [ "Metrics" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "backend-api", "description": "Component ID or name" }, "required": true, "description": "Component ID or name", "name": "componentIdOrName", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-01-01", "description": "Window start (RFC 3339 date or date-time, inclusive). Defaults to six months before `to`." }, "required": false, "description": "Window start (RFC 3339 date or date-time, inclusive). Defaults to six months before `to`.", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-06-01", "description": "Window end (RFC 3339 date or date-time, inclusive). Defaults to the current time and is clamped to it." }, "required": false, "description": "Window end (RFC 3339 date or date-time, inclusive). Defaults to the current time and is clamped to it.", "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "week", "description": "Bucket size; buckets are UTC-aligned and weeks start Monday" }, "required": false, "description": "Bucket size; buckets are UTC-aligned and weeks start Monday", "name": "interval", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "CMPLX", "DUP", "MNT", "SEC", "SIZE", "ISS", "SECI", "TDR", "FILES", "LOC", "COV", "LCOV" ] } }, { "type": "string", "enum": [ "CMPLX", "DUP", "MNT", "SEC", "SIZE", "ISS", "SECI", "TDR", "FILES", "LOC", "COV", "LCOV" ] } ], "description": "Filter by metric key" }, "required": false, "description": "Filter by metric key", "name": "metric", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "maintainability", "reliability", "security", "size", "coverage", "quality" ] } }, { "type": "string", "enum": [ "maintainability", "reliability", "security", "size", "coverage", "quality" ] } ], "description": "Filter by metric category" }, "required": false, "description": "Filter by metric category", "name": "category", "in": "query" } ], "responses": { "200": { "description": "Retrieve metric time series for a component", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricSeriesList" }, "example": { "data": [ { "metric": { "key": "LCOV", "name": "Line Coverage", "description": "Percentage of lines covered by tests", "category": "coverage", "inverted": false, "valueType": "percentage" }, "dimensions": {}, "points": [ { "timestamp": "2026-01-04T23:59:59Z", "value": 78.9 }, { "timestamp": "2026-01-11T23:59:59Z", "value": 80.2 } ] } ], "meta": { "from": "2025-12-29T00:00:00Z", "to": "2026-01-09T12:00:00Z", "interval": "week" } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON); one object per point with `metric`, `timestamp`, and `value`" } }, "text/csv": { "schema": { "type": "string", "description": "CSV with a `timestamp` column followed by one column per metric key" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/coverage/file": { "get": { "operationId": "getFileCoverage", "summary": "Get file coverage", "description": "Retrieve line-by-line test coverage data for a file at a specific Git reference or commit SHA", "tags": [ "Coverage" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "refs/heads/main", "description": "Git reference (refs/heads/branch, refs/tags/tag) or commit SHA" }, "required": true, "description": "Git reference (refs/heads/branch, refs/tags/tag) or commit SHA", "name": "reference", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "example": "src/index.ts", "description": "File path to get coverage for" }, "required": true, "description": "File path to get coverage for", "name": "path", "in": "query" } ], "responses": { "200": { "description": "Retrieve file coverage for the specified path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFileCoverageResponse" }, "example": { "tags": [ "unit", "integration" ], "files": [ { "path": "src/index.ts", "hits": [ 1, 0, 1, 1, 0 ], "tag": "unit", "coveredLines": 42, "missedLines": 8, "omitLines": 10, "totalLines": 60 } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/issues": { "get": { "operationId": "listIssues", "summary": "List issues", "description": "Retrieves a list of Issues associated with a Project. Supports JSON, newline-delimited JSON (`application/x-ndjson`), and CSV (`text/csv`) response formats via the `Accept` header.", "tags": [ "Issues" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 20, "description": "Maximum number of items to return (1-100)" }, "required": false, "description": "Maximum number of items to return (1-100)", "name": "page[limit]", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "example": 0, "description": "Number of items to skip" }, "required": false, "description": "Number of items to skip", "name": "page[offset]", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "bug", "vulnerability", "structure", "duplication", "security_hotspot", "performance", "documentation", "type_check", "style", "anti_pattern", "accessibility", "dead_code", "lint", "secret", "dependency_alert" ] } }, { "type": "string", "enum": [ "bug", "vulnerability", "structure", "duplication", "security_hotspot", "performance", "documentation", "type_check", "style", "anti_pattern", "accessibility", "dead_code", "lint", "secret", "dependency_alert" ] } ], "description": "Filter by issue category" }, "required": false, "description": "Filter by issue category", "name": "category", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "high", "medium", "low", "note", "fmt" ] } }, { "type": "string", "enum": [ "high", "medium", "low", "note", "fmt" ] } ], "description": "Filter by issue level" }, "required": false, "description": "Filter by issue level", "name": "level", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "open", "ignored" ] } }, { "type": "string", "enum": [ "open", "ignored" ] } ], "default": [ "open" ], "description": "Filter by issue status (defaults to open)" }, "required": false, "description": "Filter by issue status (defaults to open)", "name": "status", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ], "description": "Filter by tool name" }, "required": false, "description": "Filter by tool name", "name": "tool", "in": "query" } ], "responses": { "200": { "description": "List issues for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueList" }, "example": { "data": [ { "id": "49b5e789-cff8-47d2-bd1c-72a469980e15", "fingerprint": "3a1b2c3d4e5f6g7h8i9j", "tool": "eslint", "ruleKey": "no-unused-vars", "message": "Variable is defined but never used", "category": "lint", "level": "medium", "status": "open", "documentationUrl": "https://eslint.org/docs/rules/no-unused-vars", "location": { "path": "src/components/Button.tsx", "startLine": 15, "endLine": 15 } } ], "meta": { "hasMore": false } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON) format" } }, "text/csv": { "schema": { "type": "string", "description": "CSV format with header row" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/metrics": { "get": { "operationId": "getProjectMetrics", "summary": "Get project metrics", "description": "Retrieve the latest value of every metric on a Project's default branch, covering maintainability, reliability, security, size, coverage, and quality indicators.", "tags": [ "Metrics" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" } ], "responses": { "200": { "description": "Retrieve metrics for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricList" }, "example": { "data": [ { "key": "CMPLX", "name": "Cognitive Complexity", "description": "Total cognitive complexity across all functions", "category": "maintainability", "value": 1490, "inverted": true, "valueType": "number" }, { "key": "MNT", "name": "Maintainability Rating", "description": "Letter grade based on technical debt ratio", "category": "maintainability", "value": "A", "inverted": true, "valueType": "grade" }, { "key": "LCOV", "name": "Line Coverage", "description": "Percentage of lines covered by tests", "category": "coverage", "value": 87.5, "inverted": false, "valueType": "percentage" }, { "key": "LOC", "name": "Lines of Code", "description": "Total lines of code", "category": "size", "value": 28104, "inverted": false, "valueType": "count" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/metrics/series": { "get": { "operationId": "getProjectMetricSeries", "summary": "Get project metric series", "description": "Retrieve each metric's history on a Project's default branch as a time series over the requested window. Returns one series per metric — covering maintainability, reliability, security, size, coverage, and quality indicators — each with the metric's descriptor and one value per interval; narrow the result with the `metric` and `category` query parameters. Available as JSON, newline-delimited JSON (`application/x-ndjson`), or CSV (`text/csv`) via the `Accept` header. Buckets are UTC-aligned and labeled with the inclusive end of each interval; a bucket with no measurement carries the most recent prior value forward, and the final bucket (the one containing `to`) may be labeled later than `to` — including the future for an interval still in progress — with its value reflecting only measurements within the window.", "tags": [ "Metrics" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-01-01", "description": "Window start (RFC 3339 date or date-time, inclusive). Defaults to six months before `to`." }, "required": false, "description": "Window start (RFC 3339 date or date-time, inclusive). Defaults to six months before `to`.", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-06-01", "description": "Window end (RFC 3339 date or date-time, inclusive). Defaults to the current time and is clamped to it." }, "required": false, "description": "Window end (RFC 3339 date or date-time, inclusive). Defaults to the current time and is clamped to it.", "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "week", "description": "Bucket size; buckets are UTC-aligned and weeks start Monday" }, "required": false, "description": "Bucket size; buckets are UTC-aligned and weeks start Monday", "name": "interval", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "CMPLX", "DUP", "MNT", "SEC", "SIZE", "ISS", "SECI", "TDR", "FILES", "LOC", "COV", "LCOV" ] } }, { "type": "string", "enum": [ "CMPLX", "DUP", "MNT", "SEC", "SIZE", "ISS", "SECI", "TDR", "FILES", "LOC", "COV", "LCOV" ] } ], "description": "Filter by metric key" }, "required": false, "description": "Filter by metric key", "name": "metric", "in": "query" }, { "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "maintainability", "reliability", "security", "size", "coverage", "quality" ] } }, { "type": "string", "enum": [ "maintainability", "reliability", "security", "size", "coverage", "quality" ] } ], "description": "Filter by metric category" }, "required": false, "description": "Filter by metric category", "name": "category", "in": "query" } ], "responses": { "200": { "description": "Retrieve metric time series for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricSeriesList" }, "example": { "data": [ { "metric": { "key": "LCOV", "name": "Line Coverage", "description": "Percentage of lines covered by tests", "category": "coverage", "inverted": false, "valueType": "percentage" }, "dimensions": {}, "points": [ { "timestamp": "2026-01-04T23:59:59Z", "value": 78.9 }, { "timestamp": "2026-01-11T23:59:59Z", "value": 80.2 } ] } ], "meta": { "from": "2025-12-29T00:00:00Z", "to": "2026-01-09T12:00:00Z", "interval": "week" } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON); one object per point with `metric`, `timestamp`, and `value`" } }, "text/csv": { "schema": { "type": "string", "description": "CSV with a `timestamp` column followed by one column per metric key" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{projectKeyOrId}/files": { "get": { "operationId": "getFileMetrics", "summary": "Get file metrics", "description": "Retrieve the latest values of all metrics for a file in a Project's default branch", "tags": [ "Metrics" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "projectKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "example": "src/index.ts", "description": "File path to retrieve metrics for" }, "required": true, "description": "File path to retrieve metrics for", "name": "path", "in": "query" } ], "responses": { "200": { "description": "Retrieve metrics for a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileMetricList" }, "example": { "data": [ { "key": "CMPLX", "name": "Cognitive Complexity", "description": "Total cognitive complexity across all functions", "category": "maintainability", "value": 8, "inverted": true }, { "key": "LOC", "name": "Lines of Code", "description": "Total lines of code", "category": "size", "value": 47, "inverted": false } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "description": "Retrieves a list of Projects associated with a Workspace. Supports JSON, newline-delimited JSON (`application/x-ndjson`), and CSV (`text/csv`) response formats via the `Accept` header.", "tags": [ "Projects" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 20, "description": "Maximum number of items to return (1-100)" }, "required": false, "description": "Maximum number of items to return (1-100)", "name": "page[limit]", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "example": 0, "description": "Number of items to skip" }, "required": false, "description": "Number of items to skip", "name": "page[offset]", "in": "query" } ], "responses": { "200": { "description": "List all projects for the owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" }, "example": { "data": [ { "id": "85fae897-5a48-483b-ad29-1852c0db1707", "workspaceId": "1c47b6fd-db56-4fbd-9cf0-4d88f9631050", "providerUrl": "https://github.com/acmeco/awesome-project", "key": "awesome-project", "workspaceKey": "acmeco" } ], "meta": { "hasMore": false } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON) format", "example": "{\"id\":\"550e8400-e29b-41d4-a716-446655440000\",\"workspaceId\":\"ws_abc123\",\"providerUrl\":\"https://github.com/acme-corp/my-repo\",\"key\":\"my-repo\",\"workspaceKey\":\"acme-corp\"}" } }, "text/csv": { "schema": { "type": "string", "description": "CSV format with header row", "example": "id,workspaceId,providerUrl,key,workspaceKey\n550e8400-e29b-41d4-a716-446655440000,ws_abc123,https://github.com/acme-corp/my-repo,my-repo,acme-corp" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/gh/{ownerKeyOrId}/projects/{keyOrId}": { "get": { "operationId": "getProject", "summary": "Get a project", "description": "Retrieves details about a specific Project", "tags": [ "Projects" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "acme-corp", "description": "Repository owner name (login) or workspace ID" }, "required": true, "description": "Repository owner name (login) or workspace ID", "name": "ownerKeyOrId", "in": "path" }, { "schema": { "type": "string", "minLength": 3, "example": "my-repo", "description": "Repository name or project ID" }, "required": true, "description": "Repository name or project ID", "name": "keyOrId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "id": "85fae897-5a48-483b-ad29-1852c0db1707", "workspaceId": "1c47b6fd-db56-4fbd-9cf0-4d88f9631050", "providerUrl": "https://github.com/acmeco/awesome-project", "key": "awesome-project", "workspaceKey": "acmeco" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rate_limit": { "get": { "operationId": "getRateLimit", "summary": "Get rate limit status", "description": "Retrieve the rate limit status for the authenticated token. Rate limits use a one-hour window; the current limit and usage are also reported on every response via the `x-ratelimit-*` headers.", "tags": [ "Service" ], "responses": { "200": { "description": "Rate limit status for the authenticated user", "headers": { "x-ratelimit-limit": { "schema": { "type": "integer", "example": 5000, "description": "Maximum number of requests allowed in the current window" }, "required": false, "description": "Maximum number of requests allowed in the current window" }, "x-ratelimit-remaining": { "schema": { "type": "integer", "example": 4990, "description": "Number of requests remaining in the current window" }, "required": false, "description": "Number of requests remaining in the current window" }, "x-ratelimit-used": { "schema": { "type": "integer", "example": 10, "description": "Number of requests used in the current window" }, "required": false, "description": "Number of requests used in the current window" }, "x-ratelimit-reset": { "schema": { "type": "integer", "example": 1734567890, "description": "Unix timestamp when the rate limit window resets" }, "required": false, "description": "Unix timestamp when the rate limit window resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitResponse" }, "example": { "resources": { "core": { "limit": 5000, "used": 10, "remaining": 4990, "reset": 1734567890 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user": { "get": { "operationId": "getUser", "summary": "Get authenticated user", "description": "Get the authenticated User based on the provided access token", "tags": [ "User" ], "responses": { "200": { "description": "The currently authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedUser" }, "example": { "id": "e34cb947-2b6f-47df-ae0c-776e17f3fdbf", "login": "alice", "name": "Alice", "email": "alice@example.com", "avatarUrl": "https://avatars.githubusercontent.com/u/12345", "providerUrl": "https://github.com/alice", "createdAt": "2023-01-01T00:00:00Z", "updatedAt": "2023-01-01T00:00:00Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "description": "List Workspaces accessible to the authenticated token. Supports JSON, newline-delimited JSON (`application/x-ndjson`), and CSV (`text/csv`) response formats via the `Accept` header.", "tags": [ "Workspaces" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 20, "description": "Maximum number of items to return (1-100)" }, "required": false, "description": "Maximum number of items to return (1-100)", "name": "page[limit]", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "example": 0, "description": "Number of items to skip" }, "required": false, "description": "Number of items to skip", "name": "page[offset]", "in": "query" } ], "responses": { "200": { "description": "List all workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceList" }, "example": { "data": [ { "id": "1c47b6fd-db56-4fbd-9cf0-4d88f9631050", "key": "acmeco", "avatarUrl": "https://assets.github.com/acmeco.png", "providerUrl": "https://github.com/acmeco", "createdAt": "2023-01-15T08:30:00Z", "updatedAt": "2023-02-20T14:45:00Z" } ], "meta": { "hasMore": false } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (NDJSON) format", "example": "{\"id\":\"ws_abc123\",\"key\":\"my-workspace\",\"avatarUrl\":\"https://example.com/avatar.png\",\"providerUrl\":\"https://github.com/my-workspace\",\"createdAt\":\"2024-01-01T00:00:00.000Z\",\"updatedAt\":\"2024-01-01T00:00:00.000Z\"}" } }, "text/csv": { "schema": { "type": "string", "description": "CSV format with header row", "example": "id,key,avatarUrl,providerUrl,createdAt,updatedAt\nws_abc123,my-workspace,https://example.com/avatar.png,https://github.com/my-workspace,2024-01-01T00:00:00.000Z,2024-01-01T00:00:00.000Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workspaces/{keyOrId}": { "get": { "operationId": "getWorkspace", "summary": "Get a workspace", "description": "Retrieve a single Workspace by its ID or key", "tags": [ "Workspaces" ], "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "my-workspace", "description": "Workspace key or ID" }, "required": true, "description": "Workspace key or ID", "name": "keyOrId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" }, "example": { "id": "1c47b6fd-db56-4fbd-9cf0-4d88f9631050", "key": "acmeco", "avatarUrl": "https://assets.github.com/acmeco.png", "providerUrl": "https://github.com/acmeco", "createdAt": "2023-01-15T08:30:00Z", "updatedAt": "2023-02-20T14:45:00Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }