接口目录
218 个操作 · 直接来自共享规范 · 只读参考
GET/api/mcpMCP stream probe (stateless)
Stateless Streamable HTTP using the official Go SDK. API Key only: cookies never authenticate this endpoint. Every HTTP request revalidates the Key/owner/workspace and consumes the existing shared rate budget; tool dispatch applies read/write scope to the actual operation, not POST. Existing REST handlers and transaction checks enforce private-team and write permissions. No session replay, browser CORS, OAuth registration or new network destination. GET returns 405; DELETE requires Mcp-Session-Id (400 if absent) and returns 204 without retaining or deleting a persistent session. SDK errors may use text/plain; tool business errors are MCP isError results containing only an error code.
鉴权
[
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "MCP-Protocol-Version",
"in": "header",
"schema": {
"type": "string"
},
"description": "Negotiated MCP protocol version; SDK validation applies."
},
{
"name": "Accept",
"in": "header",
"schema": {
"type": "string"
},
"description": "Include application/json and text/event-stream, as required by Streamable HTTP."
}
],
"responses": {
"400": {
"description": "Invalid RPC request, workspace context or protocol version.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Missing, invalid, revoked or expired API Key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Insufficient access or rejected Origin/Host.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"405": {
"description": "Stateless transport does not provide GET streams or DELETE sessions.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"406": {
"description": "Client must accept application/json and text/event-stream.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Request exceeds 1 MiB.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"415": {
"description": "Content-Type must be application/json.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Shared per-Key limit exceeded; inspect Retry-After.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
},
"headers": {
"Retry-After": {
"description": "At least one second until the shared Key window resets.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}
},
"500": {
"description": "Internal error; no database or credential details.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
POST/api/mcpCall the authenticated MCP server
Stateless Streamable HTTP using the official Go SDK. API Key only: cookies never authenticate this endpoint. Every HTTP request revalidates the Key/owner/workspace and consumes the existing shared rate budget; tool dispatch applies read/write scope to the actual operation, not POST. Existing REST handlers and transaction checks enforce private-team and write permissions. No session replay, browser CORS, OAuth registration or new network destination. GET returns 405; DELETE requires Mcp-Session-Id (400 if absent) and returns 204 without retaining or deleting a persistent session. SDK errors may use text/plain; tool business errors are MCP isError results containing only an error code.
鉴权
[
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "MCP-Protocol-Version",
"in": "header",
"schema": {
"type": "string"
},
"description": "Negotiated MCP protocol version; SDK validation applies."
},
{
"name": "Accept",
"in": "header",
"schema": {
"type": "string"
},
"description": "Include application/json and text/event-stream, as required by Streamable HTTP."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MCPRequest"
}
}
}
},
"responses": {
"200": {
"description": "MCP JSON-RPC response; tool data is untrusted workspace content, not instructions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MCPResponse"
}
}
}
},
"202": {
"description": "MCP notification accepted; response has no body."
},
"400": {
"description": "Invalid RPC request, workspace context or protocol version.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Missing, invalid, revoked or expired API Key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Insufficient access or rejected Origin/Host.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"405": {
"description": "Stateless transport does not provide GET streams or DELETE sessions.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"406": {
"description": "Client must accept application/json and text/event-stream.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Request exceeds 1 MiB.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"415": {
"description": "Content-Type must be application/json.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Shared per-Key limit exceeded; inspect Retry-After.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
},
"headers": {
"Retry-After": {
"description": "At least one second until the shared Key window resets.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}
},
"500": {
"description": "Internal error; no database or credential details.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
DELETE/api/mcpMCP session deletion probe (stateless)
Stateless Streamable HTTP using the official Go SDK. API Key only: cookies never authenticate this endpoint. Every HTTP request revalidates the Key/owner/workspace and consumes the existing shared rate budget; tool dispatch applies read/write scope to the actual operation, not POST. Existing REST handlers and transaction checks enforce private-team and write permissions. No session replay, browser CORS, OAuth registration or new network destination. GET returns 405; DELETE requires Mcp-Session-Id (400 if absent) and returns 204 without retaining or deleting a persistent session. SDK errors may use text/plain; tool business errors are MCP isError results containing only an error code.
鉴权
[
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "MCP-Protocol-Version",
"in": "header",
"schema": {
"type": "string"
},
"description": "Negotiated MCP protocol version; SDK validation applies."
},
{
"name": "Accept",
"in": "header",
"schema": {
"type": "string"
},
"description": "Include application/json and text/event-stream, as required by Streamable HTTP."
},
{
"name": "Mcp-Session-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Required by the SDK DELETE contract; stateless mode does not persist or validate a session identity."
}
],
"responses": {
"204": {
"description": "Stateless deletion acknowledged; no retained session and no response body."
},
"400": {
"description": "Invalid RPC request, workspace context or protocol version.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Missing, invalid, revoked or expired API Key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "Insufficient access or rejected Origin/Host.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"405": {
"description": "Stateless transport does not provide GET streams or DELETE sessions.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"406": {
"description": "Client must accept application/json and text/event-stream.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "Request exceeds 1 MiB.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"415": {
"description": "Content-Type must be application/json.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Shared per-Key limit exceeded; inspect Retry-After.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
},
"headers": {
"Retry-After": {
"description": "At least one second until the shared Key window resets.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}
},
"500": {
"description": "Internal error; no database or credential details.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
GET/api/initiatives/{initiativeId}/updatesList initiative updates
Lists real, nondeleted updates in newest-first order; author/admin capabilities reflect the current viewer.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List initiative updates",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreInitiativeUpdate"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/initiatives/{initiativeId}/updatesPublish initiative update
Active members publish body and three-state health. Only a new successful publication freezes subscribed active recipients, excluding the author, in the existing transactional durable notification intents. Delivery rechecks access and source; no body snapshot is stored in notifications. Requires Idempotency-Key.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "Exactly one lowercase 32-character hexadecimal operation ID. A retry with the same body resolves the original authorized update; changed content conflicts.",
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiativeUpdateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Publish initiative update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiativeUpdate"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/initiatives/{initiativeId}/updates/{updateId}Read initiative update
Reads the exact update under its current initiative and workspace, with current author/admin capabilities.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Read initiative update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiativeUpdate"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/initiatives/{initiativeId}/updates/{updateId}Edit initiative update
Only its author may replace body and health; both fields required. Edits publish workspace sync but do not notify subscribers again.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiativeUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Edit initiative update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiativeUpdate"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/initiatives/{initiativeId}/updates/{updateId}Delete initiative update
Author or current workspace admin may soft-delete this update. Deleted sources are unavailable to subsequent notification delivery and reads.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete initiative update"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/initiatives/{initiativeId}/subscriptionRead initiative subscription
Returns only the current user subscription for this initiative.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Read initiative subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiativeSubscription"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PUT/api/initiatives/{initiativeId}/subscriptionSet initiative subscription
Sets only the current user subscription. No notification is generated for subscribing, unsubscribing or repeated state.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiativeSubscription"
}
}
}
},
"responses": {
"204": {
"description": "Set initiative subscription"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/initiativesList initiatives
Returns workspace initiatives with actor-readable direct project memberships and deduplicated current progress/health. An empty workspace returns [].
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List initiatives",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreInitiative"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/initiativesCreate an initiative
Creates a workspace initiative, with optional one-level parent and readable direct projects. Current membership and key scope are revalidated in the write transaction.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCreateInitiativeRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create an initiative",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiative"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/initiatives/{initiativeId}Get an initiative
Foreign-workspace and missing initiatives return the same 404. Project identities, issue progress and health are projected using current private-team permissions.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get an initiative",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiative"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/initiatives/{initiativeId}Update an initiative
Sparse update under the workspace lock; preserves hidden project memberships and omitted fields. At most one nested level. Real changes publish the existing workspace sync event in the same transaction.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "initiativeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CorePatchInitiativeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update an initiative",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreInitiative"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/admin/workspaces/{wsId}/membersList members with workspace roles and team membership
Workspace admin only; wsId must equal the authenticated workspace. Includes each member teams array.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List members with workspace roles and team membership",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreWorkspaceMember"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/admin/workspaces/{wsId}/membersAdd a user to the current workspace
Workspace admin only; wsId must match the authenticated workspace. role is admin or member.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAddWorkspaceMemberRequest"
}
}
}
},
"responses": {
"201": {
"description": "Add a user to the current workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/admin/workspaces/{wsId}/members/candidateFind one active account by exact email for workspace membership
Workspace admin only; wsId must match the authenticated workspace. No full user directory or fuzzy search is exposed.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "email",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 255
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context; Bearer keys must match their bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Active account",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"name",
"email"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/admin/workspaces/{wsId}/members/{userId}Remove a workspace member
Workspace admin only; cannot remove self or the last workspace admin.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Remove a workspace member"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/admin/workspaces/{wsId}/members/{userId}Change a workspace member role
Workspace admin only. role is admin or member; cannot demote the last workspace admin.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreUpdateWorkspaceMemberRequest"
}
}
}
},
"responses": {
"200": {
"description": "Change a workspace member role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PUT/api/admin/workspaces/{wsId}/members/{userId}/teamsReplace a member team set
Workspace admin only; replaces the target member’s complete team membership set atomically. Empty teamIds clears all team memberships.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreSetMemberTeamsRequest"
}
}
}
},
"responses": {
"200": {
"description": "Replace a member team set",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWorkspaceMember"
}
}
}
},
"204": {
"description": "Team memberships replaced; no response body when the target member is not present in the caller-filtered member list."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/auth/loginCreate a session
Public endpoint. Requires X-Requested-With: XMLHttpRequest; invalid credentials return 401. Sets HttpOnly SameSite=Strict task_manager_session cookie.
鉴权
[]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreLoginRequest"
}
}
}
},
"responses": {
"200": {
"description": "Create a session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAuthContext"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/auth/logoutEnd the current session
Session-authenticated write; clears the session cookie.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"responses": {
"200": {
"description": "End the current session",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/auth/meGet current user context
Requires an interactive session; returns current user, workspace list and role memberships.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Get current user context",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAuthContext"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/auth/meUpdate current user profile
Fields are optional. timeZone may be null to clear; non-null timeZone must load as a valid IANA zone. Returns refreshed auth context.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreUpdateMeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update current user profile",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAuthContext"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/auth/passwordChange current password
Requires current password and a new password of at least 8 characters; rotates the session cookie.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreChangePasswordRequest"
}
}
}
},
"responses": {
"200": {
"description": "Change current password",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreOK"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/comments/{commentId}Delete a comment (author or workspace admin).
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/comments/{commentId}Update a comment (author only).
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.PatchCommentRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/comments/{commentId}/reactionsSet or clear the authenticated user reaction; collection is returned canonically.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SetReactionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.ReactionCollection"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/comments/{commentId}/resolutionSet the comment resolved state.
Requires exactly one boolean resolved field; returns the updated comment.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"resolved": {
"type": "boolean"
}
},
"required": [
"resolved"
]
}
}
}
},
"responses": {
"200": {
"description": "Updated comment with its current resolution state and provenance.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/customersList workspace customers.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Customer"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/customersCreate a workspace customer.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CreateCustomerRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Customer"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/cyclesList visible cycles
Returns cycles visible to the current workspace user.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Visible cycles.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreCycle"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/cycles/{cycleId}Delete a cycle
Admin-only; deletes cycle according to existing issue assignment handling.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "cycleId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete a cycle"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/cycles/{cycleId}Get cycle detail
Returns cycle data, progress, burndown and visible issues; burndown dates use the persisted team cycle timezone, not the viewer timezone.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "cycleId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get cycle detail",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCycleDetail"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/cycles/{cycleId}Update a cycle
Admin-only. Only name, startsOn and endsOn are accepted; fields are optional.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "cycleId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CorePatchCycleRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update a cycle",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCycle"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/favoritesList the current user workspace favorites.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FavoritesAPI.Favorite"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/favoritesCreate a favorite for an issue or project.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FavoritesAPI.CreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FavoritesAPI.Favorite"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/favorites/by-target/{targetType}/{targetId}Delete the current user favorite matching the target.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "targetType",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "targetId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/favorites/{favoriteId}Delete a favorite owned by the current user.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "favoriteId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/healthzCheck service health
Returns a static liveness response. This public endpoint exposes no instance configuration or secrets.
鉴权
[]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Service is reachable.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
}
},
"additionalProperties": false
}
}
}
}
}
}
GET/api/issue-link-sourcesList visible issue link sources
Returns unique, sorted sources from issue links visible to the current user in the active workspace. Private-team visibility is enforced.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Unique visible sources.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/issue-relations/{relationId}Delete an issue relation.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "relationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/insightsAggregate current issue insights
Aggregates the complete currently authorized issue set without pagination. Filters use the saved-view basic and advanced AST semantics; basic label values use OR semantics. Without from/to this returns only current-state distributions. Paired from/to dates additionally request real weekly creation events for the same current authorized/filter set, using Monday-start weeks in the effective user time zone. No history is inferred from current state or legacy created_at; incomplete coverage is explicitly marked. estimate is the sum of known estimates; estimatedCount distinguishes unestimated issues (null) from estimate 0. Multi-label issues may contribute to multiple label groups, so group counts may sum above total.count. Filters apply to current issue properties, not historical properties. Search matches title, identifier, and aliases, not description; the supplied search is not trimmed. Personal scopes (assigned/created/subscribed) include triage; includeTriage only changes ordinary scopes. Explicit basic statusIds also retain triage, matching issue list behavior. Time zone comes from the authenticated user's saved setting, then the X-Time-Zone request header; no query timeZone override is accepted. With from/to, completedHistory, cycleVelocity, processingTime and nonempty statusDwell additionally expose true observed transitions and durations; unknown history stays unknown. New cycle snapshots begin at migration 086, never backfilled from current assignment.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Time-Zone",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Fallback IANA timezone only when the authenticated user has no saved timezone; a saved timezone takes precedence. Invalid fallback values return 400. Defaults to UTC."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "scope",
"in": "query",
"description": "Defaults to workspace. team/project require scopeId; other scopes reject scopeId.",
"schema": {
"type": "string",
"enum": [
"workspace",
"team",
"project",
"assigned",
"created",
"subscribed"
],
"default": "workspace"
}
},
{
"name": "scopeId",
"in": "query",
"description": "Required only for scope=team or scope=project; must be valid UTF-8 and at most 64 bytes.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "filters",
"in": "query",
"description": "Saved-view filter JSON; defaults to {} and is limited to 24576 UTF-8 bytes. Strict AST validation is shared with saved-view matching.",
"schema": {
"type": "string",
"maxLength": 24576
}
},
{
"name": "search",
"in": "query",
"description": "Optional search string, at most 200 Unicode code points. Preserved as supplied; not trimmed.",
"schema": {
"type": "string",
"maxLength": 200
}
},
{
"name": "includeTriage",
"in": "query",
"description": "Optional literal true or false; defaults to false. Affects ordinary scopes only; assigned/created/subscribed scopes include triage regardless.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "hideSubIssues",
"in": "query",
"description": "Optional literal true or false; defaults to false.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "dimension",
"in": "query",
"description": "Grouping dimension; defaults to status.",
"schema": {
"type": "string",
"enum": [
"status",
"statusCategory",
"assignee",
"label",
"priority",
"team",
"cycle",
"project"
],
"default": "status"
}
},
{
"name": "from",
"in": "query",
"description": "Optional inclusive local date (YYYY-MM-DD) for weekly creation history. Requires to; the inclusive range is at most 366 calendar days. Both must be real dates and from <= to; all enclosing week dates must fit years 0001-9999. Omitting both preserves the original response shape.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "to",
"in": "query",
"description": "Inclusive local end date (YYYY-MM-DD); requires from. Current, future, pre-instrumentation and range-clipped weeks have complete=false, not proven zero counts.",
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "Current authorized issue distribution, with optional weekly creation history when from/to are supplied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.IssueInsights"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/issuesList workspace issues with optional filters and cursor pagination.
GET /issues preserves two response modes: without limit returns a plain Issue[]; with limit returns {items,nextCursor}. Filters use one singular query parameter containing comma-separated IDs/values (not repeated parameters). scope=team/project requires scopeId. include=filter_metadata adds authorized metadata. cursor requires limit. Without pagination, sort also accepts priority and due_date_asc; paginated sorting is limited to updated_desc or created_desc.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "scope",
"in": "query",
"schema": {
"type": "string",
"enum": [
"workspace",
"team",
"project",
"assigned",
"created",
"subscribed"
],
"default": "workspace"
},
"description": "workspace (default), team, project, assigned, created, or subscribed. team/project require scopeId."
},
{
"name": "scopeId",
"in": "query",
"schema": {
"type": "string"
},
"description": "Team ID when scope=team; project ID when scope=project."
},
{
"name": "priority",
"in": "query",
"description": "Comma-separated priority values: urgent,high,medium,low,none.",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"description": "Comma-separated workflow status IDs.",
"schema": {
"type": "string"
}
},
{
"name": "assignee",
"in": "query",
"description": "Comma-separated assignee user IDs.",
"schema": {
"type": "string"
}
},
{
"name": "team",
"in": "query",
"description": "Comma-separated team IDs.",
"schema": {
"type": "string"
}
},
{
"name": "project",
"in": "query",
"description": "Comma-separated project IDs.",
"schema": {
"type": "string"
}
},
{
"name": "label",
"in": "query",
"description": "Comma-separated leaf or group label IDs. Multiple values use AND semantics: every value must match; a group value matches an issue carrying any accessible leaf in that same team scope.",
"schema": {
"type": "string"
}
},
{
"name": "include",
"in": "query",
"schema": {
"type": "string",
"enum": [
"filter_metadata"
]
},
"description": "Only filter_metadata is accepted; adds authorized filter metadata fields to Issue results."
},
{
"name": "includeTriage",
"in": "query",
"schema": {
"type": "boolean"
},
"description": "Boolean; only literal true/false. Applies only when true."
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"description": "Optional; 1..100. Omit for legacy unpaginated Issue[] response."
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"maxLength": 512
},
"description": "Opaque base64url cursor; requires limit and must correspond to sort."
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"updated_desc",
"created_desc",
"priority",
"due_date_asc"
]
},
"description": "Without limit: updated_desc, created_desc, priority, or due_date_asc. With limit/cursor: only updated_desc or created_desc."
},
{
"name": "dueDate",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"overdue",
"today",
"this_week",
"this_month",
"no_date"
]
},
"description": "Optional relative-date filter: overdue,today,this_week,this_month,no_date; uses X-Time-Zone."
},
{
"name": "X-Time-Zone",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Fallback IANA timezone for relative dueDate filters only when the authenticated user has no saved timezone; otherwise the saved timezone wins and this header is ignored. Defaults to UTC. Invalid fallback values return 400."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "search",
"in": "query",
"description": "Case-insensitive literal title/current identifier/previous identifier substring. Description is not searched; SQL filters apply before cursor pagination.",
"schema": {
"type": "string",
"maxLength": 200
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items",
"nextCursor"
]
}
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issuesCreate an issue.
Workspace membership and private-team access are enforced by the server. labelIds accepts leaf IDs only (never group IDs); assignment requires a workspace-scoped or same-team leaf and at most one leaf from each group. Invalid group/scope is 400 label_invalid_group; multiple leaves from one group conflict with 409 label_group_conflict.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CreateIssueRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
}
}
},
"400": {
"description": "Invalid request; invalid label group/team/scope returns error.code label_invalid_group.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Labels from the same group cannot both be assigned (error.code: label_group_conflict).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/issues/{issueId}Delete an issue (creator or workspace admin).
Workspace membership and private-team access are enforced by the server. When labelIds is supplied, it replaces labels with leaf IDs only (never group IDs); assignment requires a workspace-scoped or same-team leaf and at most one leaf from each group. Invalid group/scope is 400 label_invalid_group; multiple leaves from one group conflict with 409 label_group_conflict.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}Get an issue.
Accepts the internal issue ID, current public identifier, or a historical identifier in the selected workspace. Returns the current identifier; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"filter_metadata"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/issues/{issueId}Update issue fields; nullable assignee/project/date/parent/cycle/estimate fields accept explicit null.
Workspace membership and private-team access are enforced by the server. When labelIds is supplied, it replaces labels with leaf IDs only (never group IDs); assignment requires a workspace-scoped or same-team leaf and at most one leaf from each group. labelChange is mutually exclusive with labelIds and is only valid with an actual team move; the server applies its add/remove intent to the locked current label set after normalizing labels for the destination team. removeId must be an accessible workspace or source-team leaf; addId must be assignable to the destination team. Invalid group/scope is 400 label_invalid_group; same-group conflicts in a replacement set are 409 label_group_conflict.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.PatchIssueRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
}
}
},
"400": {
"description": "Invalid request; invalid label group/team/scope returns error.code label_invalid_group.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Labels from the same group cannot both be assigned (error.code: label_group_conflict).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/activityList issue activity visible to the current user.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Activity"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/commentsList comments for an issue.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Comment"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issues/{issueId}/commentsCreate a comment on an issue.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CreateCommentRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/customer-requestsList customer requests for an issue.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.CustomerRequest"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issues/{issueId}/customer-requestsCreate an issue customer request.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CreateCustomerRequestForIssue"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CustomerRequest"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/issues/{issueId}/customer-requests/{requestId}Delete an issue customer request.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "requestId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/issues/{issueId}/cycleRemove an issue cycle assignment.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/cycleGet the current cycle relation for an issue.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CycleEnvelope"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/issues/{issueId}/cycleAssign an issue to a cycle.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SetCycleRequest"
}
}
}
},
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/linksList issue links.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Link"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issues/{issueId}/linksCreate an issue link.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CreateLinkRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Link"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/issues/{issueId}/links/{linkId}Delete an issue link.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "linkId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/milestoneGet the issue milestone (null when not assigned).
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/IssueAPI.ProjectMilestone"
}
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/issues/{issueId}/milestoneAssign or clear the milestone (milestoneId may be null).
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SetMilestoneRequest"
}
}
}
},
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/reactionsList issue reactions.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.ReactionCollection"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/issues/{issueId}/reactionsSet or clear the authenticated user reaction; collection is returned canonically.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SetReactionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.ReactionCollection"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/relationsList readable relations for an issue.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.IssueRelation"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issues/{issueId}/relationsCreate an issue relation.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.CreateRelationRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.IssueRelation"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/issues/{issueId}/reminderCancel the current user reminder.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/reminderGet the current user reminder time for the issue.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Reminder"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/issues/{issueId}/reminderSet the current user reminder time (future time, at most one year ahead).
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SetReminderRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Reminder"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issues/{issueId}/reorderReorder an issue in manual or priority order.
mode is manual|priority; placement is before|after|first|last. anchorIssueId is allowed only for before/after and required there by repository validation.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.ReorderRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issues/{issueId}/replayReplay an issue PATCH idempotently.
Uses the same partial-update fields and label validation as PATCH /issues/{issueId}; labelIds accepts leaf IDs only, requires workspace or same-team scope, and allows at most one leaf per group. labelChange is mutually exclusive with labelIds and is only valid with an actual team move; its normalized intent is included in the idempotency fingerprint. Invalid group/scope is 400 label_invalid_group; same-group conflicts return 409 label_group_conflict. Requires one Idempotency-Key header.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Exactly one valid idempotency key is required."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.PatchIssueRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
}
}
},
"400": {
"description": "Invalid request; invalid label group/team/scope returns error.code label_invalid_group.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Labels from the same group cannot both be assigned (error.code: label_group_conflict).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/issues/{issueId}/slaDelete issue SLA settings.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/slaGet issue SLA settings.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/IssueAPI.SLA"
}
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/issues/{issueId}/slaCreate or replace issue SLA settings.
Matches the existing handler contract; workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SLA"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SLA"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/sub-issuesList readable sub-issues.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/issues/{issueId}/subscribeUnsubscribe the current user from an issue.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/issues/{issueId}/subscribeSubscribe the current user to an issue.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/subscribersList issue subscribers.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.User"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/issues/{issueId}/subscribers/{userId}Set whether a workspace member subscribes to the issue.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SetSubscriberRequest"
}
}
}
},
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/issues/{issueId}/subscriptionGet current-user subscription and status notification preference.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.Subscription"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/issues/{issueId}/subscriptionSet current-user status notification preference.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IssueAPI.SetSubscriptionRequest"
}
}
}
},
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/labels/{labelId}Delete a label
Workspace admin only; soft-deletes the label. It is thereafter excluded from active label listings. A group with child labels, or any label still assigned to a live issue, is rejected with 409 label_in_use.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "labelId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete a label"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"description": "The label has children or is still assigned to a live issue (error.code: label_in_use).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreLabelErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/labels/{labelId}Update a label
Workspace admin only. Omitted fields are preserved; parentId/teamId null clears that field. Team scope/private-team access and group-parent scope are revalidated. Invalid group/scope is 400 label_invalid_group; reconfiguration conflicting with existing group assignments or group usage is 409 label_group_conflict or label_in_use.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "labelId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CorePatchLabelRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update a label",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreLabel"
}
}
}
},
"400": {
"description": "Invalid label input or invalid group/team scope (error.code: bad_request or label_invalid_group).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreLabelErrorEnvelope"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"description": "Label scope/group change conflicts with existing use (error.code: label_group_conflict or label_in_use).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreLabelErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/membersList current workspace members
Returns active member profiles for the current workspace.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List current workspace members",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreUser"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/my-issues/activityList filtered My Issues activity with cursor pagination.
filters is a JSON-encoded saved-view-compatible filter object. When filters is non-empty response includes timeZone; otherwise it is omitted.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 200
}
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 24576
},
"description": "One JSON-encoded saved-view IssueFilters object (decoded JSON length <=4096); supported keys include priorities,teamIds,labelIds,statusCategories,statusIds,assigneeIds,projectIds,dueDate,advanced. Repeated filters values are rejected."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 512
}
},
{
"name": "X-Time-Zone",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Fallback IANA timezone only when the authenticated user has no saved timezone; a saved timezone takes precedence and this header is ignored. Invalid fallback values return 400. Defaults to UTC."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyIssuesAPI.ActivityResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/my-issues/blockingList issue IDs blocking the current user.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/my-issues/current-cycleList current-cycle issue IDs for the current user.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Time-Zone",
"in": "header",
"required": false,
"description": "Fallback IANA timezone only when the authenticated user has no saved timezone; a saved timezone takes precedence and this header is ignored. Invalid fallback values return 400. Defaults to UTC.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/my-issues/display-defaultsGet My Issues display defaults.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyIssuesAPI.DisplayDefaults"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/my-issues/display-defaults/{scope}Replace display settings for one My Issues scope (workspace admin route).
scope is one of assigned, created, subscribed. Body must contain viewMode, groupBy, listSortBy, boardSortBy and display, with optional timelineScale (week/month/quarter); no other top-level keys are allowed; display keys are validated by handler.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "scope",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyIssuesAPI.DisplaySettings"
}
}
}
},
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/notificationsList notification groups with filtering and cursor pagination.
Always returns {items,nextCursor}; items are grouped by issue/project entity (each notification has groupCount), not a plain array. filter selects all/mentions/assigned/comments; status selects all/unread. filters/priorityFilters are JSON strings. limit defaults 50 (1..100); cursor is opaque and bound to ordering; include=issue_metadata adds metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "filter",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "all"
},
"description": "Recognized selectors: all,mentions,assigned,comments; other values are treated like all."
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "all"
},
"description": "Recognized selectors: all,unread; other values are treated like all."
},
{
"name": "search",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 100
}
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
},
"description": "JSON-encoded NotificationAPI.Filters object (one query value, max 4096 chars)."
},
{
"name": "priorityFilters",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
},
"description": "JSON-encoded NotificationAPI.PriorityFilters object (one query value, max 4096 chars)."
},
{
"name": "priorityTypes",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 256
},
"description": "Comma-separated priority-rule types: assignments,mentions,urgent,comments,status,reminders,subscriptions,sla,reactions,triage."
},
{
"name": "showSnoozed",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 512
}
},
{
"name": "ordering",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"latest",
"priority"
],
"default": "latest"
}
},
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"issue_metadata"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.ListResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/notifications/readDelete read notifications.
When undo=true, provide exactly one Idempotency-Key; the successful response is UndoAction, otherwise {ok:true}.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "undo",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"true"
]
},
"description": "Opt into undo snapshot; requires exactly one Idempotency-Key header."
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Required exactly once when undo=true."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/NotificationAPI.OK"
},
{
"$ref": "#/components/schemas/NotificationAPI.UndoAction"
}
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/notifications/read-allMark all eligible notifications read.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.OK"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/notifications/replayApply or replay one idempotent notification action.
operationId is an idempotency key. Allowed kind values: read, unread, delete, unsnooze, snooze; until is required only for snooze.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.ReplayRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.ReplayResult"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/notifications/undoRestore eligible notifications from a prior undo action.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.UndoRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.UndoResult"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/notifications/unread-countCount unread notification groups.
include=total adds totalCount; priorityTypes is comma-separated and priorityFilters is JSON-encoded.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "priorityTypes",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 256
}
},
{
"name": "priorityFilters",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 4096
},
"description": "JSON-encoded NotificationAPI.PriorityFilters object (one query value, max 4096 chars)."
},
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"total"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.CountResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/notifications/{notificationId}Delete a notification.
When undo=true, provide exactly one Idempotency-Key; the successful response is UndoAction, otherwise {ok:true}.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "notificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "undo",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"true"
]
},
"description": "Opt into undo snapshot; requires exactly one Idempotency-Key header."
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Required exactly once when undo=true."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/NotificationAPI.OK"
},
{
"$ref": "#/components/schemas/NotificationAPI.UndoAction"
}
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/notifications/{notificationId}Get the current readable notification group for an event.
Returns the current readable notification row for its whole issue/project group, with authorized issue/project/actor metadata; not the list envelope.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "notificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.Notification"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/notifications/{notificationId}/readMark notification read.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "notificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.OK"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/notifications/{notificationId}/snoozeSnooze a notification.
When undo=true, provide one Idempotency-Key; the successful response is UndoAction, otherwise {ok:true}.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "notificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "undo",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"true"
]
},
"description": "Opt into undo snapshot; requires exactly one Idempotency-Key header."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.SnoozeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/NotificationAPI.OK"
},
{
"$ref": "#/components/schemas/NotificationAPI.UndoAction"
}
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/notifications/{notificationId}/unreadMark notification unread.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "notificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.OK"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/notifications/{notificationId}/unsnoozeUnsnooze notification.
Matches the existing handler contract; identity and authorization follow the route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "notificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationAPI.OK"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/openapi.jsonGet the static OpenAPI contract
Public static API description. Contains no deployment-specific configuration or secrets.
鉴权
[]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "OpenAPI 3.0.3 document.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenAPIDocument"
}
}
}
}
}
}
GET/api/platform/notification-metricsGet process-local notification metrics snapshot.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.NotificationMetrics"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/platform/usersList active platform users.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformAPI.User"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/platform/usersCreate a platform user.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted. Account creation does not grant workspace membership. A duplicate email, including an inactive account's email, returns 409.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.CreateUserRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.User"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Email already in use.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/platform/users/{userId}Deactivate a platform user.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/platform/users/{userId}Update platform user fields.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.PatchUserRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.User"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/platform/users/{userId}/password/resetGenerate and set a temporary password (returned once).
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.PasswordResponse"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/platform/workspacesList all workspaces.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformAPI.Workspace"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/platform/workspaces/{wsId}/membersList members of a workspace.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformAPI.WorkspaceMember"
}
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/platform/workspaces/{wsId}/membersAdd a user to a workspace.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.AddMemberRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.OK"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"$ref": "#/components/responses/Error"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/platform/workspaces/{wsId}/members/{userId}Remove a user from a workspace.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/platform/workspaces/{wsId}/members/{userId}Update a workspace member role.
Platform-admin-only route; requires an authenticated session cookie. Workspace Bearer API Keys are not accepted.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "wsId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.RoleRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformAPI.OK"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/project-milestonesList milestone directories for projects
Returns the active milestone directory for the requested projects in the current workspace. Issue counts are omitted.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectIds",
"in": "query",
"required": true,
"description": "One comma-separated query value; 1–100 unique project IDs, total value length at most 4096. Repeated projectIds parameters are invalid.",
"schema": {
"type": "string",
"maxLength": 4096
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Milestones grouped by project and ordered by sortOrder, name, then id; count fields are omitted.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectMilestone"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projectsList visible projects
Returns projects visible to the current workspace user.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List visible projects",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreProject"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projectsCreate a project
Creates a project. teamIds must contain at least one team in the workspace.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCreateProjectRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create a project",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProject"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/projects/{projectId}Delete a project
Only project creator or workspace admin may delete; workspace/private-team visibility still applies.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete a project"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projects/{projectId}Get a project
Returns the project if it is visible to the current workspace user.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get a project",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProject"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/projects/{projectId}Update project fields
Omitted fields are preserved. Null clears nullable lead/date fields; at least one project team must remain.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CorePatchProjectRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update project fields",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProject"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projects/{projectId}/reorderReorder a project
Atomically moves a visible project within or between status lanes, including any required rank rebalance. before/after require a distinct visible anchor in the target status; first/last do not accept an anchor. Requires workspace write permission and a Bearer API Key with write scope.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreReorderProjectRequest"
}
}
}
},
"responses": {
"204": {
"description": "Project reordered."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projects/{projectId}/commentsList project comments with cursor pagination.
Returns items, nullable nextCursor, and canCreate. Empty collection is represented by items: [].
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Opaque cursor from nextCursor; omit for first page."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Page"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/projects/{projectId}/commentsCreate an idempotent project comment.
Requires exactly one Idempotency-Key header of 32 lowercase hexadecimal characters; body is required, maximum 1 MiB.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
},
"description": "Exactly 32 lowercase hexadecimal characters; required for creation."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.CreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/projects/{projectId}/comments/{commentId}Delete a project comment.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/projects/{projectId}/comments/{commentId}Get a project comment.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/projects/{projectId}/comments/{commentId}Edit a project comment.
The request body is {body}; unknown properties are rejected.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.CreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/projects/{projectId}/membersList visible members of a project
Returns active workspace users belonging to at least one project team visible to the caller; private-team access filters membership. Parent project access is checked by PrivateTeamAccess.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List visible members of a project",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreUser"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projects/{projectId}/milestonesList active project milestones with visible issue counts
Returns active milestones for a workspace-authorized project. Issue counts exclude deleted or private-team issues the current caller cannot see. Sorting is deterministic: sortOrder, name, id.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Milestones ordered by sortOrder, name, then id; this project-specific listing includes caller-visible issueCount and completedIssueCount.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectMilestone"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projects/{projectId}/milestonesCreate a project milestone
Creates a milestone at the end of the active order. targetDate accepts null or a YYYY-MM-DD calendar date in years 1000–9999.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "JSON body is limited to 32 KiB. targetDate is optional and nullable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProjectMilestoneRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created milestone. Count fields are omitted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectMilestone"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projects/{projectId}/milestones/reorderReplace the complete active milestone order
The write is serialized with workspace/project milestone changes. A stale or incomplete active set fails with 409 milestones_changed; no partial reorder is applied.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "JSON body is limited to 32 KiB. The list must represent the complete active collection, not a partial reorder.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReorderProjectMilestonesRequest"
}
}
}
},
"responses": {
"204": {
"description": "Order replaced, or already current."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"description": "The supplied IDs are not the exact current active milestone set. Error code is milestones_changed; reload then retry.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MilestonesChangedError"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/projects/{projectId}/milestones/{milestoneId}Delete a project milestone
Deletes the active milestone and follows existing issue-assignment handling.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "milestoneId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Milestone deleted."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/projects/{projectId}/milestones/{milestoneId}Partially update milestone name and target date
Only name and targetDate can be changed. An empty object is invalid; null is not valid for name.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "milestoneId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "At least one field is required. Omitted fields are unchanged; targetDate:null clears the date. Unknown fields are rejected.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchProjectMilestoneRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated milestone; count fields are omitted.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectMilestone"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projects/{projectId}/notification-subscriptionGet project notification preferences
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get project notification preferences",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectNotificationSubscription"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PUT/api/projects/{projectId}/notification-subscriptionReplace project notification preferences
All six boolean preferences are required; unknown properties are rejected.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectNotificationSubscriptionRequest"
}
}
}
},
"responses": {
"204": {
"description": "Replace project notification preferences"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/projects/{projectId}/reminderCancel current-user project reminder.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/projects/{projectId}/reminderGet current-user project reminder.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectReminderAPI.Reminder"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/projects/{projectId}/reminderSet current-user project reminder (future time, at most one year ahead).
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectReminderAPI.SetRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectReminderAPI.Reminder"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/projects/{projectId}/updatesList project updates
Cursor-paginated update stream; includes canCreate and firstUpdate.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List project updates",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectUpdatePage"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projects/{projectId}/updatesCreate project update
Requires body and health; create requires Idempotency-Key (one lowercase 32-hex value).
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "Exactly one lowercase 32-character hexadecimal operation ID.",
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectUpdateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create project update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectUpdate"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/projects/{projectId}/updates/{updateId}Delete project update
The author may delete; a workspace admin may delete only when current API Key scope also authorizes admin (session admins follow the same role check).
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete project update"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projects/{projectId}/updates/{updateId}Get project update
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get project update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectUpdate"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/projects/{projectId}/updates/{updateId}Update project update
Only the update author may edit. Body and health are both required; unknown fields are rejected.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update project update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreProjectUpdate"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projects/{projectId}/updates/{updateId}/commentsList project comments with cursor pagination.
Returns items, nullable nextCursor, and canCreate. Empty collection is represented by items: [].
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Opaque cursor from nextCursor; omit for first page."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Page"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/projects/{projectId}/updates/{updateId}/commentsCreate an idempotent project comment.
Requires exactly one Idempotency-Key header of 32 lowercase hexadecimal characters; body is required, maximum 1 MiB.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
},
"description": "Exactly 32 lowercase hexadecimal characters; required for creation."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.CreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/projects/{projectId}/updates/{updateId}/comments/{commentId}Delete a project comment.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Successful response."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/projects/{projectId}/updates/{updateId}/comments/{commentId}Get a project comment.
Matches the existing handler contract; authorization follows route security metadata.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/projects/{projectId}/updates/{updateId}/comments/{commentId}Edit a project comment.
The request body is {body}; unknown properties are rejected.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "updateId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "commentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.CreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectCommentAPI.Comment"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Request conflicts with current resource state or an idempotency record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/saved-view-issue-subscriptionsList current user active saved-view subscriptions
Only entries with at least one notification enabled; only views still visible to the current member are returned. Project-directory views are excluded because they do not participate in issue notifications.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List current user active saved-view subscriptions",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreSavedViewIssueSubscriptionEntry"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/saved-viewsList saved views in a scope
scope_kind defaults to workspace and scope_id defaults to empty. For scope_kind=projects, an empty scope_id lists workspace project-directory views and a team ID lists that team's views; the singular project scope remains a project-specific issue view. Private-team access is enforced. Personal views are visible to their creator; workspace-visible views are shared with authorized workspace members. Results sorted by name.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "scope_kind",
"in": "query",
"required": false,
"description": "workspace, my, team, project (project-scoped issue view), or projects (project directory).",
"schema": {
"type": "string",
"enum": [
"workspace",
"my",
"team",
"project",
"projects"
],
"default": "workspace"
}
},
{
"name": "scope_id",
"in": "query",
"required": false,
"description": "Must be empty for workspace and my scopes. For projects, empty means workspace-wide and a team ID means team-scoped. Required for team and project issue-view scopes.",
"schema": {
"type": "string",
"default": ""
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List saved views in a scope",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreSavedView"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/saved-viewsCreate a saved view
Creates a personal view unless visibility=workspace. The complete JSON request body is limited to 64 KiB; oversized bodies return 400 bad_request. For scopeKind=projects, scopeId may be empty for workspace-wide views or a team ID for team-scoped views; filters/display use the project-directory schemas. Team-scoped filters are pinned to that team and reject other-team conditions; team grouping and roadmap layout are not supported. Each raw filters/display JSON value is independently capped at 64 KiB before parsing, with decoded budgets unchanged. Project-directory display defaults to list/none. The singular project scope remains an issue view. Scope entity must exist in the active workspace and be readable; schema-invalid filters return 400.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCreateSavedViewRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create a saved view",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreSavedView"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/saved-views/{viewId}Delete a saved view
Creator only.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "viewId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete a saved view"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/saved-views/{viewId}Update a saved view
Creator only. Name is required; omitted filters/display reset to empty objects. The complete JSON request body is limited to 64 KiB; oversized bodies return 400 bad_request. Project-directory filters/display use their independent schemas; each raw filters/display JSON value is independently capped at 64 KiB before parsing, with decoded budgets unchanged; omitted project display normalizes to viewMode=list and groupBy=none. Scope and visibility cannot be changed by this route.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "viewId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreUpdateSavedViewRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update a saved view",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreSavedView"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/saved-views/{viewId}/issue-subscriptionGet current user saved-view issue subscription
Returns all false/empty defaults when no subscription row exists. Project-directory views cannot have issue subscriptions; this read endpoint remains available for existing rows/defaults.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "viewId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get current user saved-view issue subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreSavedViewIssueSubscription"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PUT/api/saved-views/{viewId}/issue-subscriptionSet current user saved-view issue subscription
All three notification booleans required. Project-directory views reject any enabled notification; disabling all removes a legacy subscription row. Enabled my-scope subscriptions require contextScope assigned/created/subscribed/activity; other scopes require empty contextScope. Disabling all removes the subscription and is permitted even if a scope/filter became invalid. The saved timezone of the authenticated user/Key takes precedence; X-Time-Zone is used only if no saved timezone exists, then UTC.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "viewId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Time-Zone",
"in": "header",
"required": false,
"description": "Fallback timezone only when the authenticated principal has no saved timezone; defaults to UTC.",
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreSavedViewIssueSubscriptionRequest"
}
}
}
},
"responses": {
"204": {
"description": "Set current user saved-view issue subscription"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/setup/bootstrapInitialize the first user and workspace
Public setup endpoint; succeeds only once. Creates the first platform-admin user, workspace and admin membership, then sets a session cookie. Slug must match ^[a-z0-9-]{2,32}$. This route does not apply the RequestedWith middleware.
鉴权
[]
请求与响应
{
"parameters": [],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreBootstrapRequest"
}
}
}
},
"responses": {
"201": {
"description": "Initialize the first user and workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAuthContext"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
},
"503": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/setup/statusCheck whether initial bootstrap is needed
Public; needsBootstrap is true only when the users table is empty.
鉴权
[]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Check whether initial bootstrap is needed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreSetupStatus"
}
}
}
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/statusesList visible workspace statuses
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List visible workspace statuses",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreStatus"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/statuses/{statusId}Delete a status
Workspace admin only; active issue references cause conflict.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "statusId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete a status"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/statuses/{statusId}Update a status
Workspace admin only. position must be a nonnegative integer; systemKey is read-only.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "statusId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CorePatchStatusRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update a status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreStatus"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/sync/workspaceUpgrade a session-cookie connection to the workspace WebSocket stream
Upgrades the session-cookie connection to a WebSocket (101); this is not SSE. Bearer API Keys are not accepted. Requires an active session, workspaceId, a same-origin Origin, and a valid WebSocket handshake. The connection periodically rechecks workspace authorization; the stream sends notification/issue version events and ping/resync signals.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "workspaceId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 64
}
},
{
"name": "Upgrade",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"websocket"
]
}
},
{
"name": "Connection",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"Upgrade"
]
}
},
{
"name": "Origin",
"in": "header",
"required": true,
"description": "Must match the request host; HTTPS is accepted, and HTTP is allowed only for localhost/127.0.0.1.",
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "Sec-WebSocket-Version",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"13"
]
}
},
{
"name": "Sec-WebSocket-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 24,
"maxLength": 24
}
}
],
"responses": {
"101": {
"description": "WebSocket protocol upgraded; server frames carry notification/issue version events or ping/resync signals."
},
"400": {
"description": "Invalid WebSocket handshake; connection is rejected.",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"description": "Workspace membership or same-origin policy rejected the connection; no response body is sent."
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teamsList visible teams
Returns teams visible to the current workspace user; private-team visibility is enforced.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List visible teams",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreTeam"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/teamsCreate a team
Workspace admin only. identifier must be 1–8 uppercase ASCII letters and is reserved per workspace, including deleted teams; duplicates return 409 team_identifier_taken.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCreateTeamRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create a team",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTeam"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/teams/{teamId}Delete a team
Workspace admin only; returns conflict if active issues remain.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Delete a team"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}Get a visible team
Private-team membership is enforced independently of workspace admin role.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get a visible team",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTeam"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/teams/{teamId}Update a team
Workspace admin only. At least one field required; defaultStatusId can be null to clear; identifier remains uppercase 1–8 letters and must be unique per workspace (409 team_identifier_taken).
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CorePatchTeamRequest"
}
}
}
},
"responses": {
"200": {
"description": "Update a team",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTeam"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}/cycle-settingsGet cycle settings
Returns the current team settings; timeZone is the persisted team zone (or UTC before initial configuration). An untouched timeZone should be omitted from PATCH so the server can initialize it from the account or request header.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get cycle settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCycleSettings"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/teams/{teamId}/cycle-settingsReplace cycle settings
Admin-only. All five settings fields are decoded; server computes timeZone from the current user timezone and returns it.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CorePatchCycleSettingsRequest"
}
}
}
},
"responses": {
"200": {
"description": "Replace cycle settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCycleSettings"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}/cyclesList visible cycles for a team
Returns cycles in the team visible to the current workspace user.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Cycles ordered by the repository query.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreCycle"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/teams/{teamId}/cyclesCreate a team cycle
Admin-only. The name may be omitted; startsOn and endsOn are required calendar dates.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCreateCycleRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created cycle.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCycle"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}/cycles/overviewList cycle summaries
Returns visible team cycles with aggregate progress.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List cycle summaries",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreCycleSummary"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}/issue-subscriptionGet current user team issue subscription
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get current user team issue subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTeamIssueSubscription"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PUT/api/teams/{teamId}/issue-subscriptionSet current user team issue subscription
Body requires explicit subscribed boolean.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreBoolRequest"
}
}
}
},
"responses": {
"204": {
"description": "Set current user team issue subscription"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}/membersList visible team members
Returns user objects for the team; private-team access applies.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List visible team members",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreTeamUser"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/teams/{teamId}/membersAdd a workspace member to a team
Workspace admin only. User must already be a member of this workspace. Returns the updated team member array.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTeamMemberRequest"
}
}
}
},
"responses": {
"200": {
"description": "Add a workspace member to a team",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreTeamUser"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/teams/{teamId}/members/{userId}Remove a member from a team
Workspace admin only.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "userId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Remove a member from a team"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}/statusesList visible statuses for a team
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List visible statuses for a team",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreStatus"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/teams/{teamId}/statusesCreate a workflow status
Workspace admin only. category is triage/backlog/unstarted/started/completed/cancelled; duplicate is reserved and systemKey cannot be set.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCreateStatusRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create a workflow status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreStatus"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/teams/{teamId}/triageGet current user team triage preferences
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get current user team triage preferences",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTeamTriage"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PUT/api/teams/{teamId}/triage/settingsConfigure team triage acceptance status
Workspace administrators with current team access only. Null selects the first Backlog status by position and binary ID. An explicit status must belong to this team and have backlog or unstarted category.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"acceptStatusId"
],
"properties": {
"acceptStatusId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 64
}
}
}
}
}
},
"responses": {
"204": {
"description": "Configuration saved atomically; unchanged settings are a no-op."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/issues/{issueId}/triageProcess one triage issue
Online-only atomic accept, reject, duplicate or transfer. Current issue edit access is required. Expected team/status must still match a Triage issue; otherwise 409 triage_conflict. Accept resolves team acceptance configuration; unavailable configuration returns 409 triage_accept_status_unavailable. Reject uses the first canceled status. Duplicate requires targetIssueId and preserves the original issue. Transfer requires another accessible targetTeamId and uses its first Triage status with existing team-move rules. Fields unrelated to the selected action are rejected. Same Idempotency-Key with a different payload returns 409 idempotency_conflict; retries reauthorize and return current data.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "32 hexadecimal digits, reused for an unchanged request after uncertain network results.",
"schema": {
"type": "string",
"pattern": "^[0-9a-fA-F]{32}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"action",
"expectedTeamId",
"expectedStatusId"
],
"properties": {
"action": {
"type": "string",
"enum": [
"accept",
"reject",
"duplicate",
"transfer"
]
},
"expectedTeamId": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"expectedStatusId": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"targetIssueId": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Required only for duplicate."
},
"targetTeamId": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Required only for transfer."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Current authorized issue after the decision or an idempotent replay.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreIssue"
}
}
}
},
"400": {
"description": "Invalid request; invalid label group/team/scope returns error.code label_invalid_group.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PUT/api/teams/{teamId}/triage/responsibilityReplace team triage responsibility users
Workspace admin only. User IDs are a complete replacement; maximum 100, each at most 32 characters.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTeamTriageResponsibilityRequest"
}
}
}
},
"responses": {
"204": {
"description": "Replace team triage responsibility users"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PUT/api/teams/{teamId}/triage/subscriptionSet current user team triage subscription
Body requires explicit subscribed boolean.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "teamId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreBoolRequest"
}
}
}
},
"responses": {
"204": {
"description": "Set current user team triage subscription"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/users/me/api-keysGET /api/users/me/api-keys
Session-only API Key management. Keys are personal and bound to the active workspace. Plaintext is returned only by creation; list and later reads never return it.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Current user keys in the active workspace.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/APIKey"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/users/me/api-keysPOST /api/users/me/api-keys
Session-only API Key management. Keys are personal and bound to the active workspace. Plaintext is returned only by creation; list and later reads never return it.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAPIKeyRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created key and one-time plaintext token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatedAPIKey"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
DELETE/api/users/me/api-keys/{keyId}DELETE /api/users/me/api-keys/{keyId}
Session-only operation on a key owned by the current user in the active workspace. Revocation is permanent; revoked keys remain listed with revokedAt and cannot authenticate.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "keyId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Key revoked."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/users/me/api-keys/{keyId}PATCH /api/users/me/api-keys/{keyId}
Session-only operation on a key owned by the current user in the active workspace. Revocation is permanent; revoked keys remain listed with revokedAt and cannot authenticate.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "keyId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenameAPIKeyRequest"
}
}
}
},
"responses": {
"204": {
"description": "Key renamed."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/users/me/notification-settingsGet account notification preferences
Returns the current session user preferences and server-supported delivery channel capabilities.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Preferences and available channels.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationSettingsResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/users/me/notification-settingsUpdate account notification preferences
Session-only partial update. Unknown fields, null values, empty patches, and unsupported channels/categories are rejected. Requires X-Requested-With: XMLHttpRequest.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationSettingsPatch"
}
}
}
},
"responses": {
"200": {
"description": "Updated preferences and available channels.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationSettingsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/users/me/subscribed-issue-idsList issue IDs subscribed to by the session user
Returns issue identifiers across the current user account; this account-wide endpoint has no workspace context and is session-only.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [],
"responses": {
"200": {
"description": "Subscribed issue IDs; empty result is an empty array.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscribedIssueIDs"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/workspaceGet current workspace
Requires workspace session or Bearer key with read scope.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Get current workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWorkspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/workspaceRename current workspace and slug
Workspace admin only (API Key requires admin scope). Both fields required; slug pattern ^[a-z0-9-]{2,32}$.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWorkspaceRequest"
}
}
}
},
"responses": {
"200": {
"description": "Rename current workspace and slug",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWorkspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/workspacesCreate a workspace
Requires an interactive session but no workspace context; the caller becomes workspace admin.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": true,
"description": "Required for this session-cookie write: XMLHttpRequest. Bearer API Keys are not accepted on this route.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWorkspaceRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create a workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWorkspace"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/workspaces/by-slug/{slug}Get a workspace by slug
Requires a session. Members and platform admins may read; inaccessible and missing slugs both return 404 to prevent enumeration.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Get a workspace by slug",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWorkspace"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/workspaces/{workspaceId}/labelsList labels in current workspace
workspaceId must equal the authenticated workspace; mismatch returns 404. Workspace-scoped labels are listed for all members; team-scoped labels are included only when the current member can access that team, including private-team membership rules.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "workspaceId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List labels in current workspace",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreLabel"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/workspaces/{workspaceId}/labelsCreate a workspace label
Workspace admin only; workspaceId must equal the authenticated workspace. Labels may be workspace-scoped or scoped to an accessible team. A group is a single-level container: it cannot itself have a parent, and a leaf parent must be a group with the same workspace/team scope.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "workspaceId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreCreateWorkspaceLabelRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create a workspace label",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreLabel"
}
}
}
},
"400": {
"description": "Invalid label input or invalid group/team scope (error.code: bad_request or label_invalid_group).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreLabelErrorEnvelope"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/trashList visible deleted issues and projects
Returns only trash visible to the current workspace member under existing private-team rules. type filters to issue or project; q searches visible titles and issue identifiers (at most 256 bytes); limit defaults to 50 and is 1..100 when supplied; cursor is opaque (at most 1024 bytes). Entries are ordered by deletedAt descending, then type ascending, then ID ascending. totalCount and revision cover the viewer’s complete visible trash, independent of type, q, pagination, and limit. deletedBy is null when historical actor data is unavailable; the server does not infer it. Trash for soft-deleted teams remains listable when otherwise visible, but cannot be restored.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Required workspace context. For Bearer API Keys, it must match the key-bound workspace."
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"issue",
"project"
]
}
},
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Visible trash page; totalCount and revision describe the viewer’s complete visible trash snapshot, independent of type, q, cursor, and limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTrashPage"
}
}
}
},
"400": {
"description": "Invalid query parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The trash changed since the cursor snapshot was created (error.code: trash_changed).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTrashConflictErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/trash/issues/{issueId}/restoreRestore a deleted issue
Restores an issue only for its creator or a currently authorized workspace admin, subject to the existing platform-admin exception and private-team boundary. A write-scoped API Key may restore its owner's own item; restoring another user's item requires admin scope and the Key owner to remain a workspace or platform admin (write scope alone is insufficient). Repeated restore of an already-restored item is an idempotent no-op and creates no event. An item in a soft-deleted team returns trash_restore_conflict.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for session-cookie writes; not required for Bearer API Key requests."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Required workspace context. For Bearer API Keys, it must match the key-bound workspace."
}
],
"responses": {
"204": {
"description": "Completed; no response body."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Trash item not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Restore is no longer valid because a required parent, project, team, or status is unavailable (error.code: trash_restore_conflict).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTrashConflictErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/trash/projects/{projectId}/restoreRestore a deleted project
Restores a project only for its creator or a currently authorized workspace admin, subject to the existing platform-admin exception and private-team boundary. A write-scoped API Key may restore its owner's own item; restoring another user's item requires admin scope and the Key owner to remain a workspace or platform admin (write scope alone is insufficient). Repeated restore of an already-restored item is an idempotent no-op and creates no event. An item whose required team is soft-deleted returns trash_restore_conflict.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for session-cookie writes; not required for Bearer API Key requests."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Required workspace context. For Bearer API Keys, it must match the key-bound workspace."
}
],
"responses": {
"204": {
"description": "Completed; no response body."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Trash item not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Restore is no longer valid because a required parent, project, team, or status is unavailable (error.code: trash_restore_conflict).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTrashConflictErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/trash/emptyPermanently empty the workspace trash
Requires the actor to remain a workspace admin and the API Key to have admin scope, subject to the existing platform-admin exception. Permanently deletes the visible workspace trash only when the supplied revision matches the complete current trash snapshot; a changed snapshot returns trash_changed (409), not a count-only comparison. Unsafe dependency cleanup returns trash_dependency_conflict (409). No scheduled cleanup or single-item permanent-delete endpoint is provided.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for session-cookie writes; not required for Bearer API Key requests."
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Required workspace context. For Bearer API Keys, it must match the key-bound workspace."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreEmptyTrashRequest"
}
}
},
"description": "Exactly one JSON object with revision; body is limited to 4096 bytes and unknown fields are rejected."
},
"responses": {
"204": {
"description": "Completed; no response body."
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Current workspace admin authorization required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "The visible trash snapshot changed (trash_changed), or a dependency cannot be safely handled (trash_dependency_conflict).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreTrashConflictErrorEnvelope"
}
}
}
},
"413": {
"description": "Request body exceeds 4096 bytes (error.code: request_too_large).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/webhooksList workspace webhooks
Lists active webhook configurations for the workspace. The response contains no signing secret or delivery payload. enabled is false when the webhook encryption key is not configured. Requires a current workspace admin or the existing platform-admin exception.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Workspace context; must match the workspace bound to a Bearer API Key."
}
],
"responses": {
"200": {
"description": "Webhook feature availability and configurations; secrets are never returned by list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/webhooksCreate a workspace webhook
Creates a webhook configuration. The signing secret is generated and returned only in this response; the stored secret is encrypted. URL destinations must use HTTPS and resolve only to public routable addresses. Requires a current workspace admin or the existing platform-admin exception. See CoreWebhookEventPayload for the outbound request body.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Workspace context; must match the workspace bound to a Bearer API Key."
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for session-cookie writes; not required for Bearer API Key requests."
}
],
"requestBody": {
"required": true,
"description": "Exactly url and events; body is limited to 16 KiB and unknown or duplicate fields are rejected.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookInput"
}
}
}
},
"responses": {
"201": {
"description": "Created webhook and its one-time signing secret.",
"headers": {
"Cache-Control": {
"required": true,
"description": "The secret-bearing response is not cacheable.",
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookSecretResponse"
}
}
}
},
"400": {
"description": "Invalid request body or configuration (error.code: bad_request).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
},
"503": {
"description": "Webhook secret encryption is unavailable (error.code: webhook_unavailable).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
PATCH/api/webhooks/{webhookId}Replace a webhook configuration and signing secret
Replaces the complete URL/events configuration only if If-Match equals the current revision. Send the positive decimal revision in double quotes (for example, If-Match: "1"); stale revisions are never retried or overwritten automatically. On success, generates a new signing secret, increments revision, and records the current administrator as configuredById. The new secret is returned only in this response; older pending deliveries are suppressed and deliveries on the previous revision cannot be replayed. Destination validation enforces HTTPS and public-network restrictions.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 32,
"maxLength": 32,
"pattern": "^[0-9a-f]{32}$"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Workspace context; must match the workspace bound to a Bearer API Key."
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[1-9][0-9]*\"$",
"example": "\"1\""
},
"description": "Required optimistic concurrency precondition: the current positive decimal webhook revision, wrapped in double quotes. Missing or malformed values return 400 bad_request; a non-current revision returns 409 webhook_changed. The server never retries the update against a newer revision."
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for session-cookie writes; not required for Bearer API Key requests."
}
],
"requestBody": {
"required": true,
"description": "Exactly url and events; body is limited to 16 KiB and unknown or duplicate fields are rejected.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookInput"
}
}
}
},
"responses": {
"200": {
"description": "Updated webhook and its new one-time signing secret.",
"headers": {
"Cache-Control": {
"required": true,
"description": "The secret-bearing response is not cacheable.",
"schema": {
"type": "string",
"enum": [
"no-store"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookSecretResponse"
}
}
}
},
"400": {
"description": "Invalid request body or configuration (error.code: bad_request).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"description": "Webhook not found in the current workspace.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Webhook revision cannot be advanced (error.code: webhook_changed).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookChangedErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
},
"503": {
"description": "Webhook secret encryption is unavailable (error.code: webhook_unavailable).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/webhooks/{webhookId}Delete a workspace webhook
Soft-deletes the webhook and suppresses its pending deliveries. Requires a current workspace admin or the existing platform-admin exception.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 32,
"maxLength": 32,
"pattern": "^[0-9a-f]{32}$"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Workspace context; must match the workspace bound to a Bearer API Key."
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for session-cookie writes; not required for Bearer API Key requests."
}
],
"responses": {
"204": {
"description": "Deleted; no response body."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"description": "Webhook not found in the current workspace.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/webhooks/{webhookId}/deliveriesList webhook deliveries
Returns visible delivery metadata without signing keys or payloads, ordered by createdAt descending then ID descending. Each delivery contains at most the latest 20 attempts, ordered by attempt number descending. Private-team delivery records are filtered by current viewer access. Requires a current workspace admin or the existing platform-admin exception.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 32,
"maxLength": 32,
"pattern": "^[0-9a-f]{32}$"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Workspace context; must match the workspace bound to a Bearer API Key."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 1024
},
"description": "Opaque page cursor scoped to this workspace and webhook; maximum 1024 bytes."
}
],
"responses": {
"200": {
"description": "Visible delivery page; no secret or payload is included.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookDeliveryPage"
}
}
}
},
"400": {
"description": "Invalid limit or cursor (error.code: bad_request).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"description": "Webhook not found in the current workspace.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/webhooks/{webhookId}/deliveries/{deliveryId}/replayReplay a webhook delivery
Queues a new attempt only for an eligible delivered/failed delivery at the current webhook revision when the current actor and original configurer remain authorized for its frozen teams. A current-revision pending/processing delivery returns webhook_busy; deleted or stale-revision deliveries return webhook_changed. The replay operation does not return delivery payload or signing secret.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "webhookId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 32,
"maxLength": 32,
"pattern": "^[0-9a-f]{32}$"
}
},
{
"name": "deliveryId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 32,
"maxLength": 32,
"pattern": "^[0-9a-f]{32}$"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1
},
"description": "Workspace context; must match the workspace bound to a Bearer API Key."
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
},
"description": "Required for session-cookie writes; not required for Bearer API Key requests."
}
],
"responses": {
"204": {
"description": "Replay queued; no response body."
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"description": "Delivery or webhook not found or not visible to the current actor.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Webhook configuration changed (webhook_changed) or a delivery is already pending/running (webhook_busy).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreWebhookConflictErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/issues/{issueId}/attachmentsList attachments bound to an issue.
Returns only bound attachments visible with the issue; commentId identifies attachments first attached through a comment. Workspace membership and private-team access are enforced by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "issueId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Bound attachments for the issue.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreAttachment"
}
}
}
}
},
"400": {
"description": "Invalid request metadata or parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/attachments/capabilitiesGet attachment upload capabilities.
Workspace-scoped capabilities for direct attachment uploads. enabled=false means uploads are unavailable; no credentials are returned by this endpoint.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Current upload limits and accepted MIME types.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAttachmentCapabilities"
}
}
}
},
"400": {
"description": "Invalid request metadata or parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/attachments/uploadsCreate a pending attachment upload.
Creates attachment metadata and returns a short-lived signed POST target. upload.fields may contain short-lived form credentials needed for that upload; the long-lived storage signing secret is never returned. Issue/comment visibility is checked by the server.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAttachmentUploadRequest"
}
}
}
},
"responses": {
"201": {
"description": "Pending attachment and short-lived direct upload instructions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAttachmentUploadResponse"
}
}
}
},
"400": {
"description": "Invalid attachment metadata (error.code: bad_request).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"502": {
"description": "Object storage SDK failure (error.code: internal_error).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Attachment storage is unavailable (error.code: attachment_unavailable).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
POST/api/attachments/{attachmentId}/completeComplete a pending attachment upload.
Verifies the uploaded object and marks the attachment ready. Expired upload instructions return 409 attachment_expired; missing or not-visible attachments return 404.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "attachmentId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAttachmentCompleteRequest"
}
}
}
},
"responses": {
"200": {
"description": "Verified attachment metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAttachment"
}
}
}
},
"400": {
"description": "Invalid completion request (error.code: bad_request).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"409": {
"description": "Upload has expired (error.code: attachment_expired).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"502": {
"description": "Object storage SDK failure (error.code: internal_error).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Attachment storage is unavailable (error.code: attachment_unavailable).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
DELETE/api/attachments/{attachmentId}Cancel an unbound draft attachment.
Deletes only a pending draft uploaded by the current user and not yet bound to an issue or comment. Other or invisible attachments are reported as not found.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "attachmentId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"204": {
"description": "Draft attachment canceled."
},
"400": {
"description": "Invalid request metadata or parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Attachment storage is unavailable (error.code: attachment_unavailable).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/attachments/{attachmentId}/downloadGet a short-lived attachment download URL.
Returns a private, short-lived URL for a ready or bound attachment visible to the current user. The URL is a bearer credential and must be treated as sensitive.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "attachmentId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Short-lived private download URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoreAttachmentDownload"
}
}
}
},
"400": {
"description": "Invalid request metadata or parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"502": {
"description": "Object storage SDK failure (error.code: internal_error).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Attachment storage is unavailable (error.code: attachment_unavailable).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/attachments/{attachmentId}/contentRedirect to private attachment content.
Session-only content route; it does not accept API Keys and does not require X-Workspace-Id. The server checks current session visibility and redirects to a private short-lived object URL. Images are served inline; other files are served as attachments.
鉴权
[
{
"SessionCookie": []
}
]
请求与响应
{
"parameters": [
{
"name": "attachmentId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"302": {
"description": "Redirect to private short-lived content.",
"headers": {
"Location": {
"description": "Private temporary object URL.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
},
"400": {
"description": "Invalid request (error.code: bad_request).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"401": {
"description": "Authentication required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"404": {
"description": "Attachment not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"500": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"502": {
"description": "Object storage SDK failure (error.code: internal_error).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "Attachment storage is unavailable (error.code: attachment_unavailable).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}
}
GET/api/projects/{projectId}/releasesList project releases
Project-scoped manual version management, not a deployment confirmation. Current workspace and private-team permissions are revalidated. Published snapshots require current issue and original team visibility; inaccessible/deleted tasks are excluded from data and counts.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "List project releases",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectRelease"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projects/{projectId}/releasesCreate a planned project release
Project-scoped manual version management, not a deployment confirmation. Current workspace and private-team permissions are revalidated. Published snapshots require current issue and original team visibility; inaccessible/deleted tasks are excluded from data and counts.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "Strict JSON object; rejects unknown/duplicate fields. Metadata body limit 256 KiB; state transitions 1024 bytes. Publish/cancel revision binds the confirmation preview and task set; stale previews return 409. Repeated same-state transitions are silent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProjectReleaseRequest"
}
}
}
},
"responses": {
"201": {
"description": "Create a planned project release",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRelease"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/projects/{projectId}/releases/{releaseId}Read release with current or frozen task list
Project-scoped manual version management, not a deployment confirmation. Current workspace and private-team permissions are revalidated. Published snapshots require current issue and original team visibility; inaccessible/deleted tasks are excluded from data and counts.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "releaseId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Read release with current or frozen task list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectReleaseDetail"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
PATCH/api/projects/{projectId}/releases/{releaseId}Edit a planned project release
Project-scoped manual version management, not a deployment confirmation. Current workspace and private-team permissions are revalidated. Published snapshots require current issue and original team visibility; inaccessible/deleted tasks are excluded from data and counts.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "releaseId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "Strict JSON object; rejects unknown/duplicate fields. Metadata body limit 256 KiB; state transitions 1024 bytes. Publish/cancel revision binds the confirmation preview and task set; stale previews return 409. Repeated same-state transitions are silent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchProjectReleaseRequest"
}
}
}
},
"responses": {
"200": {
"description": "Edit a planned project release",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRelease"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projects/{projectId}/releases/{releaseId}/publishPublish project release
Project-scoped manual version management, not a deployment confirmation. Current workspace and private-team permissions are revalidated. Published snapshots require current issue and original team visibility; inaccessible/deleted tasks are excluded from data and counts.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "releaseId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "Strict JSON object; rejects unknown/duplicate fields. Metadata body limit 256 KiB; state transitions 1024 bytes. Publish/cancel revision binds the confirmation preview and task set; stale previews return 409. Repeated same-state transitions are silent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeProjectReleaseStateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Publish project release",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRelease"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
POST/api/projects/{projectId}/releases/{releaseId}/cancelCancel project release
Project-scoped manual version management, not a deployment confirmation. Current workspace and private-team permissions are revalidated. Published snapshots require current issue and original team visibility; inaccessible/deleted tasks are excluded from data and counts.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "releaseId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Requested-With",
"in": "header",
"required": false,
"description": "Required for session-cookie writes; not required for Bearer API Key requests.",
"schema": {
"type": "string",
"enum": [
"XMLHttpRequest"
]
}
},
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"description": "Strict JSON object; rejects unknown/duplicate fields. Metadata body limit 256 KiB; state transitions 1024 bytes. Publish/cancel revision binds the confirmation preview and task set; stale previews return 409. Repeated same-state transitions are silent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeProjectReleaseStateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Cancel project release",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRelease"
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
GET/api/project-releasesRead release directories for readable projects
Project-scoped manual version management, not a deployment confirmation. Current workspace and private-team permissions are revalidated. Published snapshots require current issue and original team visibility; inaccessible/deleted tasks are excluded from data and counts.
鉴权
[
{
"SessionCookie": []
},
{
"WorkspaceBearer": []
}
]
请求与响应
{
"parameters": [
{
"name": "X-Workspace-Id",
"in": "header",
"required": true,
"description": "Required workspace context. For Bearer API Keys, it selects and must match the key-bound workspace.",
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "projectIds",
"in": "query",
"required": true,
"description": "One comma-separated list of 1-100 unique readable project IDs, at most 4096 bytes. All references must be authorized; no partial result.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
}
],
"responses": {
"200": {
"description": "Read release directories for readable projects",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectRelease"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/Error"
},
"404": {
"$ref": "#/components/responses/Error"
},
"409": {
"$ref": "#/components/responses/Error"
},
"429": {
"$ref": "#/components/responses/APIKeyRateLimited"
},
"500": {
"$ref": "#/components/responses/Error"
}
}
}
类型与通用定义
securitySchemes
SessionCookie
{
"type": "apiKey",
"in": "cookie",
"name": "task_manager_session",
"description": "Interactive session cookie; HttpOnly and SameSite=Strict. Non-GET/HEAD/OPTIONS session writes require X-Requested-With: XMLHttpRequest."
}
WorkspaceBearer
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "tm_ API Key",
"description": "Workspace-bound API Key. Accepted only on workspace business routes. Read scope permits GET/HEAD/OPTIONS; write/admin role and private-team checks are applied server-side. Not accepted by auth-only, Key management, platform, or WebSocket routes."
}
schemas
MCPRequest
{
"type": "object",
"required": [
"jsonrpc",
"method"
],
"properties": {
"jsonrpc": {
"type": "string",
"enum": [
"2.0"
]
},
"id": {
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"method": {
"type": "string",
"description": "MCP method, including initialize, notifications/initialized, tools/list and tools/call."
},
"params": {
"type": "object",
"additionalProperties": true,
"description": "Method-specific MCP parameters. tools/call uses name and arguments; discover exact typed schemas using tools/list."
}
},
"additionalProperties": false
}
MCPResponse
{
"type": "object",
"required": [
"jsonrpc",
"id"
],
"properties": {
"jsonrpc": {
"type": "string",
"enum": [
"2.0"
]
},
"id": {
"nullable": true,
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"result": {
"type": "object",
"additionalProperties": true,
"description": "Method-specific MCP result. Tool calls return content, structuredContent and optional isError. get_issue returns issue/comments/relations; other tools wrap data as result."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer"
},
"message": {
"type": "string"
},
"data": {
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
IssueAPI.InsightCompletedHistory
{
"type": "object",
"description": "Real entries into completed from a known different category within the requested range. Canceled/duplicate, creation already completed, status definition changes, restoration and estimate changes do not count. Reopening and completing again is a new completion. Uses the current complete authorized/filter set, not event-time filter properties; no backfill. Unknown coverage is not proven zero.",
"required": [
"from",
"to",
"observedSince",
"observedThrough",
"weeks"
],
"properties": {
"from": {
"type": "string",
"format": "date"
},
"to": {
"type": "string",
"format": "date"
},
"observedSince": {
"type": "string",
"format": "date-time",
"description": "UTC instrumentation epoch after all collection triggers were installed."
},
"observedThrough": {
"type": "string",
"format": "date-time",
"description": "UTC database time captured inside the same authorized read transaction."
},
"weeks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.InsightCompletedWeek"
}
}
},
"additionalProperties": false
}
schemas/IssueAPI.InsightCompletedWeek
IssueAPI.InsightCompletedWeek
{
"type": "object",
"required": [
"startsOn",
"endsOn",
"count",
"complete",
"estimate",
"estimatedCount"
],
"properties": {
"startsOn": {
"type": "string",
"format": "date",
"description": "Monday local date."
},
"endsOn": {
"type": "string",
"format": "date",
"description": "Sunday local date."
},
"count": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Actual observed completed entries; repeated completions after reopen count separately."
},
"complete": {
"type": "boolean",
"description": "True only if the entire Monday-Sunday week lies within the requested range and fully observed past interval. False means unknown or partial, including current/future weeks."
},
"estimate": {
"type": "number",
"format": "double",
"description": "Sum of known event-time completion estimates, not current estimates."
},
"estimatedCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Number of completions with known estimates; zero means unknown estimates, not zero points."
}
},
"additionalProperties": false
}
IssueAPI.InsightCycle
{
"type": "object",
"required": [
"count",
"estimate",
"estimatedCount",
"cycleId",
"startsOn",
"endsOn",
"complete"
],
"properties": {
"count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"estimate": {
"type": "number",
"format": "double"
},
"estimatedCount": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"cycleId": {
"type": "string"
},
"startsOn": {
"type": "string",
"format": "date"
},
"endsOn": {
"type": "string",
"format": "date"
},
"complete": {
"type": "boolean",
"description": "False for a partial requested/observed cycle; do not treat partial counts as a proven full cycle velocity."
}
},
"additionalProperties": false,
"description": "Completion facts associated with this currently readable cycle at event time; never inferred from current issue assignment. Only completions inside its calendar range contribute."
}
IssueAPI.InsightCycleVelocity
{
"type": "object",
"additionalProperties": false,
"required": [
"cycles",
"unknownCycleCount",
"complete"
],
"properties": {
"cycles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.InsightCycle"
}
},
"unknownCycleCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Observed completions without a provable event-time cycle snapshot; never assigned to the issue current cycle."
},
"complete": {
"type": "boolean",
"description": "Whether event-time cycle instrumentation covers the requested observation range; individual cycles and unknownCycleCount can still indicate partial observations."
}
}
}
schemas/IssueAPI.InsightCycle
IssueAPI.InsightDuration
{
"type": "object",
"additionalProperties": false,
"required": [
"seconds",
"count",
"complete"
],
"description": "Total seconds and count of actual observed intervals ending in the requested range. Average is seconds/count only when count>0; count=0 is unknown, not zero duration. Missing or non-monotonic history must not be estimated. Processing is each round first started to completed; state dwell is real entry to exit.",
"properties": {
"seconds": {
"type": "number",
"format": "double",
"minimum": 0
},
"count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"complete": {
"type": "boolean",
"description": "Whether the applicable history was completely observed; false preserves known partial samples without claiming coverage."
}
}
}
IssueAPI.InsightStatusDwell
{
"type": "object",
"additionalProperties": false,
"required": [
"seconds",
"count",
"complete",
"category",
"statusId"
],
"description": "Total seconds and count of actual observed intervals ending in the requested range. Average is seconds/count only when count>0; count=0 is unknown, not zero duration. Missing or non-monotonic history must not be estimated. Processing is each round first started to completed; state dwell is real entry to exit.",
"properties": {
"seconds": {
"type": "number",
"format": "double",
"minimum": 0
},
"count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"complete": {
"type": "boolean",
"description": "Whether the applicable history was completely observed; false preserves known partial samples without claiming coverage."
},
"category": {
"type": "string",
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"cancelled",
"duplicate"
]
},
"statusId": {
"type": "string",
"nullable": true,
"description": "Observed workflow state ID, not its current category. Resolve only from the current authorized directory; unavailable states must not display internal IDs."
}
}
}
CoreInitiativeUpdate
{
"type": "object",
"required": [
"id",
"initiativeId",
"body",
"health",
"author",
"createdAt",
"updatedAt",
"canEdit",
"canDelete"
],
"properties": {
"id": {
"type": "string"
},
"body": {
"type": "string"
},
"health": {
"type": "string",
"enum": [
"onTrack",
"atRisk",
"offTrack"
],
"description": "Values accepted by the project_updates health column."
},
"author": {
"$ref": "#/components/schemas/CoreActor"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"canEdit": {
"type": "boolean"
},
"canDelete": {
"type": "boolean"
},
"source": {
"allOf": [
{
"$ref": "#/components/schemas/CoreActivitySource"
}
],
"description": "Omitted for cookie-origin records; source snapshots the API Key name. The internal key ID is never serialized."
},
"initiativeId": {
"type": "string"
}
},
"additionalProperties": false,
"description": "A real initiative update. Its health is independent from project-derived initiative health. Active workspace members read/publish, author edits, author or workspace admin deletes; private linked projects are not embedded."
}
schemas/CoreActor
schemas/CoreActivitySource
CoreInitiativeUpdateRequest
{
"type": "object",
"required": [
"body",
"health"
],
"properties": {
"body": {
"type": "string"
},
"health": {
"type": "string",
"enum": [
"on_track",
"at_risk",
"off_track"
]
}
},
"additionalProperties": false,
"description": "Body is limited to 1 MiB; unknown fields are rejected. Create also requires Idempotency-Key: exactly one lowercase 32-character hexadecimal value."
}
CoreInitiativeSubscription
{
"type": "object",
"additionalProperties": false,
"required": [
"subscribed"
],
"properties": {
"subscribed": {
"type": "boolean"
}
}
}
CoreInitiativeProject
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"status",
"targetDate",
"issueCount",
"completedIssueCount",
"health"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Calendar date YYYY-MM-DD, year 1000-9999; null clears the date."
},
"issueCount": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"completedIssueCount": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"health": {
"type": "string",
"nullable": true,
"enum": [
"onTrack",
"atRisk",
"offTrack",
null
],
"description": "Latest non-deleted real project update health; null when none is recorded."
}
}
}
CoreInitiative
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"description",
"status",
"leadId",
"parentId",
"targetDate",
"createdById",
"createdAt",
"updatedAt",
"projects",
"issueCount",
"completedIssueCount",
"health"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"leadId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 32
},
"parentId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 32
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Calendar date YYYY-MM-DD, year 1000-9999; null clears the date."
},
"createdById": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 32
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"projects": {
"type": "array",
"description": "Direct, currently readable, undeleted project memberships only, in canonical ID order. Hidden memberships are never returned; a projectIds PATCH preserves memberships the actor cannot currently read.",
"items": {
"$ref": "#/components/schemas/CoreInitiativeProject"
}
},
"issueCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Current readable undeleted issue count across direct projects and one level of child initiatives, deduplicated by project."
},
"completedIssueCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Same visible project union as issueCount; only actual completed workflow categories count as completed."
},
"health": {
"type": "string",
"nullable": true,
"enum": [
"onTrack",
"atRisk",
"offTrack",
null
],
"description": "Worst recorded latest health across the same readable project union, ignoring projects without updates; null if no health is known."
}
},
"description": "Workspace-visible initiative; at most one nested level. Linked project details and progress remain subject to the current actor private-team boundary."
}
schemas/CoreInitiativeProject
CoreCreateInitiativeRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Trimmed non-empty name; control characters are rejected."
},
"description": {
"type": "string",
"maxLength": 50000
},
"status": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"leadId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 32,
"description": "Active workspace member, or null to clear."
},
"parentId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 32,
"description": "Root initiative in the same workspace, or null to detach. Self-links, cycles, grandchildren and nesting an initiative that has children are rejected."
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Calendar date YYYY-MM-DD, year 1000-9999; null clears the date."
},
"projectIds": {
"type": "array",
"maxItems": 500,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"description": "Replace only currently readable direct memberships; hidden memberships are retained. Every requested project must be currently readable and in the current workspace. Canonical IDs are deduplicated; [] clears readable direct memberships."
}
},
"description": "Strict JSON object, duplicate keys and trailing input rejected; maximum request body 512 KiB. Defaults: empty description, planned status, no lead/parent/date/projects."
}
CorePatchInitiativeRequest
{
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Trimmed non-empty name; control characters are rejected."
},
"description": {
"type": "string",
"maxLength": 50000
},
"status": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"leadId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 32,
"description": "Active workspace member, or null to clear."
},
"parentId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 32,
"description": "Root initiative in the same workspace, or null to detach. Self-links, cycles, grandchildren and nesting an initiative that has children are rejected."
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Calendar date YYYY-MM-DD, year 1000-9999; null clears the date."
},
"projectIds": {
"type": "array",
"maxItems": 500,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"description": "Replace only currently readable direct memberships; hidden memberships are retained. Every requested project must be currently readable and in the current workspace. Canonical IDs are deduplicated; [] clears readable direct memberships."
}
},
"description": "Omitted fields preserve current data under the workspace transaction lock. Only leadId, parentId and targetDate accept null. Same-value writes are silent; changes and workspace sync commit atomically."
}
ErrorEnvelope
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
CoreLabelErrorEnvelope
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"bad_request",
"label_invalid_group",
"label_group_conflict",
"label_in_use"
]
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
LoginRequest
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"format": "password"
}
}
}
HealthResponse
{
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
}
},
"description": "Liveness response; this endpoint confirms the HTTP process is serving, not downstream dependency health."
}
APIKey
{
"type": "object",
"required": [
"id",
"workspaceId",
"name",
"scope",
"createdAt"
],
"properties": {
"id": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"name": {
"type": "string",
"maxLength": 100
},
"scope": {
"type": "string",
"enum": [
"read",
"write",
"admin"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"lastUsedAt": {
"type": "string",
"format": "date-time"
},
"revokedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
CreateAPIKeyRequest
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Trimmed, non-empty display name; at most 100 Unicode code points and no control characters."
},
"scope": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"default": "read",
"description": "Requested scope. Defaults to read; creation is rejected if current creator authority cannot grant the requested scope."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Optional future RFC 3339 timestamp representable by MySQL DATETIME (years 1000–9999); null or omission means no expiry."
}
},
"additionalProperties": false
}
RenameAPIKeyRequest
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
CreatedAPIKey
{
"type": "object",
"required": [
"key",
"token"
],
"properties": {
"key": {
"$ref": "#/components/schemas/APIKey"
},
"token": {
"type": "string",
"description": "One-time plaintext bearer secret returned only in this creation response; never included in list or persisted in plaintext.",
"pattern": "^tm_[0-9a-f]{64}$",
"format": "password"
}
},
"additionalProperties": false
}
schemas/APIKey
OpenAPIDocument
{
"type": "object",
"required": [
"openapi",
"info",
"paths"
],
"properties": {
"openapi": {
"type": "string",
"enum": [
"3.0.3"
]
},
"info": {
"type": "object",
"required": [
"title",
"version"
],
"properties": {
"title": {
"type": "string"
},
"version": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"servers": {
"type": "array",
"items": {
"type": "object"
}
},
"paths": {
"type": "object",
"additionalProperties": true
},
"components": {
"type": "object",
"additionalProperties": true
},
"security": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": true
}
MilestoneDate
{
"type": "string",
"format": "date",
"pattern": "^(1000|[1-9][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$",
"description": "Calendar date from year 1000 through 9999, inclusive.",
"nullable": true
}
ProjectMilestone
{
"type": "object",
"required": [
"id",
"projectId",
"name",
"targetDate",
"sortOrder"
],
"properties": {
"id": {
"type": "string",
"maxLength": 32
},
"projectId": {
"type": "string"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"targetDate": {
"$ref": "#/components/schemas/MilestoneDate"
},
"sortOrder": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"issueCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Optional count of currently visible, active issues assigned to this milestone; omitted by the batched project directory."
},
"completedIssueCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Optional count of currently visible, active issues in a completed workflow status; omitted by the batched project directory."
}
},
"additionalProperties": false
}
schemas/MilestoneDate
CreateProjectMilestoneRequest
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Server trims surrounding Unicode whitespace and requires 1–128 Unicode code points."
},
"targetDate": {
"$ref": "#/components/schemas/MilestoneDate"
}
},
"additionalProperties": false
}
schemas/MilestoneDate
PatchProjectMilestoneRequest
{
"type": "object",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Server trims surrounding Unicode whitespace and requires 1–128 Unicode code points."
},
"targetDate": {
"allOf": [
{
"$ref": "#/components/schemas/MilestoneDate"
}
],
"description": "Omit to preserve the current date; null clears it."
}
},
"additionalProperties": false
}
schemas/MilestoneDate
ReorderProjectMilestonesRequest
{
"type": "object",
"required": [
"milestoneIds"
],
"properties": {
"milestoneIds": {
"type": "array",
"maxItems": 1000,
"uniqueItems": true,
"description": "Complete ordered set of all active milestones in this project. IDs must be current; omission/addition or a stale active set returns 409 milestones_changed. An empty list is valid only when the active set is empty.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
}
},
"additionalProperties": false
}
MilestonesChangedError
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"milestones_changed"
]
},
"message": {
"type": "string",
"description": "Reload the active milestone set and retry."
}
}
}
},
"additionalProperties": false
}
CoreCycle
{
"type": "object",
"required": [
"id",
"teamId",
"number",
"name",
"startsOn",
"endsOn"
],
"properties": {
"id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"number": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string"
},
"startsOn": {
"type": "string",
"format": "date"
},
"endsOn": {
"type": "string",
"format": "date"
}
},
"additionalProperties": false
}
CoreCycleProgress
{
"type": "object",
"required": [
"total",
"completed",
"totalEstimate",
"completedEstimate"
],
"properties": {
"total": {
"type": "integer",
"format": "int32"
},
"completed": {
"type": "integer",
"format": "int32"
},
"totalEstimate": {
"type": "number",
"format": "double"
},
"completedEstimate": {
"type": "number",
"format": "double"
}
},
"additionalProperties": false
}
CoreCycleBurndownDay
{
"type": "object",
"required": [
"date",
"scope",
"completed",
"ideal"
],
"properties": {
"date": {
"type": "string",
"format": "date"
},
"scope": {
"type": "integer",
"format": "int32"
},
"completed": {
"type": "integer",
"format": "int32"
},
"ideal": {
"type": "number",
"format": "double"
}
},
"additionalProperties": false
}
CoreCycleSummary
{
"type": "object",
"required": [
"id",
"teamId",
"number",
"name",
"startsOn",
"endsOn",
"progress"
],
"properties": {
"id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"number": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string"
},
"startsOn": {
"type": "string",
"format": "date"
},
"endsOn": {
"type": "string",
"format": "date"
},
"progress": {
"$ref": "#/components/schemas/CoreCycleProgress"
}
},
"additionalProperties": false
}
schemas/CoreCycleProgress
CoreCycleDetail
{
"type": "object",
"required": [
"cycle",
"progress",
"burndown",
"issues"
],
"properties": {
"cycle": {
"$ref": "#/components/schemas/CoreCycle"
},
"progress": {
"$ref": "#/components/schemas/CoreCycleProgress"
},
"burndown": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreCycleBurndownDay"
}
},
"issues": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreIssue"
},
"description": "Issues visible to the caller; this endpoint serializes the base issue fields and label IDs, without the optional issue-list metadata envelope."
}
},
"additionalProperties": false
}
schemas/CoreCycle
schemas/CoreCycleProgress
schemas/CoreCycleBurndownDay
schemas/CoreIssue
CoreCycleSettings
{
"type": "object",
"required": [
"enabled",
"lengthWeeks",
"startWeekday",
"cooldownWeeks",
"upcomingCount",
"timeZone",
"rolloverUnfinishedIssues",
"autoAddStartedIssues"
],
"properties": {
"enabled": {
"type": "boolean"
},
"lengthWeeks": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 8
},
"startWeekday": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 6
},
"cooldownWeeks": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 2
},
"upcomingCount": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 10
},
"timeZone": {
"type": "string"
},
"rolloverUnfinishedIssues": {
"type": "boolean"
},
"autoAddStartedIssues": {
"type": "boolean"
}
},
"additionalProperties": false
}
CoreCreateCycleRequest
{
"type": "object",
"required": [
"startsOn",
"endsOn"
],
"properties": {
"name": {
"type": "string"
},
"startsOn": {
"type": "string",
"format": "date"
},
"endsOn": {
"type": "string",
"format": "date"
}
},
"additionalProperties": true,
"description": "name is optional; startsOn and endsOn are required calendar dates. Unknown JSON properties are ignored by the handler."
}
CorePatchCycleRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "Omitting this field or sending null preserves the current value; null does not clear it."
},
"startsOn": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Omitting this field or sending null preserves the current value; null does not clear it."
},
"endsOn": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Omitting this field or sending null preserves the current value; null does not clear it."
}
},
"additionalProperties": true,
"description": "Fields are optional pointers; omitted fields are preserved. Unknown JSON properties are ignored by the handler."
}
CorePatchCycleSettingsRequest
{
"type": "object",
"required": [
"lengthWeeks",
"upcomingCount"
],
"properties": {
"enabled": {
"type": "boolean"
},
"lengthWeeks": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 8
},
"startWeekday": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 6
},
"cooldownWeeks": {
"type": "integer",
"format": "int32",
"minimum": 0,
"maximum": 2
},
"upcomingCount": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 10
},
"timeZone": {
"type": "string",
"description": "Explicit IANA time zone for this team. Invalid or empty values are rejected. If omitted, an existing setting is preserved; without a saved setting the effective account zone, request zone, or UTC is used."
},
"rolloverUnfinishedIssues": {
"type": "boolean",
"description": "Optional. Defaults to true on first save; omission preserves the saved value. Null is rejected."
},
"autoAddStartedIssues": {
"type": "boolean",
"description": "Optional. Defaults to false on first save; omission preserves the saved value. Null is rejected."
}
},
"additionalProperties": true,
"description": "lengthWeeks and upcomingCount are required and must be in range; omitted startWeekday/cooldownWeeks decode as 0. Explicit timeZone sets the team's schedule zone; omission preserves an existing zone. Omitted automation flags retain existing values."
}
CoreProject
{
"type": "object",
"required": [
"id",
"createdById",
"name",
"description",
"status",
"priority",
"sortOrder",
"issueCount",
"completedIssueCount",
"leadId",
"teamIds",
"startDate",
"targetDate"
],
"properties": {
"id": {
"type": "string"
},
"createdById": {
"type": "string",
"nullable": true
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"priority": {
"$ref": "#/components/schemas/CoreProjectPriority"
},
"sortOrder": {
"type": "integer",
"format": "int64",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Safe integer ordering value."
},
"issueCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"readOnly": true,
"description": "Count of issues visible to the current user."
},
"completedIssueCount": {
"type": "integer",
"format": "int64",
"minimum": 0,
"readOnly": true,
"description": "Count of visible issues in a completed workflow status."
},
"leadId": {
"type": "string",
"nullable": true
},
"teamIds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreString"
}
},
"startDate": {
"type": "string",
"format": "date",
"nullable": true
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true
}
},
"additionalProperties": false
}
schemas/CoreProjectPriority
schemas/CoreString
CoreProjectPriority
{
"type": "string",
"enum": [
"none",
"urgent",
"high",
"medium",
"low"
]
}
CoreString
{
"type": "string"
}
CoreActor
{
"type": "object",
"required": [
"id",
"name",
"avatarUrl",
"isActive"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"isActive": {
"type": "boolean"
}
},
"additionalProperties": false
}
CoreProjectUpdate
{
"type": "object",
"required": [
"id",
"projectId",
"body",
"health",
"author",
"createdAt",
"updatedAt",
"canEdit",
"canDelete"
],
"properties": {
"id": {
"type": "string"
},
"projectId": {
"type": "string"
},
"body": {
"type": "string"
},
"health": {
"type": "string",
"enum": [
"onTrack",
"atRisk",
"offTrack"
],
"description": "Values accepted by the project_updates health column."
},
"author": {
"$ref": "#/components/schemas/CoreActor"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"canEdit": {
"type": "boolean"
},
"canDelete": {
"type": "boolean"
},
"source": {
"allOf": [
{
"$ref": "#/components/schemas/CoreActivitySource"
}
],
"description": "Omitted for cookie-origin records; source snapshots the API Key name. The internal key ID is never serialized."
}
},
"additionalProperties": false
}
schemas/CoreActor
schemas/CoreActivitySource
CoreProjectUpdatePage
{
"type": "object",
"required": [
"items",
"nextCursor",
"canCreate",
"firstUpdate"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreProjectUpdate"
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"canCreate": {
"type": "boolean"
},
"firstUpdate": {
"type": "boolean"
}
},
"additionalProperties": false
}
schemas/CoreProjectUpdate
CoreProjectNotificationSubscription
{
"type": "object",
"required": [
"created",
"completed",
"canceled",
"description",
"updates",
"comments"
],
"properties": {
"created": {
"type": "boolean"
},
"completed": {
"type": "boolean"
},
"canceled": {
"type": "boolean"
},
"description": {
"type": "boolean"
},
"updates": {
"type": "boolean"
},
"comments": {
"type": "boolean"
}
},
"additionalProperties": false
}
CoreCreateProjectRequest
{
"type": "object",
"required": [
"name",
"teamIds"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"none",
"urgent",
"high",
"medium",
"low"
],
"nullable": true,
"default": "none"
},
"leadId": {
"type": "string",
"nullable": true
},
"startDate": {
"type": "string",
"format": "date",
"nullable": true
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true
},
"teamIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
}
},
"additionalProperties": true,
"description": "Unknown JSON properties are ignored by the handler."
}
CorePatchProjectRequest
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"priority": {
"$ref": "#/components/schemas/CoreProjectPriority"
},
"leadId": {
"type": "string",
"nullable": true
},
"startDate": {
"type": "string",
"format": "date",
"nullable": true
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true
},
"teamIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
}
},
"additionalProperties": true,
"description": "Omitted known fields preserve current values; null clears nullable lead/date fields. teamIds, if supplied, must be a non-empty array of strings. Invalid JSON types for known fields return 400 without writing; unknown properties remain ignored."
}
schemas/CoreProjectPriority
CoreReorderProjectRequest
{
"type": "object",
"required": [
"status",
"placement"
],
"properties": {
"status": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"placement": {
"type": "string",
"enum": [
"first",
"last",
"before",
"after"
]
},
"anchorProjectId": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
},
"description": "before/after require an anchorProjectId distinct from projectId and visible in the target status. first/last forbid anchorProjectId."
}
CoreProjectUpdateRequest
{
"type": "object",
"required": [
"body",
"health"
],
"properties": {
"body": {
"type": "string"
},
"health": {
"type": "string",
"enum": [
"on_track",
"at_risk",
"off_track"
]
}
},
"additionalProperties": false,
"description": "Body is limited to 1 MiB; unknown fields are rejected. Create also requires Idempotency-Key: exactly one lowercase 32-character hexadecimal value."
}
CoreProjectNotificationSubscriptionRequest
{
"type": "object",
"required": [
"created",
"completed",
"canceled",
"description",
"updates",
"comments"
],
"properties": {
"created": {
"type": "boolean"
},
"completed": {
"type": "boolean"
},
"canceled": {
"type": "boolean"
},
"description": {
"type": "boolean"
},
"updates": {
"type": "boolean"
},
"comments": {
"type": "boolean"
}
},
"additionalProperties": false,
"description": "All six booleans are required; unknown fields are rejected."
}
CoreProjectReminderRequest
{
"type": "object",
"required": [
"remindAt"
],
"properties": {
"remindAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true,
"description": "RFC3339 timestamp strictly in the future and no more than one year ahead; persisted/returned as UTC. Unknown JSON properties are ignored."
}
CoreActivitySource
{
"type": "object",
"required": [
"type",
"keyName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"api"
]
},
"keyName": {
"type": "string"
},
"keyId": {
"type": "string",
"description": "Internal provenance identifier is intentionally not serialized."
}
},
"additionalProperties": false
}
CoreIssue
{
"type": "object",
"required": [
"id",
"identifier",
"teamId",
"title",
"description",
"statusId",
"priority",
"assigneeId",
"labelIds",
"projectId",
"dueDate",
"createdById",
"createdAt",
"updatedAt",
"sortOrder",
"prioritySortOrder",
"estimate"
],
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"teamId": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"statusId": {
"type": "string"
},
"priority": {
"type": "string"
},
"assigneeId": {
"type": "string",
"nullable": true
},
"labelIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Leaf label IDs only; group IDs are never stored on or returned with issues. Leaves must be workspace-scoped or belong to the issue team, and at most one leaf from each group may be assigned."
},
"projectId": {
"type": "string",
"nullable": true
},
"dueDate": {
"type": "string",
"format": "date",
"nullable": true
},
"parentIssueId": {
"type": "string",
"nullable": true
},
"createdById": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sortOrder": {
"type": "integer",
"format": "int64"
},
"prioritySortOrder": {
"type": "integer",
"format": "int64"
},
"estimate": {
"type": "number",
"format": "double",
"nullable": true
},
"startDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Optional independent calendar start date YYYY-MM-DD (years 1000-9999). Null clears it on patch; omission preserves it. Does not change cycle membership. Unset dates are omitted from Issue responses."
}
},
"additionalProperties": false
}
CoreUser
{
"type": "object",
"required": [
"id",
"name",
"avatarUrl",
"email",
"isPlatformAdmin"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"email": {
"type": "string"
},
"isPlatformAdmin": {
"type": "boolean"
},
"timeZone": {
"type": "string",
"description": "Optional IANA timezone; omitted when unset."
}
},
"additionalProperties": false
}
CoreWorkspace
{
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"additionalProperties": false
}
CoreMembership
{
"type": "object",
"required": [
"workspaceId",
"role"
],
"properties": {
"workspaceId": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"member"
]
}
},
"additionalProperties": false
}
CoreAuthContext
{
"type": "object",
"required": [
"user",
"workspaces",
"memberships"
],
"properties": {
"user": {
"$ref": "#/components/schemas/CoreUser"
},
"workspaces": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreWorkspace"
}
},
"memberships": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreMembership"
},
"nullable": true
}
},
"additionalProperties": false
}
schemas/CoreUser
schemas/CoreWorkspace
schemas/CoreMembership
CoreOK
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
}
},
"additionalProperties": false
}
CoreSetupStatus
{
"type": "object",
"required": [
"needsBootstrap"
],
"properties": {
"needsBootstrap": {
"type": "boolean"
}
},
"additionalProperties": false
}
CoreLoginRequest
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string"
},
"password": {
"type": "string"
}
},
"additionalProperties": true
}
CoreBootstrapRequest
{
"type": "object",
"required": [
"email",
"password",
"name",
"workspaceName",
"workspaceSlug"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"name": {
"type": "string"
},
"workspaceName": {
"type": "string"
},
"workspaceSlug": {
"type": "string",
"pattern": "^[a-z0-9-]{2,32}$"
}
},
"additionalProperties": true
}
CoreUpdateMeRequest
{
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"avatarUrl": {
"type": "string"
},
"timeZone": {
"type": "string",
"nullable": true
}
},
"additionalProperties": true
}
CoreChangePasswordRequest
{
"type": "object",
"required": [
"currentPassword",
"newPassword"
],
"properties": {
"currentPassword": {
"type": "string"
},
"newPassword": {
"type": "string",
"minLength": 8
}
},
"additionalProperties": true
}
CoreWorkspaceRequest
{
"type": "object",
"required": [
"name",
"workspaceSlug"
],
"properties": {
"name": {
"type": "string"
},
"workspaceSlug": {
"type": "string",
"pattern": "^[a-z0-9-]{2,32}$"
}
},
"additionalProperties": true
}
CoreTeam
{
"type": "object",
"required": [
"id",
"name",
"identifier",
"workspaceId",
"defaultStatusId",
"isPrivate"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"identifier": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"defaultStatusId": {
"type": "string",
"nullable": true
},
"isPrivate": {
"type": "boolean"
}
},
"additionalProperties": false
}
CoreStatus
{
"type": "object",
"required": [
"id",
"name",
"color",
"category",
"position",
"teamId",
"systemKey"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"cancelled",
"duplicate"
]
},
"position": {
"type": "integer",
"format": "int32"
},
"teamId": {
"type": "string"
},
"systemKey": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
CoreLabel
{
"type": "object",
"required": [
"id",
"name",
"color",
"workspaceId",
"parentId",
"teamId",
"isGroup"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"parentId": {
"type": "string",
"nullable": true,
"description": "Null for a workspace/team label that is not a child; non-null only for a leaf under a one-level group."
},
"teamId": {
"type": "string",
"nullable": true,
"description": "Null for a workspace-scoped label; otherwise the team scope."
},
"isGroup": {
"type": "boolean",
"description": "Group labels are containers and are never assigned to issues."
}
},
"additionalProperties": false
}
CoreTeamRef
{
"type": "object",
"required": [
"id",
"identifier",
"name"
],
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
CoreWorkspaceMember
{
"type": "object",
"required": [
"id",
"workspaceId",
"role",
"name",
"email",
"avatarUrl",
"teams"
],
"properties": {
"id": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"member"
]
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"teams": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreTeamRef"
}
}
},
"additionalProperties": false
}
schemas/CoreTeamRef
CoreTeamUser
{
"type": "object",
"required": [
"id",
"name",
"avatarUrl",
"email",
"isPlatformAdmin"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"email": {
"type": "string"
},
"isPlatformAdmin": {
"type": "boolean",
"description": "The team-member query does not select this database field; serialized false is a zero value and is not authoritative."
}
},
"additionalProperties": false
}
CoreCreateTeamRequest
{
"type": "object",
"required": [
"name",
"identifier"
],
"properties": {
"name": {
"type": "string"
},
"identifier": {
"type": "string",
"pattern": "^[A-Z]{1,8}$"
},
"isPrivate": {
"type": "boolean"
}
},
"additionalProperties": true,
"description": "Unknown properties are ignored."
}
CorePatchTeamRequest
{
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"identifier": {
"type": "string",
"pattern": "^[A-Z]{1,8}$"
},
"defaultStatusId": {
"type": "string",
"nullable": true
},
"isPrivate": {
"type": "boolean"
}
},
"additionalProperties": true,
"description": "At least one field is required; defaultStatusId may be null to clear. Unknown properties are ignored."
}
CoreCreateStatusRequest
{
"type": "object",
"required": [
"name",
"color",
"category"
],
"properties": {
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"cancelled"
]
},
"systemKey": {
"not": {},
"description": "Any supplied value, including null, is rejected because systemKey is server-managed."
}
},
"additionalProperties": true,
"description": "systemKey is not writable; category duplicate cannot be created. Unknown properties are ignored."
}
CorePatchStatusRequest
{
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"color": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"cancelled",
"duplicate"
]
},
"position": {
"type": "integer",
"minimum": 0
},
"systemKey": {
"not": {},
"description": "Any supplied value, including null, is rejected because systemKey is read-only."
}
},
"additionalProperties": true,
"description": "systemKey is read-only. Unknown properties are ignored."
}
CoreCreateLabelRequest
{
"type": "object",
"required": [
"name",
"color"
],
"properties": {
"name": {
"type": "string"
},
"color": {
"type": "string"
}
},
"additionalProperties": true
}
CorePatchLabelRequest
{
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string",
"maxLength": 64
},
"color": {
"type": "string",
"maxLength": 16
},
"parentId": {
"type": "string",
"nullable": true,
"description": "Omit to preserve; null clears the parent. A non-null parent must be a one-level group with matching team scope."
},
"teamId": {
"type": "string",
"nullable": true,
"description": "Omit to preserve; null clears team scope. A non-null team must be accessible to the actor, including private-team membership checks."
},
"isGroup": {
"type": "boolean",
"description": "Omit to preserve. A group cannot have a parent and cannot be assigned to an issue."
}
},
"additionalProperties": true,
"description": "All fields may be omitted and are preserved. parentId/teamId may be null to clear; scope/parent compatibility is validated. Changes that conflict with group usage or existing issue assignments return 409."
}
CoreAddWorkspaceMemberRequest
{
"type": "object",
"required": [
"userId",
"role"
],
"properties": {
"userId": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"member"
]
}
},
"additionalProperties": true
}
CoreUpdateWorkspaceMemberRequest
{
"type": "object",
"required": [
"role"
],
"properties": {
"role": {
"type": "string",
"enum": [
"admin",
"member"
]
}
},
"additionalProperties": true
}
CoreSetMemberTeamsRequest
{
"type": "object",
"required": [
"teamIds"
],
"properties": {
"teamIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
CoreTeamMemberRequest
{
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"type": "string"
}
},
"additionalProperties": true
}
CoreTeamIssueSubscription
{
"type": "object",
"required": [
"subscribed"
],
"properties": {
"subscribed": {
"type": "boolean"
}
},
"additionalProperties": false
}
CoreTeamTriage
{
"type": "object",
"required": [
"subscribed",
"responsibleUserIds",
"acceptStatusId",
"resolvedAcceptStatusId"
],
"properties": {
"subscribed": {
"type": "boolean"
},
"responsibleUserIds": {
"type": "array",
"items": {
"type": "string"
}
},
"acceptStatusId": {
"type": "string",
"nullable": true
},
"resolvedAcceptStatusId": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
CoreBoolRequest
{
"type": "object",
"required": [
"subscribed"
],
"properties": {
"subscribed": {
"type": "boolean"
}
},
"additionalProperties": true
}
CoreTeamTriageResponsibilityRequest
{
"type": "object",
"required": [
"userIds"
],
"properties": {
"userIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100
}
},
"additionalProperties": true
}
CoreCreateWorkspaceLabelRequest
{
"type": "object",
"required": [
"name",
"color"
],
"properties": {
"name": {
"type": "string",
"maxLength": 64
},
"color": {
"type": "string",
"maxLength": 16,
"description": "At most 16 UTF-8 bytes."
},
"parentId": {
"type": "string",
"nullable": true,
"description": "Optional parent; if supplied, must be a one-level group in the same workspace/team scope."
},
"teamId": {
"type": "string",
"nullable": true,
"description": "Optional team scope; caller must be allowed to access the team, including private-team membership checks. Null/omitted means workspace scope."
},
"isGroup": {
"type": "boolean",
"default": false,
"description": "Optional. Groups cannot have a parent and cannot be assigned to issues."
}
},
"additionalProperties": true,
"description": "Name is limited to 64 Unicode code points and color to 16 bytes. A group is one level only; a leaf parent must be a group with exactly the same nullable team scope. Unknown properties are ignored."
}
CoreSavedView
{
"type": "object",
"required": [
"id",
"workspaceId",
"userId",
"visibility",
"scopeKind",
"scopeId",
"name",
"filters",
"display",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"userId": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"personal",
"workspace"
]
},
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"my",
"team",
"project",
"projects"
],
"description": "projects is a project-directory saved-view scope: empty scopeId is workspace-wide, and a team ID scopes the directory to that team. Singular project remains an issue view scoped to one project."
},
"scopeId": {
"type": "string",
"description": "Empty for workspace, my, and workspace-wide projects scopes; an entity ID for team, project, and team-scoped projects views."
},
"name": {
"type": "string",
"maxLength": 128
},
"filters": {
"anyOf": [
{
"$ref": "#/components/schemas/CoreSavedViewIssueFilters"
},
{
"$ref": "#/components/schemas/CoreProjectDirectoryFilters"
}
],
"description": "Scope-specific filters: issue filters for workspace/my/team/project scopes, or project-directory filters for projects. Team-scoped project views are pinned to their team. Historical rows may contain null.",
"nullable": true
},
"display": {
"$ref": "#/components/schemas/CoreSavedViewDisplay"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
schemas/CoreSavedViewIssueFilters
schemas/CoreProjectDirectoryFilters
schemas/CoreSavedViewDisplay
CoreSavedViewFilterGroup
{
"type": "object",
"required": [
"type",
"conjunction",
"children"
],
"properties": {
"type": {
"type": "string",
"enum": [
"group"
]
},
"conjunction": {
"type": "string",
"enum": [
"and",
"or"
]
},
"children": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"$ref": "#/components/schemas/CoreSavedViewAdvancedNode"
}
}
},
"additionalProperties": false
}
schemas/CoreSavedViewAdvancedNode
CoreSavedViewFilterCondition
{
"type": "object",
"required": [
"type",
"field",
"operator",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"condition"
]
},
"field": {
"type": "string",
"description": "For label conditions, a group ID matches if the issue has any leaf in that group.",
"enum": [
"label",
"customer",
"link",
"subscriber",
"relation",
"priority",
"team",
"status",
"statusCategory",
"assignee",
"creator",
"project",
"cycle",
"cyclePhase",
"milestone",
"content",
"createdAt",
"updatedAt",
"dueDate",
"addedToCycleAt",
"cycleEntry",
"release"
]
},
"operator": {
"type": "string",
"enum": [
"includes",
"includesAny",
"includesAll",
"includesNone",
"is",
"isNot",
"isAnyOf",
"isNoneOf",
"isEmpty",
"isNotEmpty",
"contains",
"notContains",
"before",
"after",
"on"
]
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 100
}
]
}
},
"additionalProperties": false,
"description": "For advanced label conditions, a group ID matches an issue carrying any leaf in that group."
}
CoreSavedViewAdvancedNode
{
"oneOf": [
{
"$ref": "#/components/schemas/CoreSavedViewFilterGroup"
},
{
"$ref": "#/components/schemas/CoreSavedViewFilterCondition"
}
]
}
schemas/CoreSavedViewFilterGroup
schemas/CoreSavedViewFilterCondition
CoreSavedViewIssueFilters
{
"type": "object",
"required": [],
"properties": {
"priorities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low",
"none"
]
},
"maxItems": 100
},
"teamIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100
},
"labelIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Basic saved-view labels use OR semantics; a group ID matches an issue with any leaf in that group."
},
"statusCategories": {
"type": "array",
"items": {
"type": "string",
"enum": [
"triage",
"backlog",
"unstarted",
"started",
"completed",
"cancelled",
"duplicate"
]
},
"maxItems": 100
},
"statusIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100
},
"assigneeIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100
},
"projectIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100
},
"dueDate": {
"type": "string",
"enum": [
"overdue",
"today",
"this_week",
"this_month",
"no_date"
]
},
"advanced": {
"$ref": "#/components/schemas/CoreSavedViewAdvancedNode"
}
},
"description": "At most 4096 UTF-16 code units after JSON parsing; unknown top-level properties are rejected. Advanced groups depth <= 8 and total nodes <= 100; field/operator/value combinations have additional cross-field validation.",
"additionalProperties": false
}
schemas/CoreSavedViewAdvancedNode
CoreProjectDirectoryFilters
{
"type": "object",
"properties": {
"priority": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreProjectPriority"
},
"maxItems": 100
},
"leadId": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^\\S(?:.*\\S)?$",
"description": "Project lead ID; the literal none selects projects without a lead. The backend enforces a 64 UTF-16-code-unit limit."
},
"maxItems": 100
},
"teamId": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^\\S(?:.*\\S)?$",
"description": "Team ID with no surrounding whitespace. The backend enforces a 64 UTF-16-code-unit limit."
},
"maxItems": 100
},
"status": {
"type": "array",
"items": {
"type": "string",
"enum": [
"planned",
"active",
"paused",
"completed",
"cancelled"
]
},
"maxItems": 100
}
},
"description": "Project-directory filters only; all fields are optional. Unknown fields are rejected. Raw JSON is capped at 64 KiB before parsing; after parsing, at most 100 values per field and 4096 UTF-16 code units for JSON string content. Empty arrays are valid.",
"additionalProperties": false
}
schemas/CoreProjectPriority
CoreProjectDirectoryDisplay
{
"type": "object",
"properties": {
"viewMode": {
"type": "string",
"enum": [
"list",
"board",
"timeline",
"roadmap"
],
"default": "list"
},
"timelineScale": {
"type": "string",
"enum": [
"week",
"month",
"quarter"
],
"description": "Optional saved timeline scale. The client defaults to month when absent; legacy displays that omit this field remain valid and keep it omitted when saved."
},
"groupBy": {
"type": "string",
"enum": [
"none",
"status",
"priority",
"lead",
"team"
],
"default": "none"
}
},
"description": "Unknown fields, duplicate fields (including escaped aliases), and non-string values are rejected. Raw JSON is capped at 64 KiB before parsing; after parsing JSON string content is limited to 4096 UTF-16 code units. Defaults are viewMode=list and groupBy=none; list mode has no grouping. Board mode always uses status columns regardless of groupBy. Roadmap groups readable projects by their real Initiative associations. timelineScale is optional and, when present, is week, month, or quarter; the client defaults to month when it is absent, and saves preserve its absence for legacy displays.",
"additionalProperties": false
}
CoreSavedViewDisplay
{
"anyOf": [
{
"$ref": "#/components/schemas/CoreProjectDirectoryDisplay"
},
{
"description": "Issue-view display is arbitrary JSON and is not validated by the handler."
}
],
"description": "Scope-specific display. Project-directory views validate CoreProjectDirectoryDisplay and normalize omitted values to viewMode=list/groupBy=none; issue-view scopes retain their unvalidated JSON display behavior."
}
schemas/CoreProjectDirectoryDisplay
CoreSavedViewFilters
{
"anyOf": [
{
"$ref": "#/components/schemas/CoreSavedViewIssueFilters"
},
{
"$ref": "#/components/schemas/CoreProjectDirectoryFilters"
}
],
"description": "Scope-specific filter contract. anyOf intentionally permits the empty object {}, which is valid for the legacy issue parser and also for project-directory views."
}
schemas/CoreSavedViewIssueFilters
schemas/CoreProjectDirectoryFilters
CoreCreateSavedViewRequest
{
"type": "object",
"required": [
"name",
"scopeKind"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"my",
"team",
"project",
"projects"
]
},
"scopeId": {
"type": "string"
},
"filters": {
"$ref": "#/components/schemas/CoreSavedViewFilters"
},
"display": {
"allOf": [
{
"$ref": "#/components/schemas/CoreSavedViewDisplay"
}
],
"description": "Issue-view display is arbitrary JSON; project-directory display is validated by CoreProjectDirectoryDisplay. Omitted display defaults to {}; for projects scope it normalizes to viewMode=list and groupBy=none."
},
"visibility": {
"type": "string",
"enum": [
"personal",
"workspace"
]
}
},
"additionalProperties": true,
"description": "Name must be nonblank after trimming and at most 128 Unicode code points. Complete request body is limited to 64 KiB; exceeding it returns 400 bad_request. scopeId defaults to empty, filters/display default to {}, visibility defaults to personal. workspace/my scopes require empty scopeId; team/project scopes require an existing same-workspace entity ID; projects accepts empty for workspace-wide or a readable team ID for team scope. Team project views remain pinned to their team and exclude team grouping and roadmap display. Project-directory filters/display have independent schemas and each raw JSON value is capped at 64 KiB; decoded budgets remain 4096 UTF-16 code units, 100 array entries, and 64 UTF-16 code units per ID. Issue filters keep the legacy parser."
}
schemas/CoreSavedViewFilters
schemas/CoreSavedViewDisplay
CoreUpdateSavedViewRequest
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"filters": {
"$ref": "#/components/schemas/CoreSavedViewFilters"
},
"display": {
"allOf": [
{
"$ref": "#/components/schemas/CoreSavedViewDisplay"
}
],
"description": "Issue-view display is arbitrary JSON; project-directory display is validated by CoreProjectDirectoryDisplay. Omitted display resets to {}; for projects scope it normalizes to viewMode=list and groupBy=none."
}
},
"additionalProperties": true,
"description": "Creator only. Name is required and must be nonblank after trimming (<=128 Unicode code points); complete request body is limited to 64 KiB and oversized bodies return 400 bad_request. Omitted filters/display reset to empty objects. Project-directory raw filters/display JSON values are each capped at 64 KiB before parsing, with existing decoded budgets unchanged. Scope and visibility are immutable."
}
schemas/CoreSavedViewFilters
schemas/CoreSavedViewDisplay
CoreSavedViewIssueSubscription
{
"type": "object",
"required": [
"added",
"completed",
"canceled",
"contextScope",
"timeZone"
],
"properties": {
"added": {
"type": "boolean"
},
"completed": {
"type": "boolean"
},
"canceled": {
"type": "boolean"
},
"contextScope": {
"type": "string"
},
"timeZone": {
"type": "string"
}
},
"additionalProperties": false
}
CoreSavedViewIssueSubscriptionEntry
{
"type": "object",
"required": [
"viewId",
"name",
"scopeKind",
"scopeId",
"added",
"completed",
"canceled",
"contextScope",
"timeZone"
],
"properties": {
"viewId": {
"type": "string"
},
"name": {
"type": "string"
},
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"my",
"team",
"project"
]
},
"scopeId": {
"type": "string"
},
"added": {
"type": "boolean"
},
"completed": {
"type": "boolean"
},
"canceled": {
"type": "boolean"
},
"contextScope": {
"type": "string"
},
"timeZone": {
"type": "string"
}
},
"additionalProperties": false
}
CoreSavedViewIssueSubscriptionRequest
{
"type": "object",
"required": [
"added",
"completed",
"canceled"
],
"properties": {
"added": {
"type": "boolean"
},
"completed": {
"type": "boolean"
},
"canceled": {
"type": "boolean"
},
"contextScope": {
"type": "string"
}
},
"additionalProperties": true
}
CorePlatformUserCreate
{
"type": "object",
"required": [
"name",
"email",
"password"
],
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"isPlatformAdmin": {
"type": "boolean"
}
},
"additionalProperties": true
}
CorePlatformUserPatch
{
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"isActive": {
"type": "boolean"
},
"isPlatformAdmin": {
"type": "boolean"
}
},
"additionalProperties": true
}
CoreResetPasswordResponse
{
"type": "object",
"required": [
"password"
],
"properties": {
"password": {
"type": "string",
"description": "Generated one-time password; returned only in this response."
}
},
"additionalProperties": false
}
IssueAPI.IssueInsights
{
"type": "object",
"required": [
"dimension",
"timeZone",
"total",
"groups"
],
"properties": {
"dimension": {
"type": "string",
"enum": [
"status",
"statusCategory",
"assignee",
"label",
"priority",
"team",
"cycle",
"project"
]
},
"timeZone": {
"type": "string"
},
"total": {
"$ref": "#/components/schemas/IssueAPI.InsightTotal"
},
"groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.InsightGroup"
}
},
"createdHistory": {
"$ref": "#/components/schemas/IssueAPI.InsightCreatedHistory"
},
"completedHistory": {
"$ref": "#/components/schemas/IssueAPI.InsightCompletedHistory"
},
"cycleVelocity": {
"$ref": "#/components/schemas/IssueAPI.InsightCycleVelocity"
},
"processingTime": {
"$ref": "#/components/schemas/IssueAPI.InsightDuration"
},
"statusDwell": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.InsightStatusDwell"
},
"description": "Real observed workflow-state intervals; an explicit range returns an empty array if none are usable. Omitted only without a history range."
}
},
"additionalProperties": false
}
schemas/IssueAPI.InsightTotal
schemas/IssueAPI.InsightGroup
schemas/IssueAPI.InsightCreatedHistory
schemas/IssueAPI.InsightCompletedHistory
schemas/IssueAPI.InsightCycleVelocity
schemas/IssueAPI.InsightDuration
schemas/IssueAPI.InsightStatusDwell
IssueAPI.InsightCreatedHistory
{
"type": "object",
"description": "Actual creation events of the current authorized/filter set, not an event-time property snapshot. Counts exclude events before instrumentation and after the observed snapshot. Only source_kind=created contributes; restoration does not. Weeks without complete coverage must not be displayed as proven zero. Existing issue history is never backfilled. Coverage applies only to the current matched snapshot, not a global commit watermark or immutable historical total; commits and later changes to membership, visibility or filter properties may change that set and its counts.",
"required": [
"from",
"to",
"observedSince",
"observedThrough",
"weeks"
],
"properties": {
"from": {
"type": "string",
"format": "date"
},
"to": {
"type": "string",
"format": "date"
},
"observedSince": {
"type": "string",
"format": "date-time",
"description": "UTC instrumentation epoch after all collection triggers were installed."
},
"observedThrough": {
"type": "string",
"format": "date-time",
"description": "UTC database time captured inside the same authorized read transaction."
},
"weeks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.InsightCreatedWeek"
}
}
},
"additionalProperties": false
}
schemas/IssueAPI.InsightCreatedWeek
IssueAPI.InsightCreatedWeek
{
"type": "object",
"required": [
"startsOn",
"endsOn",
"count",
"complete"
],
"properties": {
"startsOn": {
"type": "string",
"format": "date",
"description": "Monday local date."
},
"endsOn": {
"type": "string",
"format": "date",
"description": "Sunday local date."
},
"count": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Observed creation events within the requested inclusive dates and observation interval. A partial count is not a complete weekly total."
},
"complete": {
"type": "boolean",
"description": "True only if the entire Monday-Sunday week lies within the requested range and fully observed past interval. False means unknown or partial, including current/future weeks."
}
},
"additionalProperties": false
}
IssueAPI.InsightTotal
{
"type": "object",
"required": [
"count",
"estimate",
"estimatedCount"
],
"properties": {
"count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"estimate": {
"type": "number",
"format": "double"
},
"estimatedCount": {
"type": "integer",
"format": "int64",
"minimum": 0
}
},
"additionalProperties": false
}
IssueAPI.InsightGroup
{
"type": "object",
"required": [
"key",
"count",
"estimate",
"estimatedCount"
],
"properties": {
"key": {
"type": "string",
"nullable": true
},
"count": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"estimate": {
"type": "number",
"format": "double"
},
"estimatedCount": {
"type": "integer",
"format": "int64",
"minimum": 0
}
},
"additionalProperties": false
}
IssueAPI.Issue
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"teamId": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"statusId": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low",
"none"
]
},
"assigneeId": {
"type": "string",
"nullable": true
},
"labelIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Leaf label IDs only. Group IDs are invalid for issue assignment; leaves must belong to the issue team or be workspace-scoped, and at most one leaf from each group may be assigned."
},
"projectId": {
"type": "string",
"nullable": true
},
"dueDate": {
"type": "string",
"nullable": true
},
"parentIssueId": {
"type": "string",
"nullable": true
},
"createdById": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sortOrder": {
"type": "integer",
"format": "int64"
},
"prioritySortOrder": {
"type": "integer",
"format": "int64"
},
"estimate": {
"type": "number",
"nullable": true
},
"cycleId": {
"type": "string",
"nullable": true
},
"addedToCycleAt": {
"type": "string",
"nullable": true
},
"subscriberIds": {
"type": "array",
"items": {
"type": "string"
}
},
"relationTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"blockingIssueIds": {
"type": "array",
"description": "Only present with include=filter_metadata. Sorted, unique IDs of currently readable issues blocked by this issue, including endpoints outside this page. Empty means no readable outgoing blocks. Clients must intersect both endpoints with their complete filtered collection before drawing dependencies. Related and duplicate relations are not dependencies.",
"uniqueItems": true,
"items": {
"type": "string"
}
},
"blockedByIssueIds": {
"type": "array",
"description": "Only present with include=filter_metadata. Sorted, unique IDs of currently readable issues blocking this issue, including endpoints outside this page. Empty means no readable incoming blocks. Both endpoints must belong to the current workspace and undeleted, currently readable teams and issues.",
"uniqueItems": true,
"items": {
"type": "string"
}
},
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"issueId": {
"type": "string"
},
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"source": {
"type": "string"
},
"createdAt": {
"type": "string"
}
},
"required": [
"id",
"issueId",
"url",
"title",
"source",
"createdAt"
]
}
},
"customers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Customer"
}
},
"statusAge": {
"type": "object",
"properties": {
"statusId": {
"type": "string"
},
"enteredAt": {
"type": "string"
}
},
"required": [
"statusId",
"enteredAt"
]
},
"identifierAliases": {
"type": "array",
"items": {
"type": "string"
}
},
"slaStartedAt": {
"type": "string"
},
"slaMediumRiskAt": {
"type": "string",
"nullable": true
},
"slaHighRiskAt": {
"type": "string",
"nullable": true
},
"slaBreachesAt": {
"type": "string"
},
"slaType": {
"type": "string"
},
"milestone": {
"type": "object",
"nullable": true
},
"cycleWindow": {
"type": "object",
"nullable": true
},
"startDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Optional independent calendar start date YYYY-MM-DD (years 1000-9999). Null clears it on patch; omission preserves it. Does not change cycle membership. Unset dates are omitted from Issue responses."
},
"release": {
"$ref": "#/components/schemas/IssueAPI.Release"
},
"releaseId": {
"type": "string",
"nullable": true,
"description": "Current target release; omitted when no target is assigned."
}
},
"required": [
"id",
"identifier",
"teamId",
"title",
"description",
"statusId",
"priority",
"assigneeId",
"labelIds",
"projectId",
"dueDate",
"createdById",
"createdAt",
"updatedAt",
"sortOrder",
"prioritySortOrder",
"estimate"
]
}
schemas/IssueAPI.Customer
schemas/IssueAPI.Release
IssueAPI.CreateIssueRequest
{
"type": "object",
"properties": {
"teamId": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"statusId": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low",
"none"
]
},
"assigneeId": {
"type": "string",
"nullable": true
},
"labelIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "When supplied, replaces labels with leaf label IDs only. Group IDs are invalid; leaves must belong to the issue team or be workspace-scoped, and at most one leaf from each group may be assigned."
},
"projectId": {
"type": "string",
"nullable": true
},
"dueDate": {
"type": "string",
"nullable": true
},
"parentIssueId": {
"type": "string",
"nullable": true
},
"cycleId": {
"type": "string",
"nullable": true
},
"estimate": {
"type": "number",
"nullable": true
},
"attachmentIds": {
"type": "array",
"maxItems": 20,
"items": {
"type": "string",
"maxLength": 32
},
"description": "Optional attachment IDs to bind with this operation; at most 20 IDs, each at most 32 characters."
},
"startDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Optional independent calendar start date YYYY-MM-DD (years 1000-9999). Null clears it on patch; omission preserves it. Does not change cycle membership. Unset dates are omitted from Issue responses."
},
"releaseId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 64,
"description": "Current target release. New assignments require a planned release in the same project. Online-only; not accepted by durable issue replay."
}
},
"required": [
"teamId",
"title"
]
}
IssueAPI.IssueLabelChange
{
"type": "object",
"properties": {
"addId": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"removeId": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
},
"anyOf": [
{
"required": [
"addId"
]
},
{
"required": [
"removeId"
]
}
],
"additionalProperties": false,
"description": "Atomic label intent used only alongside a real team move. The server applies it after destination-team normalization of the locked current labels."
}
IssueAPI.PatchIssueRequest
{
"type": "object",
"not": {
"required": [
"labelIds",
"labelChange"
]
},
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"teamId": {
"type": "string"
},
"statusId": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low",
"none"
]
},
"assigneeId": {
"type": "string",
"nullable": true
},
"labelIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "When supplied, replaces the issue's labels with leaf label IDs only. Group IDs are invalid; leaves must be workspace-scoped or belong to the issue team, and at most one leaf from each group may be assigned."
},
"labelChange": {
"$ref": "#/components/schemas/IssueAPI.IssueLabelChange",
"description": "Mutually exclusive with labelIds; requires an actual team move and applies add/remove intent to the locked label set after destination normalization."
},
"projectId": {
"type": "string",
"nullable": true
},
"dueDate": {
"type": "string",
"nullable": true
},
"parentIssueId": {
"type": "string",
"nullable": true
},
"cycleId": {
"type": "string",
"nullable": true
},
"estimate": {
"type": "number",
"nullable": true
},
"startDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Optional independent calendar start date YYYY-MM-DD (years 1000-9999). Null clears it on patch; omission preserves it. Does not change cycle membership. Unset dates are omitted from Issue responses."
},
"releaseId": {
"type": "string",
"nullable": true,
"minLength": 1,
"maxLength": 64,
"description": "Current target release. New assignments require a planned release in the same project. Online-only; not accepted by durable issue replay."
}
}
}
schemas/IssueAPI.IssueLabelChange
IssueAPI.Reaction
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"issueId": {
"type": "string"
},
"commentId": {
"type": "string",
"nullable": true
},
"userId": {
"type": "string"
},
"emoji": {
"type": "string",
"enum": [
"👍",
"❤️",
"🎉",
"👀",
"🚀",
"✅"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"source": {
"type": "object"
}
},
"required": [
"id",
"issueId",
"userId",
"emoji",
"createdAt"
]
}
IssueAPI.ReactionCollection
{
"type": "object",
"properties": {
"issueId": {
"type": "string"
},
"emojis": {
"type": "array",
"items": {
"type": "string"
}
},
"reactions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IssueAPI.Reaction"
}
}
},
"required": [
"issueId",
"emojis",
"reactions"
]
}
schemas/IssueAPI.Reaction
IssueAPI.SetReactionRequest
{
"type": "object",
"properties": {
"emoji": {
"type": "string",
"enum": [
"👍",
"❤️",
"🎉",
"👀",
"🚀",
"✅"
]
},
"active": {
"type": "boolean"
}
},
"required": [
"emoji",
"active"
],
"additionalProperties": false,
"minProperties": 2,
"maxProperties": 2
}
IssueAPI.IssueRelation
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"sourceIssueId": {
"type": "string"
},
"targetIssueId": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"related",
"blocks",
"duplicate"
],
"description": "Valid relation types are related, blocks and duplicate; blockedBy is represented by the inverse blocks relation."
},
"createdBy": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"targetIssue": {
"$ref": "#/components/schemas/IssueAPI.Issue"
},
"sourceIssue": {
"$ref": "#/components/schemas/IssueAPI.Issue"
}
},
"required": [
"id",
"sourceIssueId",
"targetIssueId",
"type",
"createdBy",
"createdAt"
]
}
schemas/IssueAPI.Issue
IssueAPI.CreateRelationRequest
{
"type": "object",
"properties": {
"targetIssueId": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"related",
"blocks",
"blockedBy",
"duplicate"
]
}
},
"required": [
"targetIssueId",
"type"
]
}
IssueAPI.SLA
{
"type": "object",
"properties": {
"slaStartedAt": {
"type": "string",
"format": "date-time"
},
"slaMediumRiskAt": {
"type": "string",
"nullable": true
},
"slaHighRiskAt": {
"type": "string",
"nullable": true
},
"slaBreachesAt": {
"type": "string",
"format": "date-time"
},
"slaType": {
"type": "string"
}
},
"required": [
"slaStartedAt",
"slaMediumRiskAt",
"slaHighRiskAt",
"slaBreachesAt",
"slaType"
],
"additionalProperties": false
}
IssueAPI.Reminder
{
"type": "object",
"properties": {
"remindAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"remindAt"
]
}
IssueAPI.SetReminderRequest
{
"type": "object",
"properties": {
"remindAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"remindAt"
]
}
IssueAPI.Customer
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
IssueAPI.CreateCustomerRequest
{
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
IssueAPI.CustomerRequest
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"issueId": {
"type": "string"
},
"customerId": {
"type": "string"
},
"customerName": {
"type": "string"
},
"body": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"issueId",
"customerId",
"customerName",
"body",
"createdAt"
]
}
IssueAPI.CreateCustomerRequestForIssue
{
"type": "object",
"properties": {
"customerId": {
"type": "string"
},
"body": {
"type": "string"
}
},
"required": [
"customerId",
"body"
],
"additionalProperties": false
}
NotificationAPI.NotificationActor
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"isActive": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"avatarUrl",
"isActive"
]
}
NotificationAPI.Notification
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"recipientId": {
"type": "string"
},
"actorId": {
"type": "string"
},
"issueId": {
"type": "string"
},
"projectId": {
"type": "string",
"nullable": true
},
"projectUpdateId": {
"type": "string",
"nullable": true
},
"projectCommentId": {
"type": "string",
"nullable": true
},
"commentId": {
"type": "string",
"nullable": true
},
"reactionEmoji": {
"type": "string",
"nullable": true
},
"kind": {
"type": "string"
},
"title": {
"type": "string"
},
"bodyPreview": {
"type": "string"
},
"readAt": {
"type": "string",
"nullable": true
},
"snoozedUntilAt": {
"type": "string",
"nullable": true
},
"unsnoozedAt": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string"
},
"groupCount": {
"type": "integer"
},
"priorityRules": {
"type": "array",
"items": {
"type": "string"
}
},
"issue": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/NotificationAPI.Issue"
}
]
},
"project": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/NotificationAPI.Project"
}
]
},
"actor": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/NotificationAPI.NotificationActor"
}
]
},
"initiativeId": {
"type": "string",
"description": "Present only for an initiativeUpdate target, never a project or issue ID."
},
"initiativeUpdateId": {
"type": "string",
"description": "Exact live initiative update target. Resolve online with the initiative and workspace scope; do not display internal IDs."
}
},
"required": [
"id",
"workspaceId",
"recipientId",
"actorId",
"issueId",
"commentId",
"kind",
"title",
"bodyPreview",
"readAt",
"snoozedUntilAt",
"unsnoozedAt",
"createdAt",
"groupCount",
"priorityRules"
],
"description": "A notification row in an issue/project group. groupCount describes the group; metadata fields are included only when requested (or on the linked-notification GET)."
}
schemas/NotificationAPI.Issue
schemas/NotificationAPI.Project
schemas/NotificationAPI.NotificationActor
NotificationAPI.ListResponse
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NotificationAPI.Notification"
}
},
"nextCursor": {
"type": "string"
}
},
"required": [
"items",
"nextCursor"
],
"description": "ListNotifications always returns this envelope; rows are grouped by issue/project entity and filtered before paging."
}
schemas/NotificationAPI.Notification
NotificationAPI.CountResponse
{
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"totalCount": {
"type": "integer"
}
},
"required": [
"count"
]
}
NotificationAPI.OK
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
]
}
NotificationAPI.UndoAction
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"undoToken": {
"type": "string"
}
},
"required": [
"ok",
"undoToken"
]
}
NotificationAPI.UndoResult
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"restoredCount": {
"type": "integer"
},
"skippedCount": {
"type": "integer"
}
},
"required": [
"ok",
"restoredCount",
"skippedCount"
]
}
NotificationAPI.ReplayResult
{
"type": "object",
"properties": {
"appliedAt": {
"type": "string",
"format": "date-time"
},
"changedCount": {
"type": "integer",
"format": "int64"
}
},
"required": [
"appliedAt",
"changedCount"
]
}
NotificationAPI.UndoRequest
{
"type": "object",
"properties": {
"undoToken": {
"type": "string"
}
},
"required": [
"undoToken"
]
}
NotificationAPI.SnoozeRequest
{
"type": "object",
"properties": {
"until": {
"type": "string",
"format": "date-time"
}
},
"required": [
"until"
]
}
NotificationAPI.ReplayRequest
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
},
"notificationId": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"read",
"unread",
"delete",
"unsnooze",
"snooze"
]
},
"until": {
"type": "string",
"format": "date-time"
}
},
"required": [
"operationId",
"notificationId",
"kind"
],
"additionalProperties": false
}
NotificationAPI.Filters
{
"type": "object",
"properties": {
"kinds": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"enum": [
"mention",
"assigned",
"comment",
"issueAssignedToYou",
"issueUnassignedFromYou",
"issueMention",
"issueCommentMention",
"issueNewComment",
"issueThreadResolved",
"issueEmojiReaction",
"issueCommentReaction",
"issueStatusChanged",
"issueStatusChangedAll",
"issueReopened",
"issueBlocking",
"issueUnblocked",
"issuePriorityUrgent",
"issueReminder",
"issueDue",
"issueCreated",
"issueAddedToView",
"issueAddedToTriage",
"triageResponsibilityIssueAddedToTriage",
"issueSubscribed",
"issueUnsubscribed",
"issueSlaHighRisk",
"issueSlaBreached",
"projectReminder",
"projectDescriptionChanged",
"projectUpdate",
"projectComment",
"projectUpdateComment"
]
}
},
"priorities": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low",
"none"
]
}
},
"teamIds": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"projectIds": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "The sentinel none selects issue groups with no project."
},
"assigneeIds": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "The sentinel unassigned selects issue groups with no assignee."
}
}
}
NotificationAPI.PriorityFilters
{
"type": "object",
"properties": {
"priorities": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"enum": [
"urgent",
"high",
"medium",
"low",
"none"
]
}
},
"teamIds": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"projectIds": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "The sentinel none selects issue groups with no project."
}
}
}
MyIssuesAPI.ActivityItem
{
"type": "object",
"properties": {
"issueId": {
"type": "string"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
},
"occurredAt": {
"type": "string"
}
},
"required": [
"issueId",
"identifier",
"title",
"occurredAt"
]
}
MyIssuesAPI.ActivityResponse
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MyIssuesAPI.ActivityItem"
}
},
"nextCursor": {
"type": "string"
},
"timeZone": {
"type": "string"
}
},
"required": [
"items",
"nextCursor"
]
}
schemas/MyIssuesAPI.ActivityItem
MyIssuesAPI.DisplaySettings
{
"type": "object",
"properties": {
"viewMode": {
"type": "string",
"enum": [
"list",
"board",
"timeline"
]
},
"groupBy": {
"type": "string",
"enum": [
"focus",
"sla",
"statusCategory",
"priority",
"team",
"assignee",
"project",
"label",
"cycle",
"parent",
"none"
]
},
"listSortBy": {
"type": "string",
"enum": [
"updated",
"priority",
"dueDate",
"created",
"status",
"manual",
"linkCount"
]
},
"boardSortBy": {
"type": "string",
"enum": [
"updated",
"priority",
"dueDate",
"created",
"status",
"manual",
"linkCount"
]
},
"display": {
"type": "object",
"properties": {
"showPriority": {
"type": "boolean"
},
"showLabels": {
"type": "boolean"
},
"showAssignee": {
"type": "boolean"
},
"showEstimate": {
"type": "boolean"
},
"showCycle": {
"type": "boolean"
},
"showSla": {
"type": "boolean"
},
"showMilestone": {
"type": "boolean"
},
"showStatusAge": {
"type": "boolean"
},
"showLinks": {
"type": "boolean"
},
"showCodeLinks": {
"type": "boolean"
},
"showSentryLinks": {
"type": "boolean"
},
"showCustomers": {
"type": "boolean"
},
"showIdentifier": {
"type": "boolean"
},
"showStatus": {
"type": "boolean"
},
"showProject": {
"type": "boolean"
},
"showDueDate": {
"type": "boolean"
},
"showCreatedAt": {
"type": "boolean"
},
"showUpdatedAt": {
"type": "boolean"
},
"showSubIssues": {
"type": "boolean"
},
"showEmptyGroups": {
"type": "boolean"
},
"reverseSort": {
"type": "boolean"
},
"subGroupBy": {
"type": "string",
"enum": [
"sla",
"statusCategory",
"priority",
"team",
"assignee",
"project",
"label",
"cycle",
"parent",
"none"
]
},
"groupMetric": {
"type": "string",
"enum": [
"count",
"estimate"
]
}
},
"required": [
"showPriority",
"showLabels",
"showAssignee"
],
"additionalProperties": false
},
"timelineScale": {
"type": "string",
"enum": [
"week",
"month",
"quarter"
],
"description": "Optional Timeline scale. Omitted values stay omitted for legacy settings; clients display month when absent."
},
"showRelease": {
"type": "boolean",
"description": "Display the current target release. Defaults to false."
}
},
"required": [
"viewMode",
"groupBy",
"listSortBy",
"boardSortBy",
"display"
],
"additionalProperties": false,
"description": "groupBy=focus is valid only for scope=assigned; display accepts only the documented boolean flags plus optional subGroupBy and groupMetric."
}
MyIssuesAPI.DisplayDefaults
{
"type": "object",
"properties": {
"assigned": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/MyIssuesAPI.DisplaySettings"
}
]
},
"created": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/MyIssuesAPI.DisplaySettings"
}
]
},
"subscribed": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/MyIssuesAPI.DisplaySettings"
}
]
}
},
"required": [
"assigned",
"created",
"subscribed"
]
}
schemas/MyIssuesAPI.DisplaySettings
FavoritesAPI.Favorite
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"userId": {
"type": "string"
},
"targetType": {
"type": "string"
},
"targetId": {
"type": "string"
},
"issue": {
"$ref": "#/components/schemas/FavoritesAPI.Issue"
},
"project": {
"$ref": "#/components/schemas/FavoritesAPI.Project"
},
"createdAt": {
"type": "string"
}
},
"required": [
"id",
"workspaceId",
"userId",
"targetType",
"targetId",
"createdAt"
]
}
schemas/FavoritesAPI.Issue
schemas/FavoritesAPI.Project
FavoritesAPI.CreateRequest
{
"type": "object",
"properties": {
"targetType": {
"type": "string",
"enum": [
"issue",
"project"
]
},
"targetId": {
"type": "string"
}
},
"required": [
"targetType",
"targetId"
]
}
PlatformAPI.User
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"email": {
"type": "string"
},
"isPlatformAdmin": {
"type": "boolean"
},
"timeZone": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"name",
"avatarUrl",
"email",
"isPlatformAdmin"
]
}
PlatformAPI.CreateUserRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Must contain at least one non-whitespace character; surrounding whitespace is trimmed."
},
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8,
"description": "At most 72 UTF-8 bytes (bcrypt limit)."
},
"isPlatformAdmin": {
"type": "boolean"
}
},
"required": [
"name",
"email",
"password"
]
}
PlatformAPI.PatchUserRequest
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"isActive": {
"type": "boolean"
},
"isPlatformAdmin": {
"type": "boolean"
}
}
}
PlatformAPI.Workspace
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"id",
"name",
"slug"
]
}
PlatformAPI.WorkspaceMember
{
"type": "object",
"required": [
"id",
"workspaceId",
"role",
"name",
"email",
"avatarUrl",
"teams"
],
"properties": {
"id": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"member"
]
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"teams": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"identifier",
"name"
],
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
PlatformAPI.AddMemberRequest
{
"type": "object",
"properties": {
"userId": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"admin",
"member"
]
}
},
"required": [
"userId",
"role"
]
}
PlatformAPI.RoleRequest
{
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"admin",
"member"
]
}
},
"required": [
"role"
]
}
PlatformAPI.OK
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
]
}
PlatformAPI.PasswordResponse
{
"type": "object",
"properties": {
"password": {
"type": "string"
}
},
"required": [
"password"
]
}
PlatformAPI.NotificationMetrics
{
"type": "object",
"required": [
"startedAt",
"generation",
"email",
"snooze"
],
"properties": {
"startedAt": {
"type": "string",
"format": "date-time"
},
"generation": {
"type": "object",
"required": [
"delivered",
"dropped",
"failed",
"delay"
],
"properties": {
"delivered": {
"type": "integer",
"format": "uint64"
},
"dropped": {
"type": "integer",
"format": "uint64"
},
"failed": {
"type": "integer",
"format": "uint64"
},
"delay": {
"$ref": "#/components/schemas/PlatformAPI.HistogramSnapshot"
}
}
},
"email": {
"type": "object",
"required": [
"attempts",
"accepted",
"failed",
"completed",
"digestCompleted",
"delay"
],
"properties": {
"attempts": {
"type": "integer",
"format": "uint64"
},
"accepted": {
"type": "integer",
"format": "uint64"
},
"failed": {
"type": "integer",
"format": "uint64"
},
"completed": {
"type": "integer",
"format": "uint64"
},
"digestCompleted": {
"type": "integer",
"format": "uint64"
},
"delay": {
"$ref": "#/components/schemas/PlatformAPI.HistogramSnapshot"
}
}
},
"snooze": {
"type": "object",
"required": [
"count",
"delay"
],
"properties": {
"count": {
"type": "integer",
"format": "uint64"
},
"delay": {
"$ref": "#/components/schemas/PlatformAPI.HistogramSnapshot"
}
}
}
}
}
schemas/PlatformAPI.HistogramSnapshot
IssueAPI.Activity
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"issueId": {
"type": "string"
},
"actorId": {
"type": "string"
},
"kind": {
"type": "string"
},
"fromValue": {
"type": "string",
"nullable": true
},
"toValue": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string"
},
"source": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"keyName": {
"type": "string"
}
},
"required": [
"type",
"keyName"
]
}
},
"required": [
"id",
"issueId",
"actorId",
"kind",
"fromValue",
"toValue",
"createdAt"
]
}
IssueAPI.Link
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"issueId": {
"type": "string"
},
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"source": {
"type": "string"
},
"createdAt": {
"type": "string"
}
},
"required": [
"id",
"issueId",
"url",
"title",
"source",
"createdAt"
]
}
IssueAPI.CreateLinkRequest
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"source": {
"type": "string"
}
},
"required": [
"url",
"title"
]
}
IssueAPI.Cycle
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"number": {
"type": "integer"
},
"name": {
"type": "string"
},
"startsOn": {
"type": "string",
"format": "date"
},
"endsOn": {
"type": "string",
"format": "date"
}
},
"required": [
"id",
"teamId",
"number",
"name",
"startsOn",
"endsOn"
]
}
IssueAPI.CycleEnvelope
{
"type": "object",
"properties": {
"cycle": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/IssueAPI.Cycle"
}
]
}
},
"required": [
"cycle"
]
}
schemas/IssueAPI.Cycle
IssueAPI.SetCycleRequest
{
"type": "object",
"properties": {
"cycleId": {
"type": "string"
}
},
"required": [
"cycleId"
]
}
IssueAPI.ProjectMilestone
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"projectId": {
"type": "string"
},
"name": {
"type": "string"
},
"targetDate": {
"type": "string",
"format": "date",
"nullable": true
},
"sortOrder": {
"type": "integer"
},
"issueCount": {
"type": "integer"
},
"completedIssueCount": {
"type": "integer"
}
},
"required": [
"id",
"projectId",
"name",
"sortOrder"
]
}
IssueAPI.SetMilestoneRequest
{
"type": "object",
"properties": {
"milestoneId": {
"type": "string",
"nullable": true
}
},
"required": [
"milestoneId"
],
"additionalProperties": false
}
IssueAPI.ReorderRequest
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"manual",
"priority"
]
},
"placement": {
"type": "string",
"enum": [
"before",
"after",
"first",
"last"
]
},
"anchorIssueId": {
"type": "string"
}
},
"required": [
"mode",
"placement"
]
}
IssueAPI.Subscription
{
"type": "object",
"properties": {
"subscribed": {
"type": "boolean"
},
"notifyAllStatusChanges": {
"type": "boolean"
}
},
"required": [
"subscribed",
"notifyAllStatusChanges"
]
}
IssueAPI.SetSubscriptionRequest
{
"type": "object",
"properties": {
"notifyAllStatusChanges": {
"type": "boolean"
}
},
"required": [
"notifyAllStatusChanges"
]
}
IssueAPI.SetSubscriberRequest
{
"type": "object",
"properties": {
"subscribed": {
"type": "boolean"
}
},
"required": [
"subscribed"
]
}
IssueAPI.User
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"email": {
"type": "string"
},
"isPlatformAdmin": {
"type": "boolean"
},
"timeZone": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"name",
"avatarUrl",
"email",
"isPlatformAdmin"
]
}
ProjectReminderAPI.Reminder
{
"type": "object",
"properties": {
"remindAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"remindAt"
]
}
ProjectReminderAPI.SetRequest
{
"type": "object",
"properties": {
"remindAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"remindAt"
]
}
PlatformAPI.HistogramSnapshot
{
"type": "object",
"required": [
"count",
"sumSeconds",
"boundsSeconds",
"buckets",
"overflow"
],
"properties": {
"count": {
"type": "integer",
"format": "uint64"
},
"sumSeconds": {
"type": "number"
},
"boundsSeconds": {
"type": "array",
"items": {
"type": "number"
}
},
"buckets": {
"type": "array",
"items": {
"type": "integer",
"format": "uint64"
}
},
"overflow": {
"type": "integer",
"format": "uint64"
}
}
}
NotificationAPI.IssueStatus
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"color": {
"type": "string"
},
"systemKey": {
"type": "string",
"nullable": true
}
},
"required": [
"id",
"name",
"category",
"color",
"systemKey"
]
}
NotificationAPI.IssueAssignee
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
}
},
"required": [
"id",
"name",
"avatarUrl"
]
}
NotificationAPI.IssueTeam
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"identifier": {
"type": "string"
}
},
"required": [
"id",
"name",
"identifier"
]
}
NotificationAPI.IssueProject
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
NotificationAPI.Project
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"name",
"status"
]
}
NotificationAPI.Issue
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
},
"priority": {
"type": "string"
},
"status": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/NotificationAPI.IssueStatus"
}
]
},
"assignee": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/NotificationAPI.IssueAssignee"
}
]
},
"team": {
"$ref": "#/components/schemas/NotificationAPI.IssueTeam"
},
"project": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/NotificationAPI.IssueProject"
}
]
}
},
"required": [
"id",
"identifier",
"title",
"priority",
"status",
"assignee",
"team",
"project"
]
}
schemas/NotificationAPI.IssueStatus
schemas/NotificationAPI.IssueAssignee
schemas/NotificationAPI.IssueTeam
schemas/NotificationAPI.IssueProject
FavoritesAPI.Issue
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
},
"teamId": {
"type": "string"
}
},
"required": [
"id",
"identifier",
"title",
"teamId"
]
}
FavoritesAPI.Project
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"name",
"status"
]
}
NotificationSettingsChannels
{
"type": "object",
"required": [
"desktop",
"mobile",
"email",
"slack"
],
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
}
NotificationSettingsResponse
{
"type": "object",
"required": [
"channels",
"categories",
"emailMode",
"capabilities"
],
"properties": {
"channels": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"categories": {
"type": "object",
"required": [
"assignments",
"mentions",
"commentsAndReplies",
"reactions",
"statusChanges",
"reminders",
"reviews",
"subscriptions",
"triage",
"documentChanges",
"postsAndUpdates",
"customers",
"appsAndIntegrations",
"billing",
"feed",
"system",
"loops"
],
"properties": {
"assignments": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"mentions": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"commentsAndReplies": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"reactions": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"statusChanges": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"reminders": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"reviews": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"subscriptions": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"triage": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"documentChanges": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"postsAndUpdates": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"customers": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"appsAndIntegrations": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"billing": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"feed": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"system": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
},
"loops": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
}
},
"additionalProperties": false
},
"emailMode": {
"type": "string",
"enum": [
"digest",
"immediate"
]
},
"capabilities": {
"$ref": "#/components/schemas/NotificationSettingsChannels"
}
},
"additionalProperties": false
}
schemas/NotificationSettingsChannels
NotificationSettingsPatch
{
"type": "object",
"minProperties": 1,
"properties": {
"channels": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"categories": {
"type": "object",
"minProperties": 1,
"properties": {
"assignments": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"mentions": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"commentsAndReplies": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"reactions": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"statusChanges": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"reminders": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"reviews": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"subscriptions": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"triage": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"documentChanges": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"postsAndUpdates": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"customers": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"appsAndIntegrations": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"billing": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"feed": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"system": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
},
"loops": {
"type": "object",
"minProperties": 1,
"properties": {
"desktop": {
"type": "boolean"
},
"mobile": {
"type": "boolean"
},
"email": {
"type": "boolean"
},
"slack": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"emailMode": {
"type": "string",
"enum": [
"digest",
"immediate"
]
}
},
"additionalProperties": false,
"description": "At least one non-empty channels/category patch or emailMode is required; unknown fields and null values are rejected."
}
SubscribedIssueIDs
{
"type": "array",
"items": {
"type": "string"
}
}
CoreTrashDeletedBy
{
"type": "object",
"required": [
"id",
"name",
"avatarUrl"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
CoreTrashEntry
{
"type": "object",
"required": [
"id",
"type",
"title",
"identifier",
"teamId",
"deletedAt",
"deletedBy",
"canRestore"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"issue",
"project"
]
},
"title": {
"type": "string"
},
"identifier": {
"type": "string",
"nullable": true
},
"teamId": {
"type": "string",
"nullable": true
},
"deletedAt": {
"type": "string",
"format": "date-time"
},
"deletedBy": {
"allOf": [
{
"$ref": "#/components/schemas/CoreTrashDeletedBy"
}
],
"nullable": true,
"description": "Null when historical deleter data is unavailable; never inferred."
},
"canRestore": {
"type": "boolean",
"description": "For session authentication, true when the actor is the creator or a workspace/platform admin. For API Keys, read scope is always false, write scope is true only for the creator's own entry, and admin scope can restore another actor's entry only while the current actor remains a workspace or platform admin. A true value does not guarantee that related team, status, parent, or project dependencies are restorable; dependency conflicts may still reject the restore request."
}
},
"additionalProperties": false
}
schemas/CoreTrashDeletedBy
CoreTrashPage
{
"type": "object",
"required": [
"items",
"nextCursor",
"totalCount",
"revision"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreTrashEntry"
}
},
"nextCursor": {
"type": "string",
"nullable": true
},
"totalCount": {
"type": "integer",
"minimum": 0,
"description": "Count of all trash entries visible to the current viewer, independent of filters and pagination."
},
"revision": {
"type": "string",
"description": "Opaque snapshot revision for all currently visible trash entries, independent of filters and pagination; it is not a count."
}
},
"additionalProperties": false
}
schemas/CoreTrashEntry
CoreEmptyTrashRequest
{
"type": "object",
"required": [
"revision"
],
"properties": {
"revision": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"description": "Opaque 64-character snapshot revision copied from the current trash response; values that do not match the current snapshot return trash_changed."
}
},
"additionalProperties": false
}
CoreTrashConflictErrorEnvelope
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"trash_changed",
"trash_restore_conflict",
"trash_dependency_conflict"
]
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
CoreWebhookEvent
{
"type": "string",
"enum": [
"issue.created",
"issue.updated",
"issue.deleted",
"comment.created",
"comment.updated",
"comment.deleted",
"project.created",
"project.updated",
"project.deleted",
"cycle.created",
"cycle.updated",
"cycle.deleted"
]
}
CoreWebhookEventPayload
{
"type": "object",
"description": "Signed JSON POST body sent to a configured webhook HTTPS receiver. For new comment events, issueId identifies issue comments, projectId identifies project comments, and projectId with projectUpdateId identifies project-update comments. Earlier queued or replayed events can lack these fields. The payload contains no comment body.",
"required": [
"id",
"type",
"workspaceId",
"entityId",
"occurredAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
"type": {
"$ref": "#/components/schemas/CoreWebhookEvent"
},
"workspaceId": {
"type": "string"
},
"entityId": {
"type": "string",
"description": "Internal ID of the changed entity. For comment events, this is the comment ID."
},
"occurredAt": {
"type": "string",
"format": "date-time"
},
"issueId": {
"type": "string",
"description": "For an issue comment, use GET /api/issues/{issueId}/comments and match entityId to an item ID."
},
"projectId": {
"type": "string",
"description": "For a project description comment, use GET /api/projects/{projectId}/comments/{entityId}. Project-update comments also carry projectUpdateId."
},
"projectUpdateId": {
"type": "string",
"description": "For a project-update comment, use GET /api/projects/{projectId}/updates/{projectUpdateId}/comments/{entityId}."
}
},
"additionalProperties": false
}
schemas/CoreWebhookEvent
CoreWebhook
{
"type": "object",
"required": [
"id",
"workspaceId",
"url",
"events",
"configuredById",
"revision",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
},
"workspaceId": {
"type": "string"
},
"url": {
"type": "string",
"maxLength": 2048,
"description": "HTTPS URL for a publicly routable destination; userinfo, fragments, private/loopback addresses, and non-public resolved IPs are rejected."
},
"events": {
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/CoreWebhookEvent"
}
},
"configuredById": {
"type": "string"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Increments whenever the configuration and signing secret are replaced."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
schemas/CoreWebhookEvent
CoreWebhookInput
{
"type": "object",
"required": [
"url",
"events"
],
"properties": {
"url": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "Maximum 2048 UTF-8 bytes. Must be HTTPS and target a public routable destination; userinfo, fragments, private/loopback addresses, and non-public resolved IPs are rejected."
},
"events": {
"type": "array",
"minItems": 1,
"maxItems": 12,
"uniqueItems": true,
"items": {
"$ref": "#/components/schemas/CoreWebhookEvent"
}
}
},
"additionalProperties": false
}
schemas/CoreWebhookEvent
CoreWebhookListResponse
{
"type": "object",
"required": [
"enabled",
"items"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "True when a 32-byte webhook secret-encryption key is configured."
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreWebhook"
}
}
},
"additionalProperties": false
}
schemas/CoreWebhook
CoreWebhookSecretResponse
{
"type": "object",
"required": [
"webhook",
"secret"
],
"properties": {
"webhook": {
"$ref": "#/components/schemas/CoreWebhook"
},
"secret": {
"type": "string",
"pattern": "^whsec_[A-Za-z0-9_-]{43}$",
"description": "Signing secret returned once by create or configuration replacement; it cannot be retrieved from list or delivery history."
}
},
"additionalProperties": false
}
schemas/CoreWebhook
CoreWebhookDeliveryPage
{
"type": "object",
"required": [
"items",
"nextCursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CoreWebhookDelivery"
}
},
"nextCursor": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
schemas/CoreWebhookDelivery
CoreWebhookDelivery
{
"type": "object",
"required": [
"id",
"eventId",
"eventType",
"entityId",
"webhookRevision",
"status",
"attemptCount",
"retryCount",
"availableAt",
"lastHttpStatus",
"lastErrorCode",
"createdAt",
"deliveredAt",
"canReplay",
"attempts"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
},
"eventId": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"pattern": "^[0-9a-f]{64}$"
},
"eventType": {
"$ref": "#/components/schemas/CoreWebhookEvent"
},
"entityId": {
"type": "string"
},
"webhookRevision": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"delivered",
"failed",
"suppressed"
]
},
"attemptCount": {
"type": "integer",
"minimum": 0
},
"retryCount": {
"type": "integer",
"minimum": 0,
"maximum": 255
},
"availableAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Present only while status is pending; null for other statuses."
},
"lastHttpStatus": {
"type": "integer",
"minimum": 100,
"maximum": 599,
"nullable": true
},
"lastErrorCode": {
"type": "string",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"deliveredAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"canReplay": {
"type": "boolean",
"description": "True only for an eligible delivery on the current webhook revision while the endpoint owner and private-team authorization remain valid; replay still revalidates these conditions transactionally."
},
"attempts": {
"type": "array",
"maxItems": 20,
"description": "At most the latest 20 attempts, ordered by attempt number descending.",
"items": {
"$ref": "#/components/schemas/CoreWebhookAttempt"
}
}
},
"additionalProperties": false
}
schemas/CoreWebhookEvent
schemas/CoreWebhookAttempt
CoreWebhookAttempt
{
"type": "object",
"required": [
"attempt",
"httpStatus",
"errorCode",
"startedAt",
"finishedAt"
],
"properties": {
"attempt": {
"type": "integer",
"minimum": 1
},
"httpStatus": {
"type": "integer",
"minimum": 100,
"maximum": 599,
"nullable": true
},
"errorCode": {
"type": "string",
"nullable": true
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Null while the attempt is still in progress."
}
},
"additionalProperties": false
}
CoreWebhookConflictErrorEnvelope
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"webhook_changed",
"webhook_busy"
]
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
CoreWebhookChangedErrorEnvelope
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"webhook_changed"
]
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
CoreAttachment
{
"type": "object",
"description": "Attachment metadata only. Storage keys, ETags, workspace/team identifiers, and signing credentials are never exposed.",
"required": [
"id",
"ownerType",
"filename",
"size",
"mimeType",
"uploadedBy",
"createdAt",
"state"
],
"properties": {
"id": {
"type": "string"
},
"issueId": {
"type": "string"
},
"commentId": {
"type": "string"
},
"ownerType": {
"type": "string",
"enum": [
"issue",
"comment"
]
},
"filename": {
"type": "string"
},
"size": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"mimeType": {
"type": "string"
},
"uploadedBy": {
"type": "string",
"description": "ID of the user who uploaded this attachment."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"state": {
"type": "string",
"enum": [
"pending",
"ready",
"bound"
]
}
},
"additionalProperties": false
}
CoreAttachmentCapabilities
{
"type": "object",
"required": [
"enabled",
"maxSize",
"mimeTypes"
],
"properties": {
"enabled": {
"type": "boolean"
},
"maxSize": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"mimeTypes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
CoreAttachmentUploadRequest
{
"type": "object",
"required": [
"ownerType",
"filename",
"size",
"mimeType"
],
"properties": {
"issueId": {
"type": "string"
},
"teamId": {
"type": "string"
},
"commentId": {
"type": "string"
},
"ownerType": {
"type": "string",
"enum": [
"issue",
"comment"
]
},
"filename": {
"type": "string"
},
"size": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"mimeType": {
"type": "string"
}
},
"additionalProperties": false
}
CoreAttachmentUploadResponse
{
"type": "object",
"required": [
"attachment",
"upload"
],
"properties": {
"attachment": {
"$ref": "#/components/schemas/CoreAttachment"
},
"upload": {
"$ref": "#/components/schemas/CoreAttachmentUploadTarget"
}
},
"additionalProperties": false
}
schemas/CoreAttachment
schemas/CoreAttachmentUploadTarget
CoreAttachmentUploadTarget
{
"type": "object",
"description": "Short-lived HTTP POST form target. fields are the signed form parameters for this upload only; the long-lived storage signing secret is not returned.",
"required": [
"endpoint",
"fields",
"expiresAt"
],
"properties": {
"endpoint": {
"type": "string",
"format": "uri"
},
"fields": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
CoreAttachmentCompleteRequest
{
"type": "object",
"description": "Empty JSON object.",
"properties": {},
"additionalProperties": false
}
CoreAttachmentDownload
{
"type": "object",
"required": [
"url",
"expiresAt"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Private temporary bearer URL; do not persist or log."
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
ProjectRelease
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"projectId": {
"type": "string"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"maxLength": 10000
},
"targetDate": {
"type": "string",
"nullable": true,
"format": "date"
},
"status": {
"type": "string",
"enum": [
"planned",
"released",
"cancelled"
]
},
"createdById": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"releasedById": {
"type": "string",
"nullable": true
},
"releasedAt": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"canManage": {
"type": "boolean"
},
"issueCount": {
"type": "integer",
"minimum": 0
},
"completedIssueCount": {
"type": "integer",
"minimum": 0
},
"revision": {
"type": "string",
"pattern": "^([0-9a-f]{64})?$",
"description": "Confirmation digest on a fully authorized planned detail preview; empty for summaries, terminal state or partial access."
},
"cancelledById": {
"type": "string",
"nullable": true
},
"cancelledAt": {
"type": "string",
"nullable": true,
"format": "date-time"
}
},
"additionalProperties": false,
"required": [
"id",
"projectId",
"name",
"description",
"targetDate",
"status",
"createdById",
"createdAt",
"releasedById",
"releasedAt",
"canManage",
"issueCount",
"completedIssueCount",
"revision",
"cancelledById",
"cancelledAt"
]
}
ProjectReleaseIssue
{
"type": "object",
"properties": {
"issueId": {
"type": "string"
},
"identifier": {
"type": "string"
},
"title": {
"type": "string"
},
"statusCategory": {
"type": "string"
},
"frozen": {
"type": "boolean",
"description": "True for published snapshot rows; false for planned current tasks."
}
},
"additionalProperties": false,
"required": [
"issueId",
"identifier",
"title",
"statusCategory",
"frozen"
]
}
ProjectReleaseDetail
{
"type": "object",
"properties": {
"release": {
"$ref": "#/components/schemas/ProjectRelease"
},
"issues": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectReleaseIssue"
}
}
},
"additionalProperties": false,
"required": [
"release",
"issues"
]
}
schemas/ProjectRelease
schemas/ProjectReleaseIssue
CreateProjectReleaseRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"maxLength": 10000
},
"targetDate": {
"type": "string",
"nullable": true,
"format": "date"
}
},
"additionalProperties": false,
"required": [
"name"
]
}
PatchProjectReleaseRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"maxLength": 10000
},
"targetDate": {
"type": "string",
"nullable": true,
"format": "date"
}
},
"additionalProperties": false,
"minProperties": 1
}
ChangeProjectReleaseStateRequest
{
"type": "object",
"properties": {
"revision": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
"additionalProperties": false,
"required": [
"revision"
]
}
IssueAPI.Release
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"projectId": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"planned",
"released",
"cancelled"
]
}
},
"additionalProperties": false,
"required": [
"id",
"projectId",
"name",
"status"
],
"nullable": true
}
responses
Error
{
"description": "Structured API error. Server 5xx details are hidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
schemas/ErrorEnvelope
APIKeyRateLimited
{
"description": "The Bearer API Key exceeded its database-shared per-minute limit. Retry after the seconds reported by Retry-After.",
"headers": {
"Retry-After": {
"required": true,
"description": "Integer seconds until the key rate window resets.",
"schema": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
schemas/ErrorEnvelope