Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

190 KB
Raw Blame
openapi: 3.1.0
info:
  title: LoopForge Platform REST API
  version: 1.0.0
  description: |
    Public control-plane API exposed by LoopForge. Signed login cookies and
    user-owned Bearer tokens authenticate Studio, REST API, and MCP access. Legacy
    deployment-level Basic authentication remains available. Worker signals,
    OTLP ingestion, run leases, and sandbox-reclamation endpoints are intentionally
    excluded because they are internal implementation contracts.
servers:
  - url: /
security:
  - bearerAuth: []
  - cookieAuth: []
  - basicAuth: []
tags:
  - name: System
  - name: Assistant
  - name: Projects
  - name: BusinessDomains
  - name: Repositories
  - name: Issues
  - name: Tasks
  - name: Assets
  - name: Workflows
  - name: Runs
  - name: Sync
  - name: Scheduling
  - name: Analytics
  - name: Feedback
paths:
  /api/runs/{id}/control:
    parameters:
      - {name: id, in: path, required: true, schema: {type: string}}
    get:
      tags: [Runs]
      operationId: getRunControl
      summary: Read run mode and valid next actions
      description: Requires project membership. Separates execution progress, verification results and explicit delivery acceptance. Returns mode (sop or workspace), status, waitingReason, allowedActions and acceptance evidence. Workspaces and historical role-group records allow no SOP actions.
      responses:
        "200":
          description: Current control state
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Run not found
  /api/health:
    get:
      tags: [System]
      operationId: getHealth
      summary: Check service health
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/assistant/chat:
    post:
      tags: [Assistant]
      operationId: chatAssistant
      summary: Ask the Studio AI assistant or generate platform resource drafts
      description: |
        Uses the signed-in user's personal CodeBuddy API key. The model can
        request bounded source lookups and project HTTP MCP calls (`mcpCalls`).
        The CLI itself cannot call MCP, modify the source snapshot, push, or
        deploy. The server invokes TAPD/Gongfeng-style HTTP MCP that the user
        can already see in the current project, using the user's credentials,
        and redacts secrets from results. Drafts may use any public MCP write
        tool (agents, workflows including script nodes, sandboxes, Dockerfiles,
        schedule jobs, publish, start run, and so on) plus assistant_tasks_save.
        The browser applies those drafts with a separate MCP tools/call after
        the user confirms. Assistant scheduled prompts are saved with
        PUT /api/assistant/tasks and are isolated per project. Send
        `Accept: text/event-stream` to receive thought events and a final
        result event; otherwise the response is a single JSON object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [messages]
              properties:
                projectId: {type: string}
                sessionId: {type: string}
                model: {type: string}
                updatedAt: {type: string, format: date-time}
                messages:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [role, content]
                    properties:
                      role: {type: string, enum: [user, assistant]}
                      content: {type: string}
                      authorId: {type: integer}
                      authorName: {type: string}
                      speakerAgentId: {type: string}
                      speakerName: {type: string}
      responses:
        "200":
          description: Assistant reply, optional source citations, and unsaved drafts
          content:
            application/json:
              schema:
                type: object
                required: [message, drafts]
                properties:
                  message: {type: string}
                  sessionId: {type: string}
                  drafts:
                    type: array
                    maxItems: 12
                    items:
                      type: object
                      required: [tool]
                      properties:
                        tool: {type: string, description: Public MCP write tool or assistant_tasks_save}
                        path:
                          type: object
                          additionalProperties: true
                        query:
                          type: object
                          additionalProperties: true
                        body: {type: object}
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        path: {type: string}
                        line: {type: integer}
                        text: {type: string}
                  mcpCalls:
                    type: array
                    maxItems: 3
                    description: Internal follow-up requests; the HTTP response is the final answer after the server executes them.
                    items:
                      type: object
                      required: [server]
                      properties:
                        server: {type: string}
                        tool: {type: string}
                        arguments:
                          type: object
                          additionalProperties: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          description: The user already has a generation in progress
        "502":
          description: The model failed or returned an invalid draft
        "504":
          description: Generation cancelled or timed out
  /api/assistant/models:
    get:
      tags: [Assistant]
      operationId: listAssistantModels
      summary: List models available to the Studio assistant
      parameters:
        - name: schedule
          in: query
          schema: {type: integer, enum: [1]}
          description: Include built-in models for CLIs configured to use account login on the signed-in user's default execution machine.
      responses:
        "200":
          description: Model catalog
          content:
            application/json:
              schema:
                type: object
                required: [default, models]
                properties:
                  default: {type: string}
                  models:
                    type: array
                    items:
                      type: object
                      required: [id, name, family]
                      properties:
                        id: {type: string}
                        name: {type: string}
                        family: {type: string}
                        credits: {type: string, example: x0.79}
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/assistant/sessions:
    get:
      tags: [Assistant]
      operationId: listAssistantSessions
      summary: List personal conversations and authorized shared SOP discussions
      description: Conversations persist in MySQL `assistant_sessions`. Personal conversations belong to the caller; shared SOP conversations belong to a run and require project access.
      responses:
        "200":
          description: Recent conversations without message bodies
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: {type: string}
                    title: {type: string}
                    projectId: {type: string}
                    model: {type: string}
                    shared: {type: boolean}
                    runId: {type: string}
                    generationStatus: {type: string}
                    generationId: {type: string, description: "Latest reply of the conversation"}
                    unread: {type: boolean, description: "The latest reply completed after the caller last opened the conversation (sidebar blue dot). Only for conversations the caller takes part in; replies that ended before read tracking existed are never unread."}
                    updatedAt: {type: string, format: date-time}
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/assistant/sessions/{id}/read:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
    post:
      tags: [Assistant]
      operationId: markAssistantSessionRead
      summary: Record the reply the caller has seen in a conversation
      description: Clears the conversation's unread mark for the caller on every device. Only the conversation's latest reply is recorded; an older generationId changes nothing and returns recorded=false. Stored in MySQL `assistant_session_reads`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [generationId]
              properties:
                generationId: {type: string, maxLength: 64}
      responses:
        "200":
          description: "`{ok: true, recorded: boolean}`"
        "400":
          description: Missing or invalid generationId
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{id}/conversation:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Assistant]
      operationId: getRunConversation
      summary: Open the shared conversation for one SOP run
      description: Requires project access. Every authorized member receives the same session, including user authorId/authorName and role speakerAgentId/speakerName. First open preserves existing run discussions. Model/tool calls use the caller's own credentials.
      responses:
        "200":
          description: Shared conversation with messages and updatedAt
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/assistant/sessions/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Assistant]
      operationId: getAssistantSession
      summary: Load one assistant conversation
      responses:
        "200":
          description: Conversation including messages
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      tags: [Assistant]
      operationId: putAssistantSession
      summary: Update one assistant conversation
      description: Persists draft execution receipts. Shared sessions require the last updatedAt, preserve existing message bodies and attribution, and reject edits during generation. Stored in MySQL `assistant_sessions`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id: {type: string}
                title: {type: string}
                projectId: {type: string}
                sandboxProfileId: {type: string, description: Initial Docker sandbox choice; empty follows project default}
                model: {type: string}
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role: {type: string}
                      content: {type: string}
      responses:
        "200":
          description: Conversation saved
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Assistant]
      operationId: deleteAssistantSession
      summary: Delete one assistant conversation
      description: Also removes the matching CodeBuddy CLI transcript under the user's private HOME.
      responses:
        "200":
          description: Conversation and CLI transcript deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/assistant/sessions/{id}/sandbox:
    parameters:
      - {name: id, in: path, required: true, schema: {type: string}}
    put:
      tags: [Assistant]
      operationId: setAssistantSessionSandbox
      summary: Select the Docker sandbox of an ordinary conversation
      description: The conversation owner must have project edit access. Select a project-owned or shared Docker sandbox; empty lets Main Bot choose when it opens the workspace, falling back to the platform generic-docker sandbox; never a host shell. A non-empty selection overrides Main Bot's choice. Generation in progress or a bound workspace returns 409. Existing workspace snapshots are immutable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sandboxProfileId]
              properties:
                sandboxProfileId: {type: string}
      responses:
        "200": {description: Updated conversation}
        "400": {$ref: "#/components/responses/BadRequest"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "409": {description: Generation active or workspace environment already frozen}
  /api/assistant/sessions/{id}/fork:
    post:
      tags: [Assistant]
      operationId: forkAssistantSession
      summary: Edit a user message and create a conversation branch
      description: Preserves the original conversation and all previously executed changes. Shared SOP branches remain visible to project members. Inherited drafts are read-only history. Stop an active generation before branching.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [messageIndex, content, updatedAt]
              properties:
                messageIndex:
                  type: integer
                  minimum: 0
                content:
                  type: string
                updatedAt:
                  type: string
                  format: date-time
      responses:
        "201":
          description: Created branch with parentSessionId, rootSessionId and forkMessageIndex
        "400":
          description: Invalid message or attachment
        "403":
          description: Conversation or project access denied
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Source conversation changed or generation still active
  /api/assistant/tasks:
    get:
      tags: [Assistant]
      operationId: listAssistantTasks
      summary: List the current user's assistant scheduled prompts
      description: |
        These tasks make the Studio assistant run a user-written prompt on an
        interval, scoped to one Studio project. They persist in MySQL
        `assistant_tasks` and are not TAPD/Gongfeng SOP schedule jobs. Each run
        starts a fresh CodeBuddy session and does not resume the previous run.
        During execution the server may invoke that project's HTTP MCP servers
        (for example TAPD) on the model's `mcpCalls`.
      parameters:
        - name: projectId
          in: query
          required: false
          schema: {type: string}
          description: When set, only tasks belonging to this project are returned.
      responses:
        "200":
          description: Assistant-owned scheduled prompts
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assistant]
      operationId: saveAssistantTask
      summary: Create or update an assistant scheduled prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, prompt, projectId]
              properties:
                id: {type: string}
                name: {type: string}
                prompt: {type: string}
                notifications: {type: array, maxItems: 3, items: {$ref: "#/components/schemas/NotificationBinding"}}
                intervalSec: {type: integer, minimum: 60, description: Used when cron is empty. Minimum 60 seconds.}
                cron: {type: string, description: Optional 5-field cron (minute hour day month weekday) in Asia/Shanghai. When set, intervalSec is ignored.}
                enabled: {type: boolean}
                model: {type: string, description: CodeBuddy model id used when the task runs}
                projectId: {type: string, description: Studio project that owns this assistant task}
      responses:
        "200":
          description: Saved task
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/assistant/tasks/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
    delete:
      tags: [Assistant]
      operationId: deleteAssistantTask
      summary: Delete an assistant scheduled prompt
      responses:
        "200":
          description: Task deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/assistant/tasks/{id}/run:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
    post:
      tags: [Assistant]
      operationId: runAssistantTask
      summary: Run an assistant scheduled prompt immediately
      responses:
        "202":
          description: Execution started
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          description: The user already has a generation in progress
  /api/capabilities:
    get:
      tags: [System]
      operationId: getCapabilities
      summary: List public REST and MCP operations
      responses:
        "200":
          description: Public operation manifest and MCP transports
          content:
            application/json:
              schema:
                type: object
                required: [operations, mcp]
                properties:
                  operations:
                    type: array
                    items:
                      type: object
                      required: [name, description, method, path, readOnly]
                      properties:
                        name: {type: string}
                        description: {type: string}
                        method: {type: string}
                        path: {type: string}
                        readOnly: {type: boolean}
                  mcp:
                    type: object
                    properties:
                      streamableHttp: {type: string}
                      stdioCommand: {type: string}
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/openapi.yaml:
    get:
      tags: [System]
      operationId: getOpenAPI
      summary: Read this OpenAPI 3.1 contract
      responses:
        "200":
          description: OpenAPI YAML
          content:
            application/yaml:
              schema: {type: string}
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/auth/photo/{spec}/{username}:
    get:
      tags: [System]
      operationId: getEmployeePhoto
      summary: Fetch a user avatar from the configured SSO photo service
      parameters:
        - name: spec
          in: path
          required: true
          description: Photo dimension (48, 100, 150, 500)
          schema: {type: integer, enum: [48, 100, 150, 500]}
        - name: username
          in: path
          required: true
          description: User login name (with or without .png)
          schema: {type: string}
      responses:
        "200":
          description: Avatar image binary
          headers:
            Cache-Control:
              schema: {type: string, example: "public, max-age=86400"}
          content:
            image/png:
              schema: {type: string, format: binary}
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          description: SSO photo service error
  /api/auth/tokens:
    get:
      tags: [System]
      operationId: listPersonalTokens
      summary: List tokens owned by the logged-in user
      security:
        - cookieAuth: []
      responses:
        "200":
          description: Token metadata; plaintext and hashes are never returned
          content:
            application/json:
              schema:
                type: array
                items: {$ref: "#/components/schemas/APIToken"}
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [System]
      operationId: createPersonalToken
      summary: Create a personal REST API and MCP token
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: {type: string, maxLength: 128}
                expiresInDays: {type: integer, minimum: 1, maximum: 365, default: 90}
      responses:
        "201":
          description: Plaintext token is returned once in this response
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: {type: string}
                  metadata: {$ref: "#/components/schemas/APIToken"}
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/auth/tokens/{tokenId}:
    delete:
      tags: [System]
      operationId: revokePersonalToken
      summary: Revoke one token owned by the logged-in user
      security:
        - cookieAuth: []
      parameters:
        - name: tokenId
          in: path
          required: true
          schema: {type: string}
      responses:
        "200":
          description: Token revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/bootstrap:
    get:
      tags: [System]
      operationId: getBootstrap
      summary: Load the complete Studio bootstrap catalog
      responses:
        "200":
          description: Bootstrap state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bootstrap"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/users:
    get:
      tags: [Users]
      operationId: listUsers
      summary: List users with credential values redacted
      responses:
        "200":
          description: User directory
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  /api/users/{id}/credentials:
    put:
      tags: [Users]
      operationId: updateOwnCredentials
      summary: Update model credentials for the current authenticated user
      description: Git access tokens are managed through /api/users/{id}/git-http-credentials.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: integer, format: int64}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                codeBuddyApiKey: {type: string, writeOnly: true}
                codeBuddyApiKeyClear: {type: boolean}
                codeBuddyInternetEnvironment: {type: string, description: "Edition that issued the CodeBuddy key: empty for International, \"internal\" for China, \"ioa\" for iOA (\"public\" and \"China\" are also accepted). Any other value is rejected with 400."}
                codexApiKey: {type: string, writeOnly: true, description: "Blank preserves the stored key."}
                codexApiKeyClear: {type: boolean}
                codexBaseUrl: {type: string, description: "HTTP(S) Responses API base URL. Omitted preserves the value; empty uses the official endpoint."}
                claudeCodeApiKey: {type: string, writeOnly: true, description: "Blank preserves the stored key."}
                claudeCodeApiKeyClear: {type: boolean}
                claudeCodeBaseUrl: {type: string, description: "HTTP(S) Anthropic-compatible service URL. Omitted preserves the value; empty uses the official endpoint."}
      responses:
        "200":
          description: Redacted saved user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "403":
          $ref: "#/components/responses/Unauthorized"
  /api/platform/accounts:
    get:
      tags: [Users]
      operationId: listPlatformAccounts
      summary: List accounts for platform administrators
      responses:
        "200":
          description: Accounts, oldest first, and whether self sign-up is enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts: {type: array, items: {$ref: "#/components/schemas/PlatformAccount"}}
                  signupEnabled: {type: boolean}
        "403": {description: Platform administrator access required}
    post:
      tags: [Users]
      operationId: createPlatformAccount
      summary: Create a password account
      description: Platform administrators only. Browser requests must be same-origin; API tokens are accepted. The account joins the welcome project.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [loginName, password]
              properties:
                loginName: {type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9_.-]{1,63}$"}
                password: {type: string, writeOnly: true, minLength: 6, maxLength: 72}
                admin: {type: boolean, description: Also grant platform administration}
      responses:
        "201":
          description: Created account
          content:
            application/json:
              schema: {$ref: "#/components/schemas/PlatformAccount"}
        "400": {description: Invalid login name or password}
        "403": {description: Platform administrator access or same-origin request required}
        "409": {description: Login name already taken}
  /api/platform/accounts/{id}/password:
    put:
      tags: [Users]
      operationId: resetPlatformAccountPassword
      summary: Set a new password for a password account
      description: Platform administrators only. Accounts that sign in through GitHub or a gateway are refused with 400, so this never adds a password login to them.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: integer, format: int64}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [password]
              properties:
                password: {type: string, writeOnly: true, minLength: 6, maxLength: 72}
      responses:
        "200":
          description: Account
          content:
            application/json:
              schema: {$ref: "#/components/schemas/PlatformAccount"}
        "400": {description: Invalid password or not a password account}
        "403": {description: Platform administrator access or same-origin request required}
        "404": {description: Unknown account}
  /api/platform/codebuddy-key:
    get:
      tags: [Users]
      operationId: getPlatformCodeBuddyKey
      summary: Show the shared CodeBuddy API Key settings
      description: Platform administrators only. The key itself is never returned.
      parameters:
        - name: environment
          in: query
          description: Network environment whose models to list in catalog; defaults to the saved one.
          schema: {type: string, enum: ["", internal, ioa]}
      responses:
        "200":
          description: Shared key status and the models offered in the environment
          content:
            application/json:
              schema: {$ref: "#/components/schemas/PlatformCodeBuddyKey"}
        "403": {description: Platform administrator access required}
    put:
      tags: [Users]
      operationId: savePlatformCodeBuddyKey
      summary: Share a CodeBuddy API Key with users who have none
      description: >-
        Platform administrators only; browser requests must be same-origin. Users without their own key
        chat and run SOPs on this key, limited to models (the first is the default). It replaces the
        AGENTFLOW_ASSISTANT_SPONSOR_LOGIN account while configured.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [models]
              properties:
                apiKey: {type: string, writeOnly: true, description: Blank keeps the stored key.}
                internetEnvironment: {type: string, description: "Empty for International, \"internal\" for China, \"ioa\" for iOA."}
                models: {type: array, minItems: 1, maxItems: 32, items: {type: string}}
      responses:
        "200":
          description: Saved settings
          content:
            application/json:
              schema: {$ref: "#/components/schemas/PlatformCodeBuddyKey"}
        "400": {description: Missing key or models, or an invalid environment or model ID}
        "403": {description: Platform administrator access or same-origin request required}
    delete:
      tags: [Users]
      operationId: clearPlatformCodeBuddyKey
      summary: Stop sharing the CodeBuddy API Key
      responses:
        "200":
          description: Settings after clearing
          content:
            application/json:
              schema: {$ref: "#/components/schemas/PlatformCodeBuddyKey"}
        "403": {description: Platform administrator access or same-origin request required}
  /api/business-domains:
    get:
      tags: [BusinessDomains]
      operationId: listBusinessDomains
      responses:
        "200":
          description: Domain catalog, per-domain canManage/canView, canAdmin and userId
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        domain: {$ref: "#/components/schemas/BusinessDomain"}
                        canManage: {type: boolean}
                        canView: {type: boolean}
                  canAdmin: {type: boolean}
                  userId: {type: integer, format: int64}
        "401": {$ref: "#/components/responses/Unauthorized"}
    put:
      tags: [BusinessDomains]
      operationId: saveBusinessDomain
      parameters:
        - name: createOnly
          in: query
          description: Reject an existing ID with 409 instead of updating it.
          schema: {type: boolean, default: false}
      description: Platform admins create and enable/disable domains and assign managers. Domain managers may edit names, descriptions and viewers. Duplicate names or concurrent updates return 409.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: "#/components/schemas/BusinessDomain"}
      responses:
        "200":
          description: Saved domain
          content:
            application/json:
              schema: {$ref: "#/components/schemas/BusinessDomain"}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {description: Caller cannot manage this domain or change protected grants}
        "409": {description: Duplicate name or concurrent update}
  /api/business-domain-report:
    get:
      tags: [BusinessDomains]
      operationId: getBusinessDomainReport
      description: Aggregate only. Queries always resolve current project attribution; historical runs follow the current domain. All means the caller's authorized reporting scope. Unclassified projects are visible to their owners and platform admins.
      parameters:
        - name: businessDomainId
          in: query
          schema: {type: string, default: all}
          description: Domain ID, all, or unclassified
        - name: from
          in: query
          schema: {type: string, format: date-time}
        - name: to
          in: query
          schema: {type: string, format: date-time}
        - name: grain
          in: query
          schema: {type: string, enum: [day, week, month], default: day}
        - name: timeZone
          in: query
          schema: {type: string, default: UTC}
          description: IANA timezone for delivery and MR trend buckets, for example Asia/Shanghai. Run usage trends retain their existing UTC buckets.
      responses:
        "200":
          description: Current-attribution summary, delivery summary, trend, project contributions and business-domain distribution; excludes run, user and log details
          content:
            application/json:
              schema: {$ref: "#/components/schemas/BusinessDomainReport"}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {description: Domain aggregate access not granted}
        "404": {$ref: "#/components/responses/NotFound"}
  /api/projects/{projectId}/business-domain:
    parameters:
      - name: projectId
        in: path
        required: true
        schema: {type: string}
    put:
      tags: [BusinessDomains]
      operationId: assignProjectBusinessDomain
      description: Owners can assign an unclassified project. Platform admins can transfer or clear an assignment. Target must be active. Compare-and-swap protects against concurrent reassignment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [businessDomainId, expectedDomainId]
              properties:
                businessDomainId: {type: string, description: 'Empty string clears the assignment'}
                expectedDomainId: {type: string, description: 'Previously observed assignment; empty for unclassified'}
                reason: {type: string, maxLength: 500}
      responses:
        "200": {$ref: "#/components/responses/Project"}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {description: Owner or platform admin access required}
        "404": {$ref: "#/components/responses/NotFound"}
        "409": {description: Project assignment changed; refresh before retrying}
  /api/projects/{projectId}/business-domain/history:
    parameters:
      - name: projectId
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [BusinessDomains]
      operationId: getProjectBusinessDomainHistory
      responses:
        "200":
          description: Last 100 assignment changes, newest first
          content:
            application/json:
              schema:
                type: array
                items: {$ref: "#/components/schemas/BusinessDomainAssignment"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {description: Project owner or platform admin access required}
        "404": {$ref: "#/components/responses/NotFound"}
  /api/projects:
    get:
      tags: [Projects]
      operationId: listProjects
      responses:
        "200":
          $ref: "#/components/responses/ProjectList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Projects]
      operationId: createProject
      requestBody:
        $ref: "#/components/requestBodies/Project"
      responses:
        "200":
          $ref: "#/components/responses/Project"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Projects]
      operationId: upsertProject
      requestBody:
        $ref: "#/components/requestBodies/Project"
      responses:
        "200":
          $ref: "#/components/responses/Project"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/projects/{projectId}:
    parameters:
      - name: projectId
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Projects]
      operationId: getProject
      responses:
        "200":
          $ref: "#/components/responses/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Projects]
      operationId: deleteProject
      description: >-
        Delete (archive) a project; owner or platform admin. The project leaves
        project lists and syncs, its requirements, runs and settings are kept
        and the id stays taken. 409 while it has unfinished runs or enabled
        schedule jobs.
      responses:
        "200":
          $ref: "#/components/responses/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/projects/{projectId}/restore:
    parameters:
      - name: projectId
        in: path
        required: true
        schema: {type: string}
    post:
      tags: [Projects]
      operationId: restoreProject
      description: Restore a deleted project; owner or platform admin.
      responses:
        "200":
          $ref: "#/components/responses/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/repositories:
    get:
      tags: [Repositories]
      operationId: listRepositories
      responses:
        "200":
          description: Repository list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Repository"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Repositories]
      operationId: createRepository
      requestBody:
        $ref: "#/components/requestBodies/Repository"
      responses:
        "200":
          $ref: "#/components/responses/Repository"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Repositories]
      operationId: upsertRepository
      requestBody:
        $ref: "#/components/requestBodies/Repository"
      responses:
        "200":
          $ref: "#/components/responses/Repository"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Repositories]
      operationId: deleteRepository
      parameters:
        - $ref: "#/components/parameters/RepositoryIdQuery"
      responses:
        "200":
          $ref: "#/components/responses/Status"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/repositories/{repositoryId}:
    parameters:
      - name: repositoryId
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Repositories]
      operationId: getRepository
      responses:
        "200":
          $ref: "#/components/responses/Repository"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/issues:
    get:
      tags: [Issues]
      operationId: listIssues
      parameters:
        - name: projectId
          in: query
          required: false
          schema: {type: string}
          description: When set, only issues belonging to this project are returned.
        - name: status
          in: query
          required: false
          schema: {type: string}
          description: Filter by issue status. Comma-separated values are OR-matched.
        - name: source
          in: query
          required: false
          schema: {type: string}
          description: Filter by source (local, gongfeng, tapd). Comma-separated values are OR-matched.
        - name: q
          in: query
          required: false
          schema: {type: string}
          description: Case-insensitive match against title, id, number, or external id.
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 200}
          description: When omitted, the response is Issue[]. When set, the response is a page object and limit is capped at 200.
        - name: offset
          in: query
          required: false
          schema: {type: integer, minimum: 0}
      responses:
        "200":
          description: Issue list, or a page when limit is set
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: "#/components/schemas/Issue"
                  - $ref: "#/components/schemas/IssueListPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Issues]
      operationId: createIssue
      requestBody:
        $ref: "#/components/requestBodies/Issue"
      responses:
        "200":
          $ref: "#/components/responses/Issue"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Issues]
      operationId: upsertIssue
      requestBody:
        $ref: "#/components/requestBodies/Issue"
      responses:
        "200":
          $ref: "#/components/responses/Issue"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/issues/import-tapd:
    post:
      tags: [Issues]
      operationId: importTAPDIssue
      summary: Import one TAPD story, bug or task from a pasted link
      description: Imports the work item as-is. Clarification is optional and never started automatically; the item can be dispatched right away.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [projectId, url]
              properties:
                projectId: {type: string}
                url: {type: string, description: TAPD story/bug/task detail URL or shared title and link; multiple different work items are rejected}
                baseBranch: {type: string, description: Existing work branch to continue directly for a single repository; empty creates a new work branch from its configured main branch; omitted preserves the selection when reimporting with the same repositories}
                repositoryBranches:
                  type: object
                  additionalProperties: {type: string}
                  description: Existing work branches keyed by bound repository ID; overrides baseBranch. Empty or unlisted branches create new work branches from each repository's configured main branch. Omitted preserves selections for retained repositories on reimport; an empty object clears all selections.
                workflowId: {type: string, description: SOP to bind on import; omitted uses the project default requirement workflow}
                repositoryId: {type: string, description: Primary repository; at least one of repositoryId or repositoryIds is required}
                repositoryIds:
                  type: array
                  items: {type: string}
                  description: Repositories to bind; import is rejected if none are selected
      responses:
        "200":
          $ref: "#/components/responses/Issue"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/issues/{issueId}/resync-tapd:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    post:
      tags: [Issues]
      operationId: resyncTAPDIssue
      summary: Re-sync one TAPD-sourced issue from TAPD
      description: Pulls the linked TAPD story/bug/task again and refreshes the local issue content (title/description/status/priority). Local assignee, clarification state, base branch and repository bindings are preserved. Only issues with source=tapd are accepted.
      responses:
        "200":
          $ref: "#/components/responses/Issue"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/issues/{issueId}:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    get:
      tags: [Issues]
      operationId: getIssue
      responses:
        "200":
          description: Issue and comments
          content:
            application/json:
              schema:
                type: object
                required: [issue, comments]
                properties:
                  issue:
                    $ref: "#/components/schemas/Issue"
                  comments:
                    type: array
                    items:
                      $ref: "#/components/schemas/IssueComment"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Issues]
      operationId: deleteIssue
      summary: Delete a local requirement
      description: Deletes the issue, clarification, comments and failed/cancelled tasks, runs, logs, artifacts, previews and execution environments. Successful or active executions prevent deletion. The external tracker record is retained and sync may import the issue again.
      responses:
        "204":
          description: Local issue deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Issue has successful execution history or is clarifying or executing a SOP
  /api/issues/{issueId}/comments:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    post:
      tags: [Issues]
      operationId: createIssueComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssueComment"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/issues/{issueId}/runs:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    get:
      tags: [Issues, Runs]
      operationId: listIssueRuns
      responses:
        "200":
          $ref: "#/components/responses/RunList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/issues/{issueId}/chat-clarify:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    get:
      tags: [Issues]
      operationId: attachIssueClarify
      description: Attach to an in-flight server-side clarification job and replay thought events over SSE.
      responses:
        "200":
          description: Server-Sent Events stream
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags: [Issues]
      operationId: chatClarifyIssue
      description: Starts a server-side clarification job that keeps running after the client disconnects. Returns JSON normally, or an SSE stream when Accept is text/event-stream.
      requestBody:
        $ref: "#/components/requestBodies/ChatClarify"
      responses:
        "200":
          $ref: "#/components/responses/ClarifyResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
  /api/issues/{issueId}/chat-clarify/cancel:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    post:
      tags: [Issues]
      operationId: cancelIssueClarify
      description: Cancel one issue's in-flight server-side clarification job.
      responses:
        "200":
          description: Cancellation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancelled:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"
  /api/issues/{issueId}/clarification:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    post:
      tags: [Issues]
      operationId: saveIssueClarification
      description: Persists one work item's multi-turn clarification. When ready, appends the summary to its linked Gongfeng Issue or TAPD story as a comment without starting its SOP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                summary:
                  type: string
                ready:
                  type: boolean
                history:
                  type: array
                  items:
                    $ref: "#/components/schemas/ClarificationMessage"
                questions:
                  type: array
                  items:
                    $ref: "#/components/schemas/ClarificationQuestion"
                retry:
                  type: boolean
      responses:
        "200":
          $ref: "#/components/responses/Issue"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/issues/{issueId}/reopen:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    post:
      tags: [Issues]
      operationId: reopenIssue
      responses:
        "200":
          $ref: "#/components/responses/Issue"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/issues/{issueId}/dispatch:
    parameters:
      - $ref: "#/components/parameters/IssueId"
    post:
      tags: [Issues, Tasks]
      operationId: dispatchIssue
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rerun:
                  type: boolean
                  default: false
      responses:
        "201":
          description: Task created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/chat-clarify:
    post:
      tags: [Issues]
      operationId: chatClarifyDraft
      description: Clarify an unsaved issue; supports JSON or SSE based on Accept.
      requestBody:
        $ref: "#/components/requestBodies/ChatClarify"
      responses:
        "200":
          $ref: "#/components/responses/ClarifyResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/ServerError"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
  /api/chat-clarify/cancel:
    post:
      tags: [Issues]
      operationId: cancelChatClarification
      responses:
        "200":
          description: Cancellation result
          content:
            application/json:
              schema:
                type: object
                required: [cancelled]
                properties:
                  cancelled:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/tasks:
    get:
      tags: [Tasks]
      operationId: listTasks
      responses:
        "200":
          description: Task list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Task"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/tasks/{taskId}:
    parameters:
      - name: taskId
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Tasks]
      operationId: getTask
      responses:
        "200":
          description: Task
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/agents:
    get:
      tags: [Assets]
      operationId: listAgents
      parameters:
        - name: projectId
          in: query
          required: false
          schema:
            type: string
          description: Return roles owned by this project plus roles explicitly shared by other projects.
      responses:
        "200":
          description: Agent definitions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AgentDefinition"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assets]
      operationId: upsertAgent
      requestBody:
        $ref: "#/components/requestBodies/Agent"
      responses:
        "200":
          description: Stored agent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentDefinition"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/agents/{agentId}:
    parameters:
      - $ref: "#/components/parameters/AgentId"
    get:
      tags: [Assets]
      operationId: getAgent
      responses:
        "200":
          description: Agent definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentDefinition"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Assets]
      operationId: deleteAgent
      summary: Delete an Agent definition that is not shared and not referenced by any workflow
      responses:
        "204":
          description: Agent deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/agents/{agentId}/revisions:
    parameters:
      - $ref: "#/components/parameters/AgentId"
    get:
      tags: [Assets]
      operationId: listAgentRevisions
      responses:
        "200":
          $ref: "#/components/responses/RevisionList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/agents/{agentId}/revisions/{revisionId}:
    parameters:
      - $ref: "#/components/parameters/AgentId"
      - $ref: "#/components/parameters/RevisionId"
    get:
      tags: [Assets]
      operationId: getAgentRevision
      responses:
        "200":
          description: Agent definition revision
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefinitionRevision"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/agents/{agentId}/revisions/{revisionId}/restore:
    parameters:
      - $ref: "#/components/parameters/AgentId"
      - $ref: "#/components/parameters/RevisionId"
    post:
      tags: [Assets]
      operationId: restoreAgentRevision
      responses:
        "200":
          description: Restored agent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentDefinition"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/rules:
    get:
      tags: [Assets]
      operationId: listRules
      responses:
        "200":
          $ref: "#/components/responses/AssetList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assets]
      operationId: upsertRule
      requestBody:
        $ref: "#/components/requestBodies/RuleAsset"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Assets]
      operationId: deleteRule
      summary: Delete a Rule that is not shared and not referenced by any agent
      parameters:
        - $ref: "#/components/parameters/AssetIdQuery"
      responses:
        "204":
          description: Rule deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/skills:
    get:
      tags: [Assets]
      operationId: listSkills
      responses:
        "200":
          $ref: "#/components/responses/AssetList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assets]
      operationId: upsertSkill
      requestBody:
        $ref: "#/components/requestBodies/SkillAsset"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Assets]
      operationId: deleteSkill
      summary: Delete a Skill that is not shared and not referenced by any agent
      parameters:
        - $ref: "#/components/parameters/AssetIdQuery"
      responses:
        "204":
          description: Skill deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/skillhub/skills:
    get:
      tags: [Assets]
      operationId: listSkillhubSkills
      summary: Search public SkillHub skills through the platform proxy
      description: Only whitelisted query parameters are forwarded. SkillHub failures map to 429 (rate limited), 502 (unavailable) or 504 (timeout).
      parameters:
        - {name: keyword, in: query, schema: {type: string, maxLength: 100}}
        - {name: category, in: query, schema: {type: string}}
        - {name: sortBy, in: query, schema: {type: string, enum: [downloads, score, updated_at], default: downloads}}
        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
        - {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 50, default: 24}}
      responses:
        "200":
          description: "{total, page, pageSize, items:[{slug, namespace, name, description, iconUrl, category, version, ownerName, homepage, downloads, stars, labels, verified, updatedAt}]}"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/SkillhubUnavailable"
        "502":
          $ref: "#/components/responses/SkillhubUnavailable"
        "504":
          $ref: "#/components/responses/SkillhubUnavailable"
  /api/skillhub/categories:
    get:
      tags: [Assets]
      operationId: listSkillhubCategories
      summary: Active SkillHub top-level categories, cached for 10 minutes
      responses:
        "200":
          description: "{items:[{key, name}]}"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "502":
          $ref: "#/components/responses/SkillhubUnavailable"
  /api/skillhub/skills/{slug}:
    parameters:
      - $ref: "#/components/parameters/SkillhubSlug"
      - $ref: "#/components/parameters/SkillhubNamespace"
    get:
      tags: [Assets]
      operationId: getSkillhubSkill
      responses:
        "200":
          description: "{skill, latestVersion, owner, securityReports}"
        "404":
          $ref: "#/components/responses/NotFound"
        "502":
          $ref: "#/components/responses/SkillhubUnavailable"
  /api/skillhub/skills/{slug}/versions:
    parameters:
      - $ref: "#/components/parameters/SkillhubSlug"
      - $ref: "#/components/parameters/SkillhubNamespace"
    get:
      tags: [Assets]
      operationId: listSkillhubSkillVersions
      responses:
        "200":
          description: "{versions:[{version, changelog, createdAt, securityReports?:{<vendor>:{status, statusText, reportUrl, safe}}}]}"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/skillhub/skills/{slug}/files:
    parameters:
      - $ref: "#/components/parameters/SkillhubSlug"
      - $ref: "#/components/parameters/SkillhubNamespace"
      - $ref: "#/components/parameters/SkillhubVersion"
    get:
      tags: [Assets]
      operationId: listSkillhubSkillFiles
      responses:
        "200":
          description: "{version, files:[{path, size, sha256}]}"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/skillhub/skills/{slug}/file:
    parameters:
      - $ref: "#/components/parameters/SkillhubSlug"
      - $ref: "#/components/parameters/SkillhubNamespace"
      - $ref: "#/components/parameters/SkillhubVersion"
      - {name: path, in: query, required: true, schema: {type: string}}
    get:
      tags: [Assets]
      operationId: previewSkillhubSkillFile
      summary: Text preview of one package file
      description: The server follows the signed download redirect itself; signed storage URLs are never returned. Files over 1MB or non UTF-8 content return previewable=false.
      responses:
        "200":
          description: "{path, size, previewable:true, content} or {path, previewable:false, reason}"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/skillhub/skills/{slug}/evaluation:
    parameters:
      - $ref: "#/components/parameters/SkillhubSlug"
      - $ref: "#/components/parameters/SkillhubNamespace"
    get:
      tags: [Assets]
      operationId: getSkillhubSkillEvaluation
      responses:
        "200":
          description: "{available:true, dimensions, summary, userSummary, updatedAt} or {available:false} when SkillHub has no evaluation"
  /api/skillhub/install:
    post:
      tags: [Assets]
      operationId: installSkillhubSkill
      summary: Download a SkillHub package and store it as a project skill
      description: Files and the skill row are written in one transaction; any failure leaves no partial skill. The new skill records source {provider, namespace, slug, version, homepage, installedAt, updatedAt} and its files are read-only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slug, projectId]
              properties:
                slug: {type: string}
                namespace: {type: string}
                version: {type: string, description: Defaults to the latest version}
                projectId: {type: string}
                id: {type: string, description: Defaults to slug}
                name: {type: string}
      responses:
        "201":
          description: Installed SkillDefinition
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/SkillhubUnavailable"
        "502":
          $ref: "#/components/responses/SkillhubUnavailable"
        "504":
          $ref: "#/components/responses/SkillhubUnavailable"
  /api/skillhub/update:
    post:
      tags: [Assets]
      operationId: updateSkillhubSkill
      summary: Replace a SkillHub-sourced skill's files with another version
      description: Keeps id, name, description, sharing and agent bindings; a failure leaves the existing files untouched.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [skillId]
              properties:
                skillId: {type: string}
                version: {type: string, description: Defaults to the latest version}
      responses:
        "200":
          description: Updated SkillDefinition
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/SkillhubUnavailable"
        "502":
          $ref: "#/components/responses/SkillhubUnavailable"
  /api/mcp-servers:
    get:
      tags: [Assets]
      operationId: listMcpServers
      responses:
        "200":
          $ref: "#/components/responses/AssetList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assets]
      operationId: upsertMcpServer
      requestBody:
        $ref: "#/components/requestBodies/MCPServerAsset"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/mcp-servers/import:
    post:
      tags: [Assets]
      operationId: importMcpServers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: MCP object, array, keyed map, or mcpServers/servers envelope.
      responses:
        "200":
          description: Import result
          content:
            application/json:
              schema:
                type: object
                required: [imported, servers]
                properties:
                  imported:
                    type: integer
                  servers:
                    type: array
                    items:
                      $ref: "#/components/schemas/OpenObject"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/mcp-servers/{id}/files:
    post:
      tags: [Assets]
      operationId: uploadMcpFiles
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string}
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items: {type: string, format: binary}
                paths:
                  type: array
                  items: {type: string}
      responses:
        "200": {description: Updated MCP definition}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "404": {$ref: "#/components/responses/NotFound"}
  /api/mcp-servers/{id}/files/{path}:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
      - name: path
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Assets]
      operationId: downloadMcpFile
      responses:
        "200": {description: MCP file content}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "404": {$ref: "#/components/responses/NotFound"}
    delete:
      tags: [Assets]
      operationId: deleteMcpFile
      responses:
        "200": {description: Updated MCP definition}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "404": {$ref: "#/components/responses/NotFound"}
  /api/executors:
    get:
      tags: [Assets]
      operationId: listExecutors
      description: Returns the read-only built-in CLI catalog. Executors are not user-configurable.
      responses:
        "200":
          $ref: "#/components/responses/AssetList"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/executor-models:
    get:
      tags: [Assets]
      operationId: listExecutorModels
      description: Returns, per built-in CLI, the selectable model IDs, the default model and the reasoning-effort levels. An Agent's model should be one of these IDs.
      responses:
        "200":
          description: Model catalog keyed by CLI id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenObject"
  /api/dockerfiles:
    get:
      tags: [Assets]
      operationId: listDockerfiles
      responses:
        "200":
          $ref: "#/components/responses/AssetList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assets]
      operationId: upsertDockerfile
      requestBody:
        $ref: "#/components/requestBodies/DockerfileAsset"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Assets]
      operationId: deleteDockerfile
      summary: Delete a Dockerfile that is not shared and not referenced by any sandbox
      parameters:
        - $ref: "#/components/parameters/AssetIdQuery"
      responses:
        "204":
          description: Dockerfile deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/environments:
    get:
      tags: [Assets]
      operationId: listEnvironments
      responses:
        "200":
          $ref: "#/components/responses/AssetList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assets]
      operationId: upsertEnvironment
      requestBody:
        $ref: "#/components/requestBodies/EnvironmentAsset"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Assets]
      operationId: deleteEnvironment
      summary: Delete an environment install script that is not shared and not referenced by any sandbox
      parameters:
        - $ref: "#/components/parameters/AssetIdQuery"
      responses:
        "204":
          description: Environment deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/sandboxes:
    get:
      tags: [Assets]
      operationId: listSandboxProfiles
      responses:
        "200":
          $ref: "#/components/responses/AssetList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Assets]
      operationId: upsertSandboxProfile
      requestBody:
        $ref: "#/components/requestBodies/SandboxProfile"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Assets]
      operationId: deleteSandbox
      summary: Delete a sandbox profile that is not shared and not referenced by any workflow
      parameters:
        - $ref: "#/components/parameters/AssetIdQuery"
      responses:
        "204":
          description: Sandbox profile deleted
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/workflows:
    get:
      tags: [Workflows]
      operationId: listWorkflows
      responses:
        "200":
          $ref: "#/components/responses/WorkflowList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Workflows]
      operationId: upsertWorkflow
      requestBody:
        $ref: "#/components/requestBodies/Workflow"
      responses:
        "200":
          $ref: "#/components/responses/Workflow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/workflows/{workflowId}:
    parameters:
      - $ref: "#/components/parameters/WorkflowId"
    get:
      tags: [Workflows]
      operationId: getWorkflow
      responses:
        "200":
          $ref: "#/components/responses/Workflow"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Workflows]
      operationId: deleteWorkflow
      responses:
        "204":
          description: Workflow deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/workflows/{workflowId}/revisions:
    parameters:
      - $ref: "#/components/parameters/WorkflowId"
    get:
      tags: [Workflows]
      operationId: listWorkflowRevisions
      responses:
        "200":
          $ref: "#/components/responses/RevisionList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/workflows/{workflowId}/revisions/{revisionId}:
    parameters:
      - $ref: "#/components/parameters/WorkflowId"
      - $ref: "#/components/parameters/RevisionId"
    get:
      tags: [Workflows]
      operationId: getWorkflowRevision
      responses:
        "200":
          description: Workflow revision
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefinitionRevision"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/workflows/{workflowId}/revisions/{revisionId}/restore:
    parameters:
      - $ref: "#/components/parameters/WorkflowId"
      - $ref: "#/components/parameters/RevisionId"
    post:
      tags: [Workflows]
      operationId: restoreWorkflowRevision
      responses:
        "200":
          $ref: "#/components/responses/Workflow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/workflows/{workflowId}/publish:
    parameters:
      - $ref: "#/components/parameters/WorkflowId"
    post:
      tags: [Workflows]
      operationId: publishWorkflow
      responses:
        "200":
          $ref: "#/components/responses/Workflow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/workflows/{workflowId}/clone:
    parameters:
      - $ref: "#/components/parameters/WorkflowId"
    post:
      tags: [Workflows]
      operationId: cloneWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, name]
              properties:
                id:
                  type: string
                name:
                  type: string
                owner:
                  type: string
                projectId:
                  type: string
                  description: Target project. Empty or omitted retains the source project; generic templates require a target project.
      responses:
        "201":
          $ref: "#/components/responses/Workflow"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/workflow-metrics:
    get:
      tags: [Analytics]
      operationId: listWorkflowMetrics
      responses:
        "200":
          description: Workflow metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkflowMetrics"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/analytics:
    get:
      tags: [Analytics]
      operationId: getAnalytics
      parameters:
        - name: projectId
          in: query
          schema:
            type: string
        - name: workflowId
          in: query
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Analytics snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalyticsSnapshot"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/observability/spec:
    get:
      tags: [Analytics]
      operationId: getObservabilitySpec
      responses:
        "200":
          description: Public observability vocabulary and adapters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenObject"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/runs:
    get:
      tags: [Runs]
      operationId: listRuns
      responses:
        "200":
          $ref: "#/components/responses/RunList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Runs]
      operationId: startRun
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [workflowId]
              properties:
                workflowId:
                  type: string
                input:
                  type: string
                projectId:
                  type: string
      responses:
        "201":
          $ref: "#/components/responses/Run"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /api/runs/{runId}:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: getRun
      responses:
        "200":
          $ref: "#/components/responses/Run"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Runs]
      operationId: deleteRun
      responses:
        "200":
          $ref: "#/components/responses/Status"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/preview/download:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: downloadRunPreview
      description: Download the archived static build as a ZIP with original files and relative paths. Available after workspace cleanup and until preview expiry; does not require a preview session. Supports HTTP Range requests.
      responses:
        "200":
          description: Complete static site ZIP attachment
          content:
            application/zip:
              schema: {type: string, format: binary}
        "206":
          description: Requested range of the ZIP attachment
          content:
            application/zip:
              schema: {type: string, format: binary}
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Preview has not finished archiving
        "410":
          description: Preview has expired or been deleted
        "500":
          $ref: "#/components/responses/ServerError"
  /api/runs/{runId}/telemetry:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs, Analytics]
      operationId: listRunTelemetry
      parameters:
        - $ref: "#/components/parameters/NodeIdQuery"
        - name: adapter
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/After"
        - $ref: "#/components/parameters/Before"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Cursor-paged telemetry
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TelemetryPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/logs:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: listRunLogs
      parameters:
        - $ref: "#/components/parameters/NodeIdQuery"
        - $ref: "#/components/parameters/After"
        - $ref: "#/components/parameters/Before"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Cursor-paged logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LogPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/logs.txt:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: downloadRunLogs
      parameters:
        - $ref: "#/components/parameters/NodeIdQuery"
      responses:
        "200":
          description: Plain-text worker log export
          content:
            text/plain:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/workspace/terminal:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: controlRunWorkspaceTerminal
      summary: Open, poll, type into, resize or close a workspace PTY
      description: Requires project write membership and an active human editor lease. Shells run on the workspace owner with a sanitized environment; a disconnected client is reclaimed after 15 seconds. Terminal data is transient and output is base64 encoded.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [operation]
              properties:
                operation: {type: string, enum: [open, read, input, resize, close]}
                id: {type: string}
                data: {type: string, maxLength: 32768}
                cols: {type: integer}
                rows: {type: integer}
      responses:
        "200":
          description: Terminal identifier and new output
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: {type: string}
                  data: {type: string, format: byte}
                  exited: {type: boolean}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "409": {description: Execution not stopped, editor lease expired, foreign terminal, or workspace unavailable}
  /api/runs/{runId}/workspace:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: getRunWorkspace
      summary: Inspect availability and Git changes for the read-only Run workspace
      responses:
        "200":
          description: Workspace availability and change summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunWorkspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/workspace/restore:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: getRunWorkspaceRestoreStatus
      summary: Inspect background workspace restoration independently of SOP execution
      responses:
        "200":
          description: Restore status (idle, restoring, ready or failed), optional startedAt and error
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags: [Runs]
      operationId: restoreRunWorkspace
      parameters:
        - in: header
          name: Prefer
          schema:
            type: string
            example: respond-async
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "202":
          description: Background restoration accepted; poll GET on this path
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/runs/{runId}/workspace/tree:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: listRunWorkspaceTree
      summary: List safe, non-sensitive files in a Run workspace
      parameters:
        - name: path
          in: query
          schema: {type: string}
      responses:
        "200":
          description: Flat workspace tree, capped at 4000 entries
          content:
            application/json:
              schema:
                type: object
                required: [entries, truncated]
                properties:
                  entries:
                    type: array
                    items: {$ref: "#/components/schemas/WorkspaceEntry"}
                  truncated: {type: boolean}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "404": {$ref: "#/components/responses/NotFound"}
        "409": {description: Workspace is unavailable because its owner instance or remote Runner cannot currently be reached}
        "410": {description: Workspace is no longer available}
  /api/runs/{runId}/workspace/file:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: getRunWorkspaceFile
      summary: Preview one text file from a Run workspace
      parameters:
        - name: path
          in: query
          required: true
          schema: {type: string}
      responses:
        "200":
          description: Text file content, limited to 1 MiB
          content:
            application/json:
              schema:
                type: object
                required: [path, content, size]
                properties:
                  path: {type: string}
                  content: {type: string}
                  size: {type: integer, format: int64}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "404": {$ref: "#/components/responses/NotFound"}
        "409": {description: Workspace is unavailable because its owner instance or remote Runner cannot currently be reached}
        "410": {description: Workspace is no longer available}
  /api/runs/{runId}/workspace/diff:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: getRunWorkspaceDiff
      summary: Read the working-tree diff against HEAD
      parameters:
        - name: path
          in: query
          schema: {type: string}
      responses:
        "200":
          description: Git diff plus base and working-tree content for a file, capped at 1 MiB
          content:
            application/json:
              schema:
                type: object
                required: [diff, truncated]
                properties:
                  diff: {type: string}
                  original: {type: string, description: File content at HEAD when path is provided}
                  modified: {type: string, description: Current workspace content when path is provided}
                  truncated: {type: boolean}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "404": {$ref: "#/components/responses/NotFound"}
        "409": {description: Workspace is unavailable because its owner instance or remote Runner cannot currently be reached}
        "410": {description: Workspace is no longer available}
  /api/runs/{runId}/workspace/search:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: searchRunWorkspace
      summary: Search text content in safe, bounded workspace files
      parameters:
        - name: q
          in: query
          required: true
          schema: {type: string, minLength: 2}
      responses:
        "200":
          description: Up to 100 matching lines from at most 20 MiB of text files
          content:
            application/json:
              schema:
                type: object
                required: [results, truncated]
                properties:
                  results:
                    type: array
                    items: {$ref: "#/components/schemas/WorkspaceSearchResult"}
                  truncated: {type: boolean}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "404": {$ref: "#/components/responses/NotFound"}
        "409": {description: Workspace is unavailable because its owner instance or remote Runner cannot currently be reached}
        "410": {description: Workspace is no longer available}
  /api/runs/{runId}/stream:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: streamRun
      parameters:
        - $ref: "#/components/parameters/After"
        - name: logsAfter
          in: query
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: SSE run updates with run, telemetryDelta, and logDelta payloads
          content:
            text/event-stream:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/ServerError"
  /api/runs/{runId}/artifacts/{artifactId}:
    parameters:
      - $ref: "#/components/parameters/RunId"
      - $ref: "#/components/parameters/ArtifactId"
    get:
      tags: [Runs]
      operationId: getRunArtifact
      responses:
        "200":
          description: Artifact content using its stored media type
          content:
            text/plain:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
            application/json:
              schema: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/approve:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: approveRunNode
      requestBody:
        $ref: "#/components/requestBodies/NodeAction"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/runs/{runId}/pass:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: passFailedRunNode
      summary: Pass a failed script node
      description: Marks a failed script or command node as succeeded and continues downstream without re-executing it. Agent nodes must use retry with optional human context instead.
      requestBody:
        $ref: "#/components/requestBodies/NodeAction"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/runs/{runId}/reject:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: rejectRunNode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [nodeId, reason]
              properties:
                nodeId:
                  type: string
                targetId:
                  type: string
                reason:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/runs/{runId}/retry:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: retryRunNode
      description: With Prefer respond-async, a reclaimed workspace returns 202 workspaceRestore while restoring. Poll GET /api/runs/{runId}/workspace/restore, then repeat the decision when ready. Only 200 confirms the retry started.
      parameters:
        - in: header
          name: Prefer
          schema:
            type: string
            example: respond-async
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [nodeId]
              properties:
                nodeId:
                  type: string
                reason:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "202":
          description: Workspace restoration accepted (Prefer respond-async); poll restore status before repeating the decision
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/runs/{runId}/decline-retry:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: declineRunRetry
      requestBody:
        $ref: "#/components/requestBodies/NodeAction"
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/runs/{runId}/cancel:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: cancelRun
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/runs/{runId}/pause:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: pauseRun
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/runs/{runId}/resume:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: resumePausedRun
      description: Prefer respond-async separates background workspace restoration from resuming execution, using the same polling flow as retry.
      parameters:
        - in: header
          name: Prefer
          schema:
            type: string
            example: respond-async
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                context:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "202":
          description: Workspace restoration accepted; poll restore status before resuming
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/runs/{runId}/refresh-sop:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: refreshPausedRunSOP
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/runs/{runId}/eval:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: getRunEval
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      tags: [Runs]
      operationId: startRunEval
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
      responses:
        "202":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/runs/{runId}/evals:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: listRunEvals
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/eval/stream:
    parameters:
      - $ref: "#/components/parameters/RunId"
    get:
      tags: [Runs]
      operationId: streamRunEval
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/runs/{runId}/eval/apply:
    parameters:
      - $ref: "#/components/parameters/RunId"
    post:
      tags: [Runs]
      operationId: applyRunEval
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                evalId:
                  type: string
                recommendationIds:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/sync/config:
    get:
      tags: [Sync]
      operationId: getSyncConfig
      responses:
        "200":
          $ref: "#/components/responses/SyncConfig"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Sync]
      operationId: createSyncConfig
      requestBody:
        $ref: "#/components/requestBodies/SyncConfig"
      responses:
        "200":
          $ref: "#/components/responses/SyncConfig"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Sync]
      operationId: updateSyncConfig
      requestBody:
        $ref: "#/components/requestBodies/SyncConfig"
      responses:
        "200":
          $ref: "#/components/responses/SyncConfig"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/sync/now:
    post:
      tags: [Sync]
      operationId: startSync
      responses:
        "200":
          description: Sync accepted
          content:
            application/json:
              schema:
                type: object
                required: [status, syncing]
                properties:
                  status:
                    type: string
                  syncing:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/sync/logs:
    get:
      tags: [Sync]
      operationId: listSyncLogs
      responses:
        "200":
          description: Sync logs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SyncLog"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/sync/status:
    get:
      tags: [Sync]
      operationId: getSyncStatus
      responses:
        "200":
          description: Sync status, config, and recent logs
          content:
            application/json:
              schema:
                type: object
                required: [syncing, config, logs]
                properties:
                  syncing:
                    type: boolean
                  config:
                    $ref: "#/components/schemas/SyncConfig"
                  logs:
                    type: array
                    items:
                      $ref: "#/components/schemas/SyncLog"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/sync/create:
    post:
      tags: [Sync, Issues]
      operationId: createExternalIssue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [issueId, target]
              properties:
                issueId:
                  type: string
                target:
                  type: string
                  enum: [gongfeng, tapd]
      responses:
        "200":
          $ref: "#/components/responses/Issue"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/notification-bots:
    get:
      summary: List configured project notification Bots and bound chats
      operationId: listNotificationBots
      parameters:
        - name: projectId
          in: query
          required: true
          schema: {type: string}
      responses:
        "200":
          description: Public Bot records, without credentials
          content:
            application/json:
              schema: {type: array, items: {type: object}}
        "403":
          description: Project membership required
  /api/notification-bots/{id}/interactions:
    get:
      summary: Inspect Bot connection and recent chat interactions
      operationId: inspectBotInteractions
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string}
      responses:
        "200":
          description: Connection status, recent conversations and messages; credentials excluded
        "403":
          description: Bot management permission required
  /api/bot-bindings:
    get:
      summary: List the logged-in user's WeCom identity bindings
      operationId: listBotUserBindings
      responses:
        "200":
          description: Bindings belonging to the interactive browser user
        "401":
          description: Interactive browser login required
  /api/bot-bindings/{id}:
    delete:
      summary: Revoke the logged-in user's WeCom identity binding
      operationId: revokeBotUserBinding
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string}
      responses:
        "204":
          description: Revoked; outstanding challenges invalidated
        "401":
          description: Interactive browser login required
        "403":
          description: Same-origin browser request required
        "404":
          description: Binding does not belong to the current user
  /api/bot-bindings/claim:
    post:
      summary: Nominate the logged-in account; original WeCom sender must confirm
      operationId: claimBotUserBinding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token: {type: string, minLength: 64, maxLength: 64}
      responses:
        "200":
          description: Login name, status and browser-only confirmation command
        "400":
          description: Expired, invalid or already claimed challenge
        "401":
          description: Interactive browser login required; Bearer tokens rejected
        "403":
          description: Same-origin browser request required
  /api/bot-bindings/status:
    post:
      summary: Read identity challenge status without logging its token in the URL
      operationId: botUserBindingStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token: {type: string, minLength: 64, maxLength: 64}
      responses:
        "200":
          description: Current challenge status and login name; no confirmation code
        "400":
          description: Expired, invalid or claimed by another account
        "401":
          description: Interactive browser login required
  /api/notification-preview:
    post:
      summary: Preview a notification using sample context without sending or calling AI
      operationId: previewNotification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [projectId, binding]
              properties:
                projectId: {type: string}
                binding: {$ref: "#/components/schemas/NotificationBinding"}
                sourceType: {type: string, enum: [run, schedule_job, assistant_task]}
      responses:
        "200":
          description: Preview content and its source
        "400":
          description: Invalid template
  /api/schedule-jobs:
    get:
      tags: [Scheduling]
      operationId: listScheduleJobs
      responses:
        "200":
          $ref: "#/components/responses/ScheduleJobList"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Scheduling]
      operationId: createScheduleJob
      requestBody:
        $ref: "#/components/requestBodies/ScheduleJob"
      responses:
        "200":
          $ref: "#/components/responses/ScheduleJob"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Scheduling]
      operationId: upsertScheduleJob
      requestBody:
        $ref: "#/components/requestBodies/ScheduleJob"
      responses:
        "200":
          $ref: "#/components/responses/ScheduleJob"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/schedule-jobs/{jobId}:
    parameters:
      - $ref: "#/components/parameters/JobId"
    delete:
      tags: [Scheduling]
      operationId: deleteScheduleJob
      responses:
        "200":
          $ref: "#/components/responses/Ok"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/schedule-jobs/{jobId}/run:
    parameters:
      - $ref: "#/components/parameters/JobId"
    post:
      tags: [Scheduling]
      operationId: runScheduleJob
      description: |
        Starts the job on the server and returns 202 with lastStatus=running.
        Closing the client does not cancel the run. Poll GET /api/schedule-jobs
        until lastStatus is success, failed, or waiting.
      responses:
        "202":
          $ref: "#/components/responses/ScheduleJob"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /api/schedule-jobs/{jobId}/enabled:
    parameters:
      - $ref: "#/components/parameters/JobId"
    post:
      tags: [Scheduling]
      operationId: setScheduleJobEnabled
      description: |
        Starts or stops the job's schedule. Only `enabled` changes: the prompt,
        key binding (runAsUserId) and session mode stay as saved, and a run in
        progress finishes either way. Requires write access to the job's project.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled]
              properties:
                enabled: { type: boolean }
      responses:
        "200":
          $ref: "#/components/responses/ScheduleJob"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/schedule-job-executions:
    get:
      tags: [Scheduling]
      operationId: listScheduleJobExecutions
      description: |
        Execution history of the schedule jobs the caller may read, newest first.
      parameters:
        - { name: projectId, in: query, schema: { type: string } }
        - { name: jobId, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [running, success, failed, waiting] } }
        - { name: traceId, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 100, maximum: 500 } }
      responses:
        "200":
          description: Executions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ScheduleJobExecution"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: jobId belongs to a project the caller cannot read
  /api/schedule-job-executions/dashboard:
    get:
      tags: [Scheduling]
      operationId: scheduleJobExecutionDashboard
      description: |
        One page of a project's execution dashboard, filtered, counted and paged on the server.
        `total` counts the executions matching the filters. `overview` follows the job filter
        only and compares the last 7×24 hours (the current hour included) with the 7×24 hours
        before, counted by the hour an execution started. Finished executions come from hourly
        statistics kept 30 days, independent of the 200 executions a job keeps; running ones
        are counted from the history. `records` and `recentFailed` cover the whole project.
      parameters:
        - { name: projectId, in: query, required: true, schema: { type: string } }
        - { name: jobId, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [running, success, failed, waiting] } }
        - { name: since, in: query, description: Only executions started at or after this time, schema: { type: string, format: date-time } }
        - { name: q, in: query, description: Case-insensitive search in job name and ID, trace ID, error, AI reply and dispatched runs, schema: { type: string } }
        - { name: offset, in: query, schema: { type: integer, default: 0 } }
        - { name: limit, in: query, schema: { type: integer, default: 20, maximum: 100 } }
      responses:
        "200":
          description: Dashboard page
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/ScheduleJobExecution"
                  total:
                    type: integer
                  overview:
                    type: object
                    properties:
                      current:
                        $ref: "#/components/schemas/ScheduleExecutionWindow"
                      previous:
                        $ref: "#/components/schemas/ScheduleExecutionWindow"
                      since:
                        type: string
                        format: date-time
                  records:
                    type: integer
                    description: Executions kept for the project
                  recentFailed:
                    type: integer
                    description: Failed executions of the project in the current window
        "400":
          description: projectId missing or since is not RFC 3339
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: jobId belongs to a project the caller cannot read
  /api/page-feedback:
    post:
      tags: [Feedback]
      operationId: submitPageFeedback
      description: |
        Submits a report from the floating page feedback widget. The report is
        stored in its own table and is not linked to any project or issue.
        Only a signed-in, non-guest browser session may submit: guests, expired
        sessions and anonymous callers get 401 {"error":"请先登录"}; requests
        carrying an Authorization Bearer header (personal API token) are
        refused with 401 as well. The submitter (userId, loginName = RTX, chineseName snapshot falling back to
        loginName) is always taken from the session; submitter fields in the
        payload are ignored. Images are sniffed by content and must be PNG,
        JPEG, GIF or WebP; at most 5 images of 5MB each, 27MB request body.
        Sensitive query parameters (token, code, ticket, session, key, secret,
        password…) are removed from url and frameUrl before storage.
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [payload]
              properties:
                payload:
                  type: string
                  description: JSON-encoded PageFeedbackPayload
                images:
                  type: array
                  maxItems: 5
                  items: {type: string, format: binary}
            encoding:
              payload:
                contentType: application/json
      responses:
        "201":
          description: Stored feedback
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageFeedback"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "413":
          description: Request body exceeds 27MB
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      tags: [Feedback]
      operationId: listPageFeedback
      description: |
        Lists every report newest first. Any signed-in employee may read all
        reports, using the browser session or a personal API token (Bearer).
        Guests get 401. Images carry metadata and a download url only.
      parameters:
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 100, default: 20}
        - name: offset
          in: query
          schema: {type: integer, minimum: 0, default: 0}
      responses:
        "200":
          description: Page of feedback
          content:
            application/json:
              schema:
                type: object
                required: [items, total, offset, limit, hasMore]
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PageFeedback"
                  total: {type: integer, format: int64}
                  offset: {type: integer}
                  limit: {type: integer}
                  hasMore: {type: boolean}
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/page-feedback/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Feedback]
      operationId: getPageFeedback
      description: One report with its submitter. Session cookie or personal API token; guests get 401.
      responses:
        "200":
          description: Feedback
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageFeedback"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/page-feedback/{id}/images/{imageId}:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string}
      - name: imageId
        in: path
        required: true
        schema: {type: string}
    get:
      tags: [Feedback]
      operationId: getPageFeedbackImage
      description: |
        Image bytes served inline with the stored content type,
        X-Content-Type-Options nosniff and Content-Security-Policy
        default-src 'none'. 404 when the image does not belong to the report.
        Session cookie or personal API token; guests get 401.
      responses:
        "200":
          description: Image
          content:
            image/png: {}
            image/jpeg: {}
            image/gif: {}
            image/webp: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/shared-schedule-tasks:
    get:
      tags: [Scheduling]
      operationId: listSharedScheduleTasks
      summary: List latest published shared AI task versions
      responses:
        "200":
          description: Latest immutable definition for each shared task, without credentials or project notifications
          content:
            application/json:
              schema: {type: array, items: {$ref: "#/components/schemas/SharedScheduleVersion"}}
  /api/shared-schedule-tasks/{id}/versions:
    parameters:
      - {name: id, in: path, required: true, schema: {type: string}}
    get:
      tags: [Scheduling]
      operationId: listSharedScheduleVersions
      summary: List immutable versions in descending order
      responses:
        "200":
          description: Published versions, retained while subscriptions can reference them
          content:
            application/json:
              schema: {type: array, items: {$ref: "#/components/schemas/SharedScheduleVersion"}}
        "404": {$ref: "#/components/responses/NotFound"}
  /api/schedule-jobs/{id}/publish:
    parameters:
      - {name: id, in: path, required: true, schema: {type: string}}
    post:
      tags: [Scheduling]
      operationId: publishSharedScheduleVersion
      summary: Publish a credential-free version from an independent AI task
      description: Requires source project write access. Trigger configs and subscriptions cannot be republished. Publishing never changes existing subscriptions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [baseVersion]
              properties:
                name: {type: string, maxLength: 255}
                description: {type: string, maxLength: 2000}
                prompt: {type: string, description: 'Template with {{params.name}} placeholders; defaults to source task prompt'}
                parameters: {type: array, maxItems: 20, items: {$ref: "#/components/schemas/ScheduleParameter"}}
                changeNote: {type: string, maxLength: 1000}
                baseVersion: {type: integer, minimum: 0, description: '0 for first publication, otherwise the latest published version'}
      responses:
        "201":
          description: Newly published immutable version
          content:
            application/json:
              schema: {$ref: "#/components/schemas/SharedScheduleVersion"}
        "400": {$ref: "#/components/responses/BadRequest"}
        "403": {$ref: "#/components/responses/Forbidden"}
        "404": {$ref: "#/components/responses/NotFound"}
        "409": {$ref: "#/components/responses/Conflict"}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    cookieAuth:
      type: apiKey
      in: cookie
      name: agentflow_user
    basicAuth:
      type: http
      scheme: basic
  parameters:
    SkillhubSlug:
      name: slug
      in: path
      required: true
      schema:
        type: string
        pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
    SkillhubNamespace:
      name: namespace
      in: query
      description: SkillHub publisher handle; slugs are only unique within a namespace
      schema:
        type: string
    SkillhubVersion:
      name: version
      in: query
      description: Defaults to the latest version
      schema:
        type: string
    IssueId:
      name: issueId
      in: path
      required: true
      schema:
        type: string
    AgentId:
      name: agentId
      in: path
      required: true
      schema:
        type: string
    AssetIdQuery:
      name: id
      in: query
      required: true
      schema:
        type: string
    WorkflowId:
      name: workflowId
      in: path
      required: true
      schema:
        type: string
    RevisionId:
      name: revisionId
      in: path
      required: true
      schema:
        type: string
    RunId:
      name: runId
      in: path
      required: true
      schema:
        type: string
    ArtifactId:
      name: artifactId
      in: path
      required: true
      schema:
        type: string
    JobId:
      name: jobId
      in: path
      required: true
      schema:
        type: string
    RepositoryIdQuery:
      name: id
      in: query
      required: true
      schema:
        type: string
    NodeIdQuery:
      name: nodeId
      in: query
      schema:
        type: string
    After:
      name: after
      in: query
      schema:
        type: integer
        format: int64
    Before:
      name: before
      in: query
      schema:
        type: integer
        format: int64
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
  requestBodies:
    Project:
      required: true
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/Project"
              - type: object
                properties:
                  tapdClear:
                    type: boolean
    Repository:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RepositoryInput"
    Issue:
      required: true
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/Issue"
              - type: object
                properties:
                  syncTarget:
                    type: string
                    enum: [gongfeng, tapd]
    ChatClarify:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ChatClarifyRequest"
    Agent:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AgentDefinition"
    RuleAsset:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RuleAsset"
    SkillAsset:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SkillAsset"
    MCPServerAsset:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MCPServerAsset"
    DockerfileAsset:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DockerfileAsset"
    EnvironmentAsset:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EnvironmentAsset"
    SandboxProfile:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SandboxProfile"
    Workflow:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WorkflowDefinition"
    NodeAction:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [nodeId]
            properties:
              nodeId:
                type: string
    SyncConfig:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SyncConfig"
    ScheduleJob:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ScheduleJob"
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Basic authentication required
      headers:
        WWW-Authenticate:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Operation is disabled or forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description: Resource state conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    SkillhubUnavailable:
      description: SkillHub rejected the package (422), rate limited (429), is unavailable (502) or timed out (504)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    GatewayTimeout:
      description: Upstream analysis timed out
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Ok:
      description: Operation succeeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Ok"
    Status:
      description: Status result
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Status"
    Project:
      description: Project
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Project"
    ProjectList:
      description: Project list
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Project"
    Repository:
      description: Repository
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Repository"
    Issue:
      description: Issue
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Issue"
    Workflow:
      description: Workflow definition
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WorkflowDefinition"
    WorkflowList:
      description: Workflow definitions
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/WorkflowDefinition"
    Run:
      description: Run
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Run"
    RunList:
      description: Run summaries
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Run"
    RevisionList:
      description: Definition revisions
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/DefinitionRevision"
    AssetList:
      description: Asset definitions
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/OpenObject"
    ClarifyResult:
      description: JSON clarification result or SSE event stream
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClarifyResult"
        text/event-stream:
          schema:
            type: string
    SyncConfig:
      description: Sync configuration
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SyncConfig"
    ScheduleJob:
      description: Schedule job
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ScheduleJob"
    ScheduleJobList:
      description: Schedule jobs
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ScheduleJob"
  schemas:
    OpenObject:
      type: object
      additionalProperties: true
    RuleAsset:
      type: object
      required: [id, name, content]
      additionalProperties: true
      properties:
        id: {type: string}
        name: {type: string}
        projectId: {type: string, description: Owning project}
        shared: {type: boolean, description: Visible to every project}
        description: {type: string}
        content: {type: string, description: Rule text injected into bound roles}
        priority: {type: integer}
        global: {type: boolean, description: Apply to every node of the workflows in workflowIds}
        workflowIds: {type: array, items: {type: string}}
    SkillAsset:
      type: object
      required: [id, name, content]
      additionalProperties: true
      properties:
        id: {type: string}
        name: {type: string}
        projectId: {type: string}
        shared: {type: boolean}
        description: {type: string}
        content: {type: string, description: SKILL.md body}
        files: {type: object, additionalProperties: {type: string}, description: Extra text files keyed by relative path}
    MCPServerAsset:
      type: object
      required: [id, name, transport]
      additionalProperties: true
      properties:
        id: {type: string}
        name: {type: string}
        projectId: {type: string}
        scope: {type: string, enum: [project, personal]}
        description: {type: string}
        transport: {type: string, enum: [stdio, http]}
        command: {type: string, description: stdio executable}
        args: {type: array, items: {type: string}}
        url: {type: string, description: http endpoint}
        environment: {type: object, additionalProperties: {type: string}}
        headers: {type: object, additionalProperties: {type: string}}
        installScript: {type: string}
        workingDirectory: {type: string}
        pathEntries: {type: array, items: {type: string}}
        authType: {type: string, enum: ["", github-token]}
        timeoutSec: {type: integer}
    DockerfileAsset:
      type: object
      required: [id, name, projectId, content]
      additionalProperties: true
      properties:
        id: {type: string}
        name: {type: string}
        projectId: {type: string}
        shared: {type: boolean}
        description: {type: string}
        content: {type: string, description: Dockerfile text}
        files: {type: object, additionalProperties: {type: string}, description: Build-context files keyed by relative path}
    EnvironmentAsset:
      type: object
      required: [id, name, projectId]
      additionalProperties: true
      properties:
        id: {type: string}
        name: {type: string}
        projectId: {type: string}
        shared: {type: boolean}
        description: {type: string}
        variables: {type: object, additionalProperties: {type: string}}
        pathEntries: {type: array, items: {type: string}}
        installScript: {type: string, description: Runs once with PREFIX set to the isolated environment root}
    SandboxProfile:
      type: object
      required: [id, name, projectId, driver]
      additionalProperties: true
      description: >-
        Execution environment for SOP runs and conversation workspaces. Conversation workspaces
        need driver=docker with an existing dockerfileId; the built-in shared generic-docker
        profile already satisfies this, so create a new profile only for a different toolchain.
      properties:
        id: {type: string}
        name: {type: string}
        projectId: {type: string, description: Owning project (required)}
        shared: {type: boolean, description: Visible to every project}
        driver: {type: string, enum: [local, native, docker]}
        dockerfileId: {type: string, description: Required for driver=docker; see dockerfiles_list}
        environmentId: {type: string, description: Toolchain for native/local drivers; see environments_list}
        readOnlyRootFS: {type: boolean}
        environment: {type: object, additionalProperties: {type: string}}
    APIToken:
      type: object
      required: [id, userId, name, prefix, createdAt]
      properties:
        id: {type: string}
        userId: {type: integer, format: int64}
        name: {type: string}
        prefix: {type: string, description: Non-secret display prefix}
        lastUsedAt: {type: string, format: date-time}
        expiresAt: {type: string, format: date-time}
        createdAt: {type: string, format: date-time}
        revokedAt: {type: string, format: date-time}
    PageFeedbackPayload:
      type: object
      description: Unknown fields, including any submitter fields, are ignored.
      required: [title]
      properties:
        title: {type: string, minLength: 1, maxLength: 120, description: First line of the user's text}
        description: {type: string, maxLength: 5000, description: Full text}
        url: {type: string, maxLength: 2048}
        route: {type: string, description: Hash route}
        view: {type: string}
        frameUrl: {type: string, maxLength: 2048, description: Workbench iframe location}
        context:
          $ref: "#/components/schemas/PageFeedbackContext"
        element:
          $ref: "#/components/schemas/PageFeedbackElement"
    PageFeedbackContext:
      type: object
      properties:
        scroll: {$ref: "#/components/schemas/PageFeedbackPoint"}
        viewport:
          type: object
          properties:
            width: {type: number}
            height: {type: number}
        dpr: {type: number}
        userAgent: {type: string}
        language: {type: string}
        theme: {type: string}
        capturedAt: {type: string}
    PageFeedbackPoint:
      type: object
      properties:
        x: {type: number}
        y: {type: number}
    PageFeedbackRect:
      type: object
      properties:
        x: {type: number}
        y: {type: number}
        width: {type: number}
        height: {type: number}
    PageFeedbackElement:
      type: object
      properties:
        selector: {type: string}
        tag: {type: string}
        text: {type: string, maxLength: 200}
        rect: {$ref: "#/components/schemas/PageFeedbackRect"}
        pageRect: {$ref: "#/components/schemas/PageFeedbackRect"}
        point: {$ref: "#/components/schemas/PageFeedbackPoint"}
        inFrame: {type: boolean}
    PageFeedback:
      type: object
      required: [id, title, url, route, context, submitter, images, createdAt]
      properties:
        id: {type: string}
        title: {type: string}
        description: {type: string}
        url: {type: string}
        route: {type: string}
        view: {type: string}
        frameUrl: {type: string}
        context: {$ref: "#/components/schemas/PageFeedbackContext"}
        element: {$ref: "#/components/schemas/PageFeedbackElement"}
        submitter:
          type: object
          required: [userId, loginName, chineseName]
          properties:
            userId: {type: integer, format: int64}
            loginName: {type: string, description: Employee RTX}
            chineseName: {type: string, description: Snapshot at submit time; RTX when empty}
        images:
          type: array
          items:
            type: object
            properties:
              id: {type: string}
              position: {type: integer}
              fileName: {type: string}
              mimeType: {type: string}
              size: {type: integer, format: int64}
              sha256: {type: string}
              url: {type: string}
              createdAt: {type: string, format: date-time}
        createdAt: {type: string, format: date-time}
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
    Ok:
      type: object
      required: [ok]
      properties:
        ok:
          type: boolean
          const: true
    Status:
      type: object
      required: [status]
      properties:
        status:
          type: string
    Health:
      type: object
      required: [status]
      properties:
        status:
          type: string
          const: ok
    BusinessDomain:
      type: object
      required: [id, name, active, managerIds, viewerIds]
      properties:
        id: {type: string, pattern: '^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$', description: 'Stable ID; all and unclassified are reserved'}
        name: {type: string, minLength: 1, maxLength: 100}
        description: {type: string, maxLength: 2000}
        active: {type: boolean}
        managerIds: {type: array, uniqueItems: true, items: {type: integer, format: int64}}
        viewerIds: {type: array, uniqueItems: true, items: {type: integer, format: int64}}
        createdAt: {type: string, format: date-time, readOnly: true}
        updatedAt: {type: string, format: date-time, readOnly: true}
    BusinessDomainAssignment:
      type: object
      properties:
        id: {type: integer, format: int64}
        projectId: {type: string}
        fromDomainId: {type: string}
        toDomainId: {type: string}
        actorId: {type: integer, format: int64}
        reason: {type: string}
        createdAt: {type: string, format: date-time}
    BusinessDomainReport:
      type: object
      properties:
        attribution: {type: string, const: current}
        generatedAt: {type: string, format: date-time}
        from: {type: string, format: date-time}
        to: {type: string, format: date-time}
        summary: {$ref: "#/components/schemas/AnalyticsCostSummary"}
        delivery: {type: object, description: 'Existing AnalyticsDeliverySummary'}
        trend: {type: array, items: {type: object}}
        projects: {type: array, items: {type: object}, description: 'Project ID, name, businessDomainId and AnalyticsProjectUsage'}
        businessDomains: {type: array, items: {type: object}, description: 'ID, name, active, projectCount, runs, success, failed, tokens, costCny, legacy USD equivalent costUsd, costKnown, uniqueIssues and delivered'}
        deliveryMetrics: {$ref: "#/components/schemas/BusinessDeliveryMetrics"}
        deliveryTrend:
          type: array
          items:
            type: object
            properties:
              date: {type: string, description: 'Day, ISO week or month in the reporting timezone'}
              completedIssues: {type: integer}
              mergedMrs: {type: integer}
              cycleSamples: {type: integer}
              averageCycleDurationMs: {type: integer, format: int64}
              executionSamples: {type: integer}
              averageExecutionDurationMs: {type: integer, format: int64, description: Average completion duration excluding waits; requires executionSamples greater than zero}
        timeZone: {type: string}
        grain: {type: string, enum: [day, week, month]}
    BusinessDeliveryMetrics:
      type: object
      description: 'Also included as deliveryMetrics on each project and business domain. Completion, merge and Run creation windows are independent. No individual issue or Run details are returned.'
      properties:
        completionToMergeSamples: {type: integer, description: 'One sample per unique repository and MR IID, filtered by its own merge time'}
        averageCompletionToMergeMs: {type: integer, format: int64, description: 'Mean of the latest matched successful completion to each individual MR actual merge; multiple MRs for one issue are separate samples'}
        completionToMergeMissingIssues: {type: integer, description: 'Merged items without matched completion events or complete delivery MR evidence'}
        completionToMergeMissingMrs: {type: integer, description: 'Merged MRs missing completion events or matching delivery evidence'}
        mergedBeforeCompletionMrs: {type: integer, description: 'MRs merged before matching flow completion, excluded from latency averages'}
        mergedBeforeCompletionIssues: {type: integer, description: 'Items merged before their flow finished; excluded from the latency average'}
        completedIssues: {type: integer, description: 'Current done/closed/completed work items whose completion time falls in the requested window; includes Issues'}
        mergedMrs: {type: integer, description: 'Unique work MRs by actual merged_at, including integration branches, excluding baseline promotion MRs'}
        mergedMrsMissingTime: {type: integer, description: 'Merged MRs in scope with no merge timestamp, excluded from dated counts'}
        completionTimeMissingIssues: {type: integer, description: 'Currently completed historical items with no usable time, excluded from dated completion counts'}
        estimatedCompletionIssues: {type: integer, description: 'Included historical items whose time is inferred from their latest successful top-level Run'}
        cycleSamples: {type: integer}
        averageCycleDurationMs: {type: integer, format: int64, description: Completion elapsed time including waits; averaged over cycleSamples}
        executionSamples: {type: integer, description: Completed items with node execution events for every related attempt and child SOP}
        averageExecutionDurationMs: {type: integer, format: int64, description: Union of actual node execution intervals per item; excludes waits and double counting of parallel or nested execution; averaged over executionSamples}
        p50CycleDurationMs: {type: integer, format: int64, deprecated: true}
        p95CycleDurationMs: {type: integer, format: int64, deprecated: true, description: 'Nearest-rank percentile over individual work items, never an average of project percentiles'}
        completedTokens: {type: integer, format: int64}
        averageTokensPerCompletedIssue: {type: integer, format: int64}
        latestCompletedAt: {type: string, format: date-time}
    Project:
      type: object
      required: [id, name]
      properties:
        businessDomainId:
          type: string
          readOnly: true
          description: Current main business domain. Use the dedicated assignment endpoint to change it.
        id:
          type: string
        key:
          type: string
        name:
          type: string
        description:
          type: string
        color:
          type: string
        workflowId:
          type: string
        defaultRepositoryId:
          type: string
        ownerId:
          type: integer
          format: int64
        members:
          type: array
          items:
            $ref: "#/components/schemas/ProjectMember"
        tapdWorkspaceId:
          type: string
        tapdIterationId:
          type: string
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    ProjectMember:
      type: object
      required: [userId, role]
      properties:
        userId:
          type: integer
          format: int64
        role:
          type: string
          enum: [maintainer, member, viewer]
    PlatformAccount:
      type: object
      properties:
        userId: {type: integer, format: int64}
        loginName: {type: string}
        chineseName: {type: string}
        admin: {type: boolean}
        password: {type: boolean, description: False for accounts that sign in through GitHub or a gateway}
        codeBuddyApiKeyConfigured: {type: boolean}
        createdAt: {type: string, format: date-time}
    PlatformCodeBuddyKey:
      type: object
      properties:
        configured: {type: boolean}
        internetEnvironment: {type: string}
        models: {type: array, items: {type: string}, description: Allowed models, the default first}
        updatedAt: {type: string, format: date-time}
        updatedBy: {type: string}
        legacySponsor: {type: string, description: Account named by AGENTFLOW_ASSISTANT_SPONSOR_LOGIN, used while no key is configured here}
        legacySponsorModel: {type: string}
        catalog:
          type: array
          description: Models offered in the requested network environment (GET only)
          items:
            type: object
            properties:
              id: {type: string}
              name: {type: string}
              family: {type: string}
              credits: {type: string}
    User:
      type: object
      required: [id, loginName]
      properties:
        id: {type: integer, format: int64}
        staffId: {type: integer}
        loginName: {type: string}
        chineseName: {type: string}
        deptId: {type: integer}
        deptName: {type: string}
        avatarUrl: {type: string}
        gitHubCredentialConfigured: {type: boolean, readOnly: true}
        codeBuddyApiKeyConfigured: {type: boolean, readOnly: true}
        codexApiKeyConfigured: {type: boolean, readOnly: true}
        codexBaseUrl: {type: string}
        claudeCodeApiKeyConfigured: {type: boolean, readOnly: true}
        claudeCodeBaseUrl: {type: string}
        codeBuddyInternetEnvironment: {type: string}
    RepositoryInput:
      type: object
      required: [projectId]
      anyOf:
        - required: [repoUrl]
        - required: [url]
        - required: [webUrl]
        - required: [cloneUrl]
        - required: [gongfengProjectId]
      properties:
        id: {type: string}
        projectId: {type: string}
        name: {type: string}
        repoUrl: {type: string, description: GitHub web/SSH/clone URL; derives name and repository identity}
        url: {type: string, description: Alias of repoUrl}
        webUrl: {type: string}
        cloneUrl: {type: string}
        gongfengProjectId: {type: string, description: Legacy wire field for repository identity; GitHub uses github:owner/repo. Prefer repoUrl.}
        defaultBranch: {type: string}
        integrateBranch: {type: string}
        provider: {type: string, description: GitHub is inferred from repoUrl; legacy provider values remain compatible, example: github}
        pipelineProjectId: {type: integer}
        pipelineDefId: {type: integer}
    Repository:
      type: object
      required: [projectId, name, gongfengProjectId]
      properties:
        id:
          type: string
        projectId:
          type: string
        provider:
          type: string
          description: "Inferred from the repository URL: github, gongfeng, https, or ssh. Unknown HTTPS hosts use Git transport without a hosting API adapter."
          example: github
        name:
          type: string
        gongfengProjectId:
          type: string
        webUrl:
          type: string
          format: uri
        cloneUrl:
          type: string
        defaultBranch:
          type: string
        localPath:
          type: string
        pipelineProjectId:
          type: integer
        pipelineDefId:
          type: integer
        pipelineUrlPattern:
          type: string
        integrateBranch:
          type: string
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    IssueListPage:
      type: object
      required: [items, total, offset, limit, hasMore]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Issue"
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        hasMore:
          type: boolean
    Issue:
      type: object
      required: [projectId, title]
      properties:
        closureAllowed:
          type: boolean
          readOnly: true
          description: Whether manual closure is permitted; active clarification, tasks or runs prevent closure.
        completedAt:
          type: string
          format: date-time
          readOnly: true
          description: Observed transition to a completed state. Preserved on edits and tracker polling, cleared on reopen; historical unknown timestamps remain unknown.
        deletionAllowed:
          type: boolean
          readOnly: true
          description: Whether deletion is currently permitted, computed from complete task and run history on list and detail responses.
        deletionBlock:
          type: object
          readOnly: true
          description: Present when deletion is blocked. Uses complete execution history; clarification and unfinished work take precedence over historical success and completed issue status. The DELETE conflict response uses the same reason.
          required: [code, reason]
          properties:
            code:
              type: string
              enum: [clarifying, active, succeeded, completed]
            reason:
              type: string
              description: Human-readable explanation suitable for direct display.
            runId:
              type: string
              description: Existing run responsible for the restriction, including legacy task-linked runs outside the current run list.
            taskId:
              type: string
              description: Task responsible for the restriction when there is no corresponding blocking run.
        id:
          type: string
        projectId:
          type: string
        number:
          type: integer
          readOnly: true
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [backlog, todo, in_progress, in_review, done, blocked, cancelled, closed]
        priority:
          type: string
        assigneeType:
          type: string
          enum: [member, agent]
        assigneeId:
          type: string
        assigneeUserId:
          type: integer
          format: int64
        workflowId:
          type: string
        repositoryId:
          type: string
        baseBranch:
          type: string
          description: Existing work branch to continue directly for a single repository; empty creates a new work branch from the configured main branch; an omitted field preserves the selection on edits
        repositoryIds:
          type: array
          items: {type: string}
        repositoryBranches:
          type: object
          additionalProperties: {type: string}
          description: Existing work branches keyed by bound repository ID; overrides baseBranch. Empty or unlisted branches create new branches. Omitted preserves selections for retained repositories on edits; an empty object clears all selections.
        latestTaskId:
          type: string
        automationState:
          type: string
        deliveryState:
          type: string
        deliveryMrUrl:
          type: string
        deliveryMrState:
          type: string
          description: 所有交付 MR 的聚合状态(merged / integrated / opened / closed / unknown)
        deliveryMrs:
          type: array
          description: 每个交付仓库一个 MR;deliveryMrUrl 为第一项
          items:
            type: object
            properties:
              repositoryId:
                type: string
              repository:
                type: string
              project:
                type: string
              iid:
                type: integer
              url:
                type: string
              state:
                type: string
              targetBranch:
                type: string
        deliveryUpdatedAt:
          type: string
          format: date-time
        kind:
          type: string
          enum: [requirement, issue]
        clarification:
          $ref: "#/components/schemas/ClarificationAssessment"
        source:
          type: string
          enum: [local, gongfeng, tapd]
        externalRef:
          $ref: "#/components/schemas/ExternalRef"
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    ClarificationAssessment:
      type: object
      description: Optional AI clarification state. It carries no score and never gates SOP dispatch.
      properties:
        summary:
          type: string
        status:
          type: string
          enum: [in_progress, ready, needs_user]
        history:
          type: array
          items:
            $ref: "#/components/schemas/ClarificationMessage"
        questions:
          type: array
          items:
            $ref: "#/components/schemas/ClarificationQuestion"
        writeBackStatus:
          type: string
          enum: [pending, succeeded, failed, skipped]
        writeBackError:
          type: string
        writeBackFingerprint:
          type: string
        writeBackAt:
          type: string
          format: date-time
    ClarificationMessage:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
          enum: [user, assistant]
        content:
          type: string
    ClarificationQuestion:
      type: object
      required: [id, question]
      properties:
        id:
          type: string
        question:
          type: string
        options:
          type: array
          items:
            type: string
        multiSelect:
          type: boolean
    ExternalRef:
      type: object
      properties:
        source:
          type: string
        externalId:
          type: string
        externalIid:
          type: integer
        externalUrl:
          type: string
        externalState:
          type: string
        externalType:
          type: string
        syncedAt:
          type: string
          format: date-time
    IssueComment:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        issueId:
          type: string
          readOnly: true
        authorType:
          type: string
        authorId:
          type: string
        body:
          type: string
        createdAt:
          type: string
          format: date-time
          readOnly: true
    Task:
      type: object
      required: [id, issueId, workflowId, status]
      properties:
        id:
          type: string
        issueId:
          type: string
        agentId:
          type: string
        workflowId:
          type: string
        runId:
          type: string
        status:
          type: string
          enum: [queued, dispatched, running, completed, failed, cancelled]
        dispatchMode:
          type: string
          enum: [primary, scheduled, rerun]
        scheduleJobId:
          type: string
        triggerOrigin:
          type: string
        repository:
          $ref: "#/components/schemas/RepositoryContext"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    RepositoryContext:
      type: object
      additionalProperties: true
      properties:
        repositoryId:
          type: string
        provider:
          type: string
        name:
          type: string
        baseBranch:
          type: string
          description: Frozen checkout baseline and MR target; configured main branch when continuing an existing work branch
        workBranch:
          type: string
          description: Generated work branch, or the explicitly selected existing branch to continue
        requireExistingWorkBranch:
          type: boolean
          description: Requires workBranch to exist on the remote; never creates a replacement branch
        integrateBranch:
          type: string
    AgentDefinition:
      type: object
      required: [id, name]
      additionalProperties: true
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: integer
        description:
          type: string
        prompt:
          type: string
          description: The role's single free-form brief (who it is, what to do, order, limits). Runtime placeholders such as {{input}}, {{repository}}, {{artifacts}}, {{feedback}} and {{upstream}} are substituted per run; deliverable, gate and retry sections are added from artifactOutputs, verification and node policy.
        rules:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            type: string
        mcpServers:
          type: array
          items:
            type: string
        hooks:
          type: array
          items:
            $ref: "#/components/schemas/AgentHook"
        executorId:
          type: string
        model:
          type: string
        loop:
          $ref: "#/components/schemas/OpenObject"
        updatedAt:
          type: string
          format: date-time
    AgentHook:
      type: object
      required: [id, name, event, language, script]
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        event:
          type: string
          enum: [SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop]
        matcher:
          type: string
        language:
          type: string
          enum: [shell, python]
        script:
          type: string
        timeoutSec:
          type: integer
          minimum: 1
          maximum: 600
        executionScope:
          type: string
          enum: [run, repositories]
          description: Run once in the task workspace or once per repository checkout.
    WorkflowDefinition:
      type: object
      required: [id, name, sandboxProfileId, nodes, edges]
      additionalProperties: true
      properties:
        notifications: {type: array, maxItems: 1, items: {$ref: "#/components/schemas/NotificationBinding"}, description: Single SOP Bot; all nodes automatically notify waiting/failed and SOP completion. Template and AI instruction customize completion only}
        id:
          type: string
        name:
          type: string
        version:
          type: integer
        revision:
          type: integer
        status:
          type: string
          enum: [draft, published, archived]
        owner:
          type: string
        tags:
          type: array
          items:
            type: string
        description:
          type: string
        sandboxProfileId:
          type: string
        generic:
          type: boolean
          description: >-
            Platform-provided, project-independent template. Generic templates are served from the
            platform catalog. They can run directly by reference in a project, or be cloned
            for project-specific editing. Platform administrators can edit catalog templates;
            other users cannot. Repository binding is optional: without a repository, tasks run
            in their own workspace and deliver artifacts; creating a PR requires a target repository
            and credentials. Cloning also creates the referenced roles in the target project.
        requirements:
          type: array
          description: >-
            External capabilities the SOP needs at run time (for example a GitHub token or a
            project-scoped GitHub MCP). Studio renders them as a preflight checklist so users learn
            about the dependency before the first run.
          items:
            $ref: "#/components/schemas/WorkflowRequirement"
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowNode"
        edges:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowEdge"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    WorkflowRequirement:
      type: object
      required: [key, label]
      additionalProperties: true
      properties:
        key:
          type: string
          description: Stable id the client maps to a live check.
        nodeId:
          type: string
          description: Node that depends on the capability (for example a code delivery node).
        label:
          type: string
        hint:
          type: string
        setup:
          type: string
          description: Where the user fixes the dependency.
          enum: [settings, mcp]
    NotificationBinding:
      type: object
      required: [botId, events]
      properties:
        botId: {type: string, description: Platform Bot reference from notification_bots_list}
        events: {type: array, maxItems: 3, items: {type: string, enum: [succeeded, failed, waiting]}}
        scope: {type: string, enum: [node, run], description: Run scope supports succeeded and failed only. Scheduled tasks use no scope.}
        template: {type: string, maxLength: 12000, description: Free Markdown with business/output/AI variables}
        waitingPolicy: {type: string, enum: [actionable, event], description: Waiting reminders cancel if resolved before sending by default; event records are sent even after resolution.}
        contentMode: {type: string, enum: [template, ai]}
        aiInstruction: {type: string, maxLength: 4000, description: Writing instructions for the independent SOP report or the existing scheduled task model call}
    WorkflowNode:
      type: object
      required: [id, name, type]
      additionalProperties: true
      properties:
        notifications: {type: array, maxItems: 3, items: {$ref: "#/components/schemas/NotificationBinding"}}
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [agent, script, command, approval, sop]
        agentId:
          type: string
        executorId:
          type: string
        scriptLanguage:
          type: string
          enum: [shell, python]
        script:
          type: string
        command:
          type: string
          deprecated: true
          description: Legacy shell-command field; normalized to a shell script node when saved.
        maxAttempts:
          type: integer
        maxReworks:
          type: integer
        position:
          $ref: "#/components/schemas/OpenObject"
    WorkflowEdge:
      type: object
      required: [id, source, target]
      properties:
        id:
          type: string
        source:
          type: string
        target:
          type: string
        when:
          type: string
    DefinitionRevision:
      type: object
      required: [id, kind, entityId, version, revision, name, payload, createdAt]
      properties:
        id:
          type: string
        kind:
          type: string
          enum: [workflow, agent]
        entityId:
          type: string
        version:
          type: integer
        revision:
          type: integer
        name:
          type: string
        summary:
          type: string
        payload:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
    Run:
      type: object
      required: [id, workflowId, status]
      additionalProperties: true
      properties:
        id:
          type: string
        workflowId:
          type: string
        kind:
          type: string
          readOnly: true
          description: workspace identifies an idle conversation workspace; absent for SOP runs and historical role-group records.
        workflowSnapshot:
          $ref: "#/components/schemas/WorkflowDefinition"
        status:
          type: string
          enum: [queued, running, waiting, succeeded, failed, cancelled]
        admissionState:
          type: string
          enum: [queued, held, unstarted, released]
          readOnly: true
          description: Server-managed admission state; failed, paused, and cancelled runs that already started retain their concurrency slot.
        queueEnteredAt:
          type: string
          format: date-time
          readOnly: true
        concurrencyExempt:
          type: boolean
          readOnly: true
          description: Personal-runner executions do not consume project concurrency slots.
        input:
          type: string
        repository:
          $ref: "#/components/schemas/RepositoryContext"
        executionContext:
          $ref: "#/components/schemas/OpenObject"
        nodes:
          type: object
          additionalProperties:
            oneOf:
              - $ref: "#/components/schemas/NodeRun"
              - type: "null"
        events:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        usage:
          $ref: "#/components/schemas/TokenUsage"
        toolCalls:
          type: integer
        artifacts:
          type: array
          items:
            $ref: "#/components/schemas/Artifact"
        artifactCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        revision:
          type: integer
    RunWorkspace:
      type: object
      required: [available, readOnly, runStatus]
      properties:
        available: {type: boolean}
        readOnly: {type: boolean, enum: [true]}
        runStatus: {type: string}
        reason: {type: string}
        warning: {type: string}
        changes:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceChange"
    WorkspaceChange:
      type: object
      required: [path, index, worktree]
      properties:
        path: {type: string}
        repository: {type: string}
        index: {type: string, minLength: 1, maxLength: 1}
        worktree: {type: string, minLength: 1, maxLength: 1}
    WorkspaceEntry:
      type: object
      required: [path, name, type]
      properties:
        path: {type: string}
        name: {type: string}
        type: {type: string, enum: [file, directory]}
        size: {type: integer, format: int64}
        modifiedAt: {type: string, format: date-time}
    WorkspaceSearchResult:
      type: object
      required: [path, line, preview]
      properties:
        path: {type: string}
        line: {type: integer, minimum: 1}
        preview: {type: string}
    NodeRun:
      type: object
      additionalProperties: true
      properties:
        nodeId:
          type: string
        status:
          type: string
        attempt:
          type: integer
        reworkCount:
          type: integer
        output:
          type: string
        error:
          type: string
        activity:
          type: string
        feedback:
          type: string
        usage:
          $ref: "#/components/schemas/TokenUsage"
        toolCalls:
          type: integer
    TokenUsage:
      type: object
      properties:
        inputTokens:
          type: integer
          format: int64
        outputTokens:
          type: integer
          format: int64
        cacheReadTokens:
          type: integer
          format: int64
        cacheWriteTokens:
          type: integer
          format: int64
        totalTokens:
          type: integer
          format: int64
        costUsd:
          type: number
    Artifact:
      type: object
      required: [id, runId, nodeId, attempt, name, mediaType, size, sha256]
      properties:
        id:
          type: string
        runId:
          type: string
        nodeId:
          type: string
        attempt:
          type: integer
        name:
          type: string
        path:
          type: string
        mediaType:
          type: string
        size:
          type: integer
          format: int64
        sha256:
          type: string
        content:
          type: string
        createdAt:
          type: string
          format: date-time
    TelemetryPage:
      type: object
      required: [runId, sequence, events, hasMore]
      properties:
        runId:
          type: string
        sequence:
          type: integer
          format: int64
        events:
          type: array
          items:
            $ref: "#/components/schemas/TelemetryEvent"
        nextAfter:
          type: integer
          format: int64
        nextBefore:
          type: integer
          format: int64
        hasMore:
          type: boolean
    TelemetryEvent:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        runId:
          type: string
        nodeId:
          type: string
        sequence:
          type: integer
          format: int64
        timestamp:
          type: string
          format: date-time
        category:
          type: string
        name:
          type: string
        phase:
          type: string
        level:
          type: string
        message:
          type: string
    LogPage:
      type: object
      required: [runId, sequence, logs, hasMore]
      properties:
        runId:
          type: string
        sequence:
          type: integer
          format: int64
        logs:
          type: array
          items:
            $ref: "#/components/schemas/LogRecord"
        nextAfter:
          type: integer
          format: int64
        nextBefore:
          type: integer
          format: int64
        hasMore:
          type: boolean
    LogRecord:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        sequence:
          type: integer
          format: int64
        timestamp:
          type: string
          format: date-time
        level:
          type: string
        stream:
          type: string
          enum: [stdout, stderr, worker, platform]
        body:
          type: string
    ChatClarifyRequest:
      type: object
      required: [projectId]
      properties:
        projectId:
          type: string
        repositoryId:
          type: string
        repositoryIds:
          type: array
          items: {type: string}
        baseBranch:
          type: string
          description: Existing work branch to analyze and continue directly for a single repository; empty analyzes the configured main branch before creating a new work branch
        repositoryBranches:
          type: object
          additionalProperties: {type: string}
          description: Existing work branches to analyze keyed by bound repository ID; overrides baseBranch. Empty or unlisted branches analyze each repository's configured main branch.
        title:
          type: string
        description:
          type: string
        message:
          type: string
        history:
          type: array
          items:
            type: object
            required: [role, content]
            properties:
              role:
                type: string
              content:
                type: string
    ClarifyResult:
      type: object
      required: [result, parsed, repository]
      properties:
        result:
          type: string
        parsed:
          $ref: "#/components/schemas/OpenObject"
        repository:
          $ref: "#/components/schemas/OpenObject"
    SyncConfig:
      type: object
      properties:
        playbookSeedRev:
          type: integer
        gongfengProjectId:
          type: string
        gongfengMcpUrl:
          type: string
        tapdWorkspaceId:
          type: string
        tapdIterationId:
          type: string
        tapdMcpUrl:
          type: string
        autoSyncEnabled:
          type: boolean
        autoSyncIntervalSec:
          type: integer
        lastSyncAt:
          type: string
          format: date-time
          readOnly: true
        lastSyncStatus:
          type: string
          readOnly: true
        lastSyncError:
          type: string
          readOnly: true
    SyncLog:
      type: object
      properties:
        id:
          type: string
        direction:
          type: string
          enum: [pull, push]
        source:
          type: string
          enum: [gongfeng, tapd]
        action:
          type: string
        status:
          type: string
          enum: [success, failed]
        count:
          type: integer
        message:
          type: string
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
    ScheduleJob:
      type: object
      required: [name]
      properties:
        sharedTaskId: {type: string, description: Published shared AI task id; requires skipDispatch=true and a pinned version}
        sharedTaskVersion: {type: integer, minimum: 1, description: Explicit immutable version; changing it is a manual upgrade}
        parameterValues: {type: object, additionalProperties: {type: string}, description: Project-local parameter values; validated against the pinned version}
        notifications: {type: array, maxItems: 3, items: {$ref: "#/components/schemas/NotificationBinding"}, description: Optional Bot notifications for execution success/failure}
        id:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        projectId:
          type: string
        source:
          type: string
          enum: [gongfeng, tapd]
          description: Compatibility field; jobs no longer pull TAPD/Gongfeng themselves.
        tapdWorkspaceId:
          type: string
        tapdIterationId:
          type: string
        workflowId:
          type: string
          description: Required for trigger jobs. Ignored when skipDispatch is true.
        useIssueWorkflow:
          type: boolean
          description: When true, prefer the issue's bound SOP and fall back to workflowId.
        skipDispatch:
          type: boolean
          description: "When true, this is an AI scheduled job: run assistantPrompt only. When false, this is a trigger job that scans issues and dispatches SOP. The two kinds are exclusive."
        intervalSec:
          type: integer
          minimum: 0
          description: Used when cron is empty. Common values are 300, 900, 3600, 86400.
        cron:
          type: string
          description: Optional 5-field cron (minute hour day month weekday) in Asia/Shanghai. When set, intervalSec is ignored.
        assistantPrompt:
          type: string
          description: User-written prompt executed at schedule time. Required for independent AI jobs. Subscriptions resolve their pinned shared version. Cleared on trigger jobs.
        assistantModel:
          type: string
          description: Model id from GET /api/assistant/models?schedule=1.
        ownerUserId:
          type: integer
          format: int64
          description: Project owner recorded for jobs saved without a run-as identity.
        runAsUserId:
          type: integer
          format: int64
          readOnly: true
          description: User bound by the server to the last saver. Codex and Claude Code use configured account login on their online default personal Runner. Other configurations and offline Runners use the saver's personal API Key. CodeBuddy can use the shared key for allowed models if the personal key is missing. A bound user must retain write access to the project. Zero uses legacy owner selection.
        runAsName:
          type: string
          readOnly: true
          description: Display name of runAsUserId.
        sessionMode:
          type: string
          enum: ["", fixed]
          description: AI jobs only. Empty opens a new Studio conversation per execution; "fixed" keeps continuing one pinned conversation (fixedSessionId, server-managed).
        sessionKeep:
          type: integer
          enum: [10, 50, 100, -1]
          description: AI jobs that open a conversation per execution keep only their newest sessionKeep conversations; older ones are deleted after each execution (the execution records stay). -1 keeps all. Omitted or 0 saves the default 50; other values are rejected with 400. Ignored in fixed mode.
        lastRunAt:
          type: string
          format: date-time
          readOnly: true
        lastStatus:
          type: string
          enum: [running, success, failed, waiting]
          description: running means this instance is still executing the job (closing Studio does not cancel it).
          readOnly: true
        lastError:
          type: string
          readOnly: true
        lastPulled:
          type: integer
          description: Candidate issues scanned in the project
          readOnly: true
        lastDispatched:
          type: integer
          readOnly: true
        lastAssistantMessage:
          type: string
          readOnly: true
        lastTraceId:
          type: string
          description: Trace ID of the latest execution; matches ScheduleJobExecution.traceId and the scheduler log lines.
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    ScheduleExecutionWindow:
      type: object
      description: Executions started in one window. total = finished + running; avgMs averages finished executions with a duration.
      properties:
        total: { type: integer }
        finished: { type: integer }
        success: { type: integer }
        failed: { type: integer }
        running: { type: integer }
        avgMs: { type: integer, format: int64 }
    ScheduleJobExecution:
      type: object
      description: One execution of a schedule job. Each job keeps its latest 200 executions.
      properties:
        id:
          type: string
        jobId:
          type: string
        jobName:
          type: string
        jobKind:
          type: string
          enum: [assistant, trigger]
        projectId:
          type: string
        traceId:
          type: string
          description: 32-hex trace ID, also written to every scheduler log line of this execution.
        triggerOrigin:
          type: string
          enum: [timer, manual_run]
        status:
          type: string
          enum: [running, success, failed, waiting]
        error:
          type: string
        pulled:
          type: integer
        dispatched:
          type: integer
        assistantMessage:
          type: string
        sessionId:
          type: string
          description: Studio conversation an AI execution ran in.
        sessionGone:
          type: boolean
          description: Computed on each read, never stored. True when sessionId names a conversation that no longer exists (trimmed by the job's sessionKeep or the retention period, or deleted by hand). Running executions are never marked.
        runs:
          type: array
          items:
            type: object
            properties:
              issueId:
                type: string
              issueTitle:
                type: string
              runId:
                type: string
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
        durationMs:
          type: integer
    WorkflowMetrics:
      type: object
      additionalProperties: true
      properties:
        workflowId:
          type: string
        totalRuns:
          type: integer
        activeRuns:
          type: integer
        waitingRuns:
          type: integer
        succeededRuns:
          type: integer
        failedRuns:
          type: integer
        closureRate:
          type: number
        successRate:
          type: number
        averageDurationMs:
          type: integer
          format: int64
        totalTokens:
          type: integer
          format: int64
    AnalyticsCostSummary:
      type: object
      additionalProperties: true
      description: 'Operational summary. Costs are public standard token estimates except HY reported charges; raw billing facts are unchanged. All analytics breakdowns, trends, traces and delivery rows additionally expose costCny; legacy costUsd fields are USD equivalents of the CNY statistic.'
      properties:
        costCurrency: {type: string, const: CNY}
        usdToCny: {type: number, const: 7}
        costPricingVersion: {type: string}
        totalCostCny: {type: number}
        costReportedCny: {type: number, description: 'Recognized amount, including recognized parts of incompletely priced runs'}
        costCoveragePct: {type: number}
        costUnknownRuns: {type: integer}
    AnalyticsDeliveryMR:
      type: object
      additionalProperties: true
      properties:
        project: {type: string}
        iid: {type: integer}
        url: {type: string}
        state: {type: string, description: 'State of this individual MR, including merged or integrated'}
        targetBranch: {type: string}
    AnalyticsDelivery:
      type: object
      additionalProperties: true
      properties:
        mrs:
          type: array
          description: 'All associated MRs; singular mrUrl, mrIid and mrState remain primary-link compatibility fields'
          items:
            $ref: "#/components/schemas/AnalyticsDeliveryMR"
    AnalyticsDeliverySummary:
      type: object
      additionalProperties: true
      properties:
        issues: {type: integer}
        withMr: {type: integer, description: 'Requirements with an MR, used by the requirement funnel'}
        totalMrs: {type: integer, description: 'Unique repository and MR IID pairs'}
        mrMerged: {type: integer, description: 'Individual MRs landed on mainline'}
        mrIntegrated: {type: integer, description: 'Individual MRs landed on an integration branch'}
        issuesWithMergedMr: {type: integer, description: 'Requirements with a mainline MR, used by the requirement funnel'}
    AnalyticsSnapshot:
      type: object
      additionalProperties: true
      required: [filter, summary, trend, workflows, agents, executors, models, nodes, failures, coverage, delivery, demo]
      properties:
        filter:
          $ref: "#/components/schemas/OpenObject"
        summary:
          $ref: "#/components/schemas/AnalyticsCostSummary"
        trend:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        workflows:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        agents:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        executors:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        models:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        failures:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        coverage:
          $ref: "#/components/schemas/OpenObject"
        deliveries:
          type: array
          items:
            $ref: "#/components/schemas/AnalyticsDelivery"
        delivery:
          $ref: "#/components/schemas/AnalyticsDeliverySummary"
        demo:
          $ref: "#/components/schemas/OpenObject"
        runTraces:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
    Bootstrap:
      type: object
      additionalProperties: true
      required:
        - projects
        - repositories
        - users
        - agents
        - rules
        - skills
        - mcpServers
        - executors
        - dockerfiles
        - environments
        - sandboxes
        - workflows
        - syncConfig
        - scheduleJobs
        - schedulerEnabled
        - storage
      properties:
        projects:
          type: array
          items:
            $ref: "#/components/schemas/Project"
        repositories:
          type: array
          items:
            $ref: "#/components/schemas/Repository"
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
        agents:
          type: array
          items:
            $ref: "#/components/schemas/AgentDefinition"
        rules:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        skills:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        mcpServers:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        executors:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        dockerfiles:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        environments:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        sandboxes:
          type: array
          items:
            $ref: "#/components/schemas/OpenObject"
        workflows:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowDefinition"
        syncConfig:
          $ref: "#/components/schemas/SyncConfig"
        scheduleJobs:
          type: array
          items:
            $ref: "#/components/schemas/ScheduleJob"
        schedulerEnabled:
          type: boolean
        storage:
          $ref: "#/components/schemas/OpenObject"

    ScheduleParameter:
      type: object
      required: [name, label, type]
      properties:
        name: {type: string, pattern: '^[a-zA-Z][a-zA-Z0-9_]{0,31}$'}
        label: {type: string}
        type: {type: string, enum: [string, integer, number, boolean]}
        required: {type: boolean}
        default: {type: string}
    SharedScheduleVersion:
      type: object
      properties:
        id: {type: string}
        version: {type: integer, minimum: 1}
        sourceProjectId: {type: string}
        sourceProjectName: {type: string}
        sourceJobId: {type: string}
        name: {type: string}
        description: {type: string}
        prompt: {type: string}
        model: {type: string}
        cron: {type: string}
        intervalSec: {type: integer}
        parameters: {type: array, items: {$ref: "#/components/schemas/ScheduleParameter"}}
        changeNote: {type: string}
        createdAt: {type: string, format: date-time}