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.
JavaScript agent-orchestrationagentic-workflowai-agentsai-codingclaude-codecode-reviewcodebuddycodexcoding-agentscursordeveloper-toolshuman-on-the-loopllmmcpmulti-agentsdlcself-hostedsopworkflow-automationworkflow-engine
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}