{ "openapi": "3.1.0", "info": { "title": "TaskNebula API", "version": "0.6.5", "description": "OpenAPI documentation for the TaskNebula HTTP API. Only the public, stable surface is documented; internal/admin routes are intentionally omitted." }, "servers": [ { "url": "/", "description": "Current host" } ], "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "__Secure-authjs.session-token", "description": "NextAuth session cookie. In dev the cookie is named `authjs.session-token`." } }, "schemas": { "IssueType": { "type": "string", "enum": [ "story", "task", "bug", "epic" ] }, "IssuePriority": { "type": "string", "enum": [ "critical", "high", "medium", "low", "none" ] }, "IssueResolution": { "type": [ "string", "null" ], "enum": [ "fixed", "wont_do", "duplicate", "cannot_reproduce", "done" ] }, "Issue": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "projectId": { "type": "string" }, "key": { "type": "string", "example": "PROJ-12" }, "number": { "type": [ "integer", "null" ] }, "type": { "$ref": "#/components/schemas/IssueType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "statusId": { "type": [ "string", "null" ] }, "priority": { "$ref": "#/components/schemas/IssuePriority" }, "assigneeId": { "type": [ "string", "null" ] }, "reporterId": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] }, "sprintId": { "type": [ "string", "null" ] }, "epicId": { "type": [ "string", "null" ] }, "parentId": { "type": [ "string", "null" ] }, "estimate": { "type": [ "number", "null" ] }, "dueDate": { "type": [ "string", "null" ], "format": "date-time" }, "resolution": { "$ref": "#/components/schemas/IssueResolution" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "projectId", "key", "number", "type", "title", "description", "statusId", "priority", "assigneeId", "reporterId", "sprintId", "epicId", "parentId", "estimate", "dueDate", "resolution", "resolvedAt", "createdAt", "updatedAt" ] }, "IssueListResponse": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "total": { "type": "integer" } }, "required": [ "issues", "total" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "details": {} }, "required": [ "error" ] }, "IssueStatusCategory": { "type": "string", "enum": [ "backlog", "todo", "in_progress", "in_review", "done", "cancelled" ] }, "CreateIssueBody": { "type": "object", "properties": { "projectId": { "type": "string" }, "type": { "$ref": "#/components/schemas/IssueType" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": [ "string", "null" ] }, "priority": { "allOf": [ { "$ref": "#/components/schemas/IssuePriority" }, { "default": "medium" } ] }, "assigneeId": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] }, "sprintId": { "type": "string" }, "epicId": { "type": "string" }, "parentId": { "type": "string" }, "estimate": { "type": "number" }, "dueDate": { "type": "string", "format": "date-time" }, "customFields": { "type": "object", "additionalProperties": {}, "default": {} }, "statusId": { "type": "string" } }, "required": [ "projectId", "type", "title" ] }, "UpdateIssueBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/IssueStatusCategory" }, "statusId": { "type": "string" }, "priority": { "$ref": "#/components/schemas/IssuePriority" }, "assigneeId": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "sprintId": { "type": [ "string", "null" ] }, "epicId": { "type": [ "string", "null" ] }, "parentId": { "type": [ "string", "null" ] }, "estimate": { "type": [ "number", "null" ] }, "dueDate": { "type": [ "string", "null" ], "format": "date-time" }, "customFields": { "type": "object", "additionalProperties": {} }, "resolution": { "allOf": [ { "$ref": "#/components/schemas/IssueResolution" }, { "description": "Jira-style resolution. Setting a value stamps `resolvedAt`; an explicit `null` clears both fields." } ] } } }, "DeleteIssueResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "success", "id" ] }, "Comment": { "type": "object", "properties": { "id": { "type": "string" }, "issueId": { "type": "string" }, "content": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "mentions": { "type": "array", "items": { "type": "string" } }, "reactions": { "type": "array", "items": {} }, "isInternal": { "type": "string", "description": "\"true\" | \"false\" (stored as string)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": [ "string", "null" ] }, "updatedBy": { "type": [ "string", "null" ] } }, "required": [ "id", "issueId", "content", "parentId", "mentions", "reactions", "isInternal", "createdAt", "updatedAt", "createdBy", "updatedBy" ] }, "CreateCommentBody": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "parentId": { "type": "string" }, "mentions": { "type": "array", "items": { "type": "string" }, "default": [] }, "isInternal": { "type": "boolean", "default": false } }, "required": [ "content" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "teamId": { "type": [ "string", "null" ] }, "key": { "type": "string", "example": "PROJ" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "settings": { "type": "object", "additionalProperties": {}, "default": {} }, "defaultWorkflowId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "organizationName": { "type": "string" }, "team": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } }, "required": [ "id", "organizationId", "teamId", "key", "name", "description", "status", "defaultWorkflowId", "createdAt", "updatedAt" ] }, "Label": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "`null` = org-wide label" }, "name": { "type": "string" }, "color": { "type": "string", "example": "#6B7280" }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": [ "string", "null" ] } }, "required": [ "id", "organizationId", "projectId", "name", "color", "description", "createdAt", "updatedAt", "createdBy" ] }, "LabelWithUsage": { "allOf": [ { "$ref": "#/components/schemas/Label" }, { "type": "object", "properties": { "usageCount": { "type": "integer", "description": "Number of issues currently tagged with this label." } }, "required": [ "usageCount" ] } ] }, "LabelListResponse": { "type": "object", "properties": { "labels": { "type": "array", "items": { "$ref": "#/components/schemas/LabelWithUsage" } } }, "required": [ "labels" ] }, "CreateLabelBody": { "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "projectId": { "type": [ "string", "null" ], "minLength": 1, "description": "Optional project scope; `null`/absent = org-wide label." }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "color": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "description": "Hex color like `#6B7280`. Defaults to `#6B7280`." }, "description": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "organizationId", "name" ] }, "UpdateLabelBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Renaming also rewrites the legacy `issues.labels` JSONB arrays org-wide in the same transaction." }, "color": { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" }, "description": { "type": [ "string", "null" ], "maxLength": 2000 } } }, "DeleteLabelResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "success", "id" ] }, "VersionStatus": { "type": "string", "enum": [ "unreleased", "released", "archived" ] }, "ProjectVersion": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string", "example": "1.4.0" }, "description": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/VersionStatus" }, "startDate": { "type": [ "string", "null" ], "format": "date-time" }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Planned release date." }, "releasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Stamped when the version is released." }, "sortOrder": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": [ "string", "null" ] } }, "required": [ "id", "organizationId", "projectId", "name", "description", "status", "startDate", "releaseDate", "releasedAt", "sortOrder", "createdAt", "updatedAt", "createdBy" ] }, "ProjectVersionWithCounts": { "allOf": [ { "$ref": "#/components/schemas/ProjectVersion" }, { "type": "object", "properties": { "issueCount": { "type": "integer" }, "doneIssueCount": { "type": "integer", "description": "Issues with a non-null resolution." } }, "required": [ "issueCount", "doneIssueCount" ] } ] }, "VersionListResponse": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectVersionWithCounts" } }, "total": { "type": "integer" } }, "required": [ "versions", "total" ] }, "VersionResponse": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/ProjectVersion" } }, "required": [ "version" ] }, "CreateVersionBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "startDate": { "type": [ "string", "null" ], "format": "date-time" }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "name" ] }, "UpdateVersionBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "startDate": { "type": [ "string", "null" ], "format": "date-time" }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "allOf": [ { "$ref": "#/components/schemas/VersionStatus" }, { "description": "Transitioning to `released` stamps `releasedAt` (if unset); back to `unreleased` clears it." } ] }, "sortOrder": { "type": "integer" } } }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "ReleaseVersionResponse": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/ProjectVersion" }, "movedIssueCount": { "type": "integer" } }, "required": [ "version", "movedIssueCount" ] }, "ReleaseVersionBody": { "type": "object", "properties": { "moveOpenIssuesToVersionId": { "type": "string", "description": "Optional: re-point unresolved issues' fix-version to another version of the same project." } } }, "IssueVersionsResponse": { "type": "object", "properties": { "fixVersions": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectVersion" } }, "affectsVersions": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectVersion" } } }, "required": [ "fixVersions", "affectsVersions" ] }, "SetIssueVersionsBody": { "type": "object", "properties": { "fixVersionIds": { "type": "array", "items": { "type": "string" } }, "affectsVersionIds": { "type": "array", "items": { "type": "string" } } }, "description": "Replaces the respective association set(s). At least one of `fixVersionIds` or `affectsVersionIds` must be provided. Every referenced version must belong to the issue's project." }, "ComponentDefaultAssigneeType": { "type": "string", "enum": [ "project_default", "component_lead", "unassigned" ] }, "Component": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "leadId": { "type": [ "string", "null" ] }, "defaultAssigneeType": { "$ref": "#/components/schemas/ComponentDefaultAssigneeType" }, "archived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "projectId", "name", "description", "leadId", "defaultAssigneeType", "archived", "createdAt", "updatedAt" ] }, "ComponentWithCount": { "allOf": [ { "$ref": "#/components/schemas/Component" }, { "type": "object", "properties": { "issueCount": { "type": "integer" } }, "required": [ "issueCount" ] } ] }, "ComponentListResponse": { "type": "object", "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentWithCount" } }, "total": { "type": "integer" } }, "required": [ "components", "total" ] }, "ComponentResponse": { "type": "object", "properties": { "component": { "$ref": "#/components/schemas/Component" } }, "required": [ "component" ] }, "CreateComponentBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "leadId": { "type": [ "string", "null" ], "description": "Must be an active member of the organization." }, "defaultAssigneeType": { "allOf": [ { "$ref": "#/components/schemas/ComponentDefaultAssigneeType" }, { "default": "project_default" } ] } }, "required": [ "name" ] }, "UpdateComponentBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "leadId": { "type": [ "string", "null" ], "description": "Must be an active member of the organization." }, "defaultAssigneeType": { "$ref": "#/components/schemas/ComponentDefaultAssigneeType" }, "archived": { "type": "boolean" } } }, "IssueComponentsResponse": { "type": "object", "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } } }, "required": [ "components" ] }, "SetIssueComponentsBody": { "type": "object", "properties": { "componentIds": { "type": "array", "items": { "type": "string" }, "description": "Replaces the issue's component set. Every component must belong to the issue's project." } }, "required": [ "componentIds" ] }, "CurrentUser": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "isSuperAdmin": { "type": "boolean" }, "status": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "image", "isSuperAdmin", "status" ] }, "SearchResultIssue": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "labels": { "type": [ "array", "null" ], "items": { "type": "string" } }, "assigneeId": { "type": [ "string", "null" ] }, "reporterId": { "type": [ "string", "null" ] }, "projectId": { "type": "string" }, "sprintId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "key", "title", "description", "status", "priority", "type", "labels", "assigneeId", "reporterId", "projectId", "sprintId", "createdAt", "updatedAt" ] }, "SearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultIssue" } }, "count": { "type": "integer" }, "query": { "type": "string" }, "criteria": { "type": "object", "additionalProperties": {} } }, "required": [ "results", "count", "query", "criteria" ] }, "SearchBody": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "JQL-style query string", "example": "assignee = me AND status = \"In Progress\"" }, "organizationId": { "type": "string" }, "projectId": { "type": "string" }, "saveHistory": { "type": "boolean", "default": true }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "default": 0 } }, "required": [ "q", "organizationId" ] }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "unhealthy" ] }, "timestamp": { "type": "string", "format": "date-time" }, "uptime": { "type": "number" }, "checks": { "type": "object", "properties": { "database": { "type": "string" }, "memory": { "type": "string" }, "redis": { "type": "string" }, "livekit": { "type": "string" }, "smtp": { "type": "string" } }, "required": [ "database", "memory", "redis", "livekit", "smtp" ] }, "details": { "type": "object", "additionalProperties": { "type": "string" } }, "version": { "type": "string" } }, "required": [ "status", "timestamp", "uptime", "checks" ] } }, "parameters": {} }, "paths": { "/api/issues": { "get": { "summary": "List issues", "description": "Returns issues visible to the authenticated user. Optionally filter by project, assignee, status category, sprint, parent, or type.", "tags": [ "Issues" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "projectId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "assigneeId", "in": "query" }, { "schema": { "$ref": "#/components/schemas/IssueStatusCategory" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "sprintId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "parentId", "in": "query" }, { "schema": { "$ref": "#/components/schemas/IssueType" }, "required": false, "name": "type", "in": "query" } ], "responses": { "200": { "description": "A list of issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueListResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller has no access to the requested project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create an issue", "description": "Creates a new issue in the given project. The caller must have `create` permission for the project.", "tags": [ "Issues" ], "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIssueBody" } } } }, "responses": { "201": { "description": "The created issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — insufficient permissions to create issues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/issues/{issueId}": { "get": { "summary": "Get an issue", "description": "Fetch a single issue by id.", "tags": [ "Issues" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "responses": { "200": { "description": "The issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller has no view access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Issue not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "summary": "Update an issue", "description": "Partial update. The required permission depends on which fields are changed (edit, assign, transition, schedule).", "tags": [ "Issues" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIssueBody" } } } }, "responses": { "200": { "description": "The updated issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — missing permission for one of the requested changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Issue or referenced status not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete an issue", "tags": [ "Issues" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "responses": { "200": { "description": "Issue deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteIssueResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Issue not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/issues/{issueId}/comments": { "post": { "summary": "Comment on an issue", "tags": [ "Comments" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommentBody" } } } }, "responses": { "201": { "description": "The created comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/projects": { "get": { "summary": "List projects accessible to the current user", "description": "Returns projects from organizations the caller is a member of, optionally narrowed by `organizationId` and/or `teamId`. Super admins see all projects in the scope.", "tags": [ "Projects" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "organizationId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "teamId", "in": "query" } ], "responses": { "200": { "description": "A list of projects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller is not in the requested organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/labels": { "get": { "summary": "List labels for an organization", "description": "Returns the organization's labels with per-label usage counts, ordered by name. When `projectId` is given, returns that project's labels plus org-wide labels. `q` filters by case-insensitive name prefix.", "tags": [ "Labels" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "organizationId", "in": "query" }, { "schema": { "type": "string", "description": "When given, returns that project's labels plus org-wide labels (`projectId = null`)." }, "required": false, "name": "projectId", "in": "query" }, { "schema": { "type": "string", "description": "Case-insensitive name prefix filter." }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "A list of labels with usage counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelListResponse" } } } }, "400": { "description": "`organizationId` is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller is not an active member of the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create a label", "description": "Creates an org-wide label, or a project-scoped one when `projectId` is provided. Label names are unique per (organization, project) scope.", "tags": [ "Labels" ], "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabelBody" } } } }, "responses": { "201": { "description": "The created label.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller is not an active member of the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A label with this name already exists in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/labels/{labelId}": { "patch": { "summary": "Update a label", "description": "Rename / recolor / re-describe a label. On rename, the legacy `issues.labels` JSONB arrays in the organization are rewritten in the same transaction.", "tags": [ "Labels" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "labelId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLabelBody" } } } }, "responses": { "200": { "description": "The updated label.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller is not a member of the label's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Label not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A label with this name already exists in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete a label", "description": "Deletes the label. Issue associations cascade, and the name is removed from the legacy `issues.labels` JSONB arrays org-wide in the same transaction.", "tags": [ "Labels" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "labelId", "in": "path" } ], "responses": { "200": { "description": "Label deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteLabelResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller is not a member of the label's organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Label not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/projects/{projectId}/versions": { "get": { "summary": "List versions for a project", "description": "Returns the project's versions ordered by sort order then name, with per-version issue counts (`doneIssueCount` = issues with a non-null resolution).", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "A list of versions with issue counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionListResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found (or not visible to the caller).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create a version", "description": "Creates a version in the project. Requires project-manage permission. Version names are unique per project; the new version is appended to the sort order.", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionBody" } } } }, "responses": { "201": { "description": "The created version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot manage the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found (or not visible to the caller).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A version with this name already exists in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/projects/{projectId}/versions/{versionId}": { "get": { "summary": "Get a version", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "versionId", "in": "path" } ], "responses": { "200": { "description": "The version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project or version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "summary": "Update a version", "description": "Partial update. Transitioning `status` to `released` stamps `releasedAt` (if unset); back to `unreleased` clears it. Requires project-manage permission.", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "versionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVersionBody" } } } }, "responses": { "200": { "description": "The updated version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot manage the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project or version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A version with this name already exists in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete a version", "description": "Deletes the version. Issue fix/affects associations cascade. Requires project-manage permission.", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "versionId", "in": "path" } ], "responses": { "200": { "description": "Version deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot manage the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project or version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/projects/{projectId}/versions/{versionId}/release": { "post": { "summary": "Release a version", "description": "Marks the version as released (stamps `releasedAt`). Optionally re-points unresolved issues' fix-version to another version of the same project via `moveOpenIssuesToVersionId`. The body may be omitted entirely. Requires project-manage permission.", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "versionId", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseVersionBody" } } } }, "responses": { "200": { "description": "The released version and the number of issues moved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseVersionResponse" } } } }, "400": { "description": "Invalid JSON body, validation failed, or the move target is invalid (same version or not in this project).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot manage the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project or version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/issues/{issueId}/versions": { "get": { "summary": "List fix and affects versions for an issue", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "responses": { "200": { "description": "The issue's fix and affects versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueVersionsResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller has no view access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Issue not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "summary": "Replace an issue's fix and/or affects versions", "description": "Replaces the provided association set(s). At least one of `fixVersionIds` or `affectsVersionIds` must be provided; every version must belong to the issue's project.", "tags": [ "Versions" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIssueVersionsBody" } } } }, "responses": { "200": { "description": "The issue's updated fix and affects versions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueVersionsResponse" } } } }, "400": { "description": "Validation failed, or some versions do not belong to the issue's project (response includes `invalidIds`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot edit the issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Issue not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/projects/{projectId}/components": { "get": { "summary": "List components for a project", "description": "Returns the project's components ordered by name, with per-component issue counts.", "tags": [ "Components" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "A list of components with issue counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentListResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found (or not visible to the caller).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create a component", "description": "Creates a component in the project. Requires project-manage permission. Component names are unique per project; `leadId` must be an active member of the organization.", "tags": [ "Components" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComponentBody" } } } }, "responses": { "201": { "description": "The created component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentResponse" } } } }, "400": { "description": "Validation failed, or the lead is not an active organization member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot manage the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project not found (or not visible to the caller).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A component with this name already exists in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/projects/{projectId}/components/{componentId}": { "get": { "summary": "Get a component", "tags": [ "Components" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "componentId", "in": "path" } ], "responses": { "200": { "description": "The component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project or component not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "summary": "Update a component", "description": "Partial update, including archiving via `archived`. Requires project-manage permission.", "tags": [ "Components" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "componentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateComponentBody" } } } }, "responses": { "200": { "description": "The updated component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentResponse" } } } }, "400": { "description": "Validation failed, or the lead is not an active organization member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot manage the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project or component not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A component with this name already exists in this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Delete a component", "description": "Deletes the component. Issue associations cascade. Requires project-manage permission.", "tags": [ "Components" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Project id or key" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "componentId", "in": "path" } ], "responses": { "200": { "description": "Component deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot manage the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Project or component not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/issues/{issueId}/components": { "get": { "summary": "List components linked to an issue", "tags": [ "Components" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "responses": { "200": { "description": "The issue's components.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueComponentsResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller has no view access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Issue not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "summary": "Replace an issue's components", "description": "Replaces the issue's component set. Every component must belong to the issue's project.", "tags": [ "Components" ], "security": [ { "cookieAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "issueId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIssueComponentsBody" } } } }, "responses": { "200": { "description": "The issue's updated components.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueComponentsResponse" } } } }, "400": { "description": "Validation failed, or some components do not belong to the issue's project (response includes `invalidIds`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — caller cannot edit the issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Issue not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/users/me": { "get": { "summary": "Get the current authenticated user", "description": "Returns the authenticated user with their super-admin and account status. Equivalent to the legacy `/api/user/me` endpoint.", "tags": [ "Users" ], "security": [ { "cookieAuth": [] } ], "responses": { "200": { "description": "The current user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUser" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "User not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/search": { "post": { "summary": "Execute a JQL-style search", "description": "Run a structured search query against issues. Accepts JQL-style expressions like `assignee = me AND status = \"In Progress\"`.", "tags": [ "Search" ], "security": [ { "cookieAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchBody" } } } }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid query syntax or missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/health": { "get": { "summary": "Service health check", "description": "Returns the health status of the application — database, memory, redis, livekit and smtp checks. Used by container orchestrators and monitoring.", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Service is healthy or degraded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "500": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service is unhealthy (database or memory failure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } } }, "webhooks": {} }