代码提交
This commit is contained in:
1 parent
4ac7bc21cd
commit
17cf849361
110 files changed
+17007
-518
No files matched your search
@@ -0,0 +1,740 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: DeerFlow Workflow Studio API (Draft v1)
|
||||
version: "1.0.0-draft"
|
||||
description: |
|
||||
Wire models: deerflow.workflows.schemas / events / errors.
|
||||
|
||||
Paths marked `x-implemented: false` are still sketches; everything else is
|
||||
mounted today (app/gateway/routers/workflow*.py). Where the phase-0 sketch
|
||||
and the implementation disagreed, this file follows the implementation.
|
||||
servers:
|
||||
- url: http://localhost:8001
|
||||
description: Local Gateway
|
||||
tags:
|
||||
- name: workflows
|
||||
- name: runs
|
||||
- name: resources
|
||||
- name: data-sources
|
||||
- name: embed
|
||||
- name: coze-compat
|
||||
paths:
|
||||
/api/workflows:
|
||||
get:
|
||||
tags: [workflows]
|
||||
summary: List workflow definitions
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
post:
|
||||
tags: [workflows]
|
||||
summary: Create workflow definition
|
||||
responses:
|
||||
"201":
|
||||
description: Created
|
||||
/api/workflows/{workflow_id}:
|
||||
get:
|
||||
tags: [workflows]
|
||||
summary: Get workflow definition
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
patch:
|
||||
tags: [workflows]
|
||||
summary: Update workflow metadata
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
delete:
|
||||
tags: [workflows]
|
||||
summary: Soft-delete / archive
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"204":
|
||||
description: Archived
|
||||
/api/workflows/{workflow_id}/copy:
|
||||
post:
|
||||
tags: [workflows]
|
||||
summary: Duplicate a workflow as a new draft owned by the caller
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"200":
|
||||
description: Created copy
|
||||
/api/workflows/{workflow_id}/draft:
|
||||
put:
|
||||
tags: [workflows]
|
||||
summary: Save draft (optimistic lock)
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [expectedRevision, graph]
|
||||
properties:
|
||||
expectedRevision:
|
||||
type: integer
|
||||
graph:
|
||||
$ref: "#/components/schemas/WorkflowGraph"
|
||||
responses:
|
||||
"200":
|
||||
description: Saved
|
||||
"409":
|
||||
description: Draft revision conflict
|
||||
/api/workflows/{workflow_id}/validate:
|
||||
post:
|
||||
tags: [workflows]
|
||||
summary: Validate draft without publishing
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"200":
|
||||
description: Validation result
|
||||
/api/workflows/{workflow_id}/publish:
|
||||
post:
|
||||
tags: [workflows]
|
||||
summary: Publish immutable version
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"201":
|
||||
description: Version created
|
||||
/api/workflows/{workflow_id}/versions:
|
||||
get:
|
||||
tags: [workflows]
|
||||
summary: List published versions
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/{workflow_id}/versions/{version_id}:
|
||||
get:
|
||||
tags: [workflows]
|
||||
summary: Get one published version snapshot
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
- $ref: "#/components/parameters/VersionId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/node-types:
|
||||
get:
|
||||
tags: [resources]
|
||||
summary: List supported node types
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/resources/agents:
|
||||
get:
|
||||
tags: [resources]
|
||||
summary: Agents available to workflow nodes
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/resources/skills:
|
||||
get:
|
||||
tags: [resources]
|
||||
summary: Skills available to workflow nodes
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/resources/data-sources:
|
||||
get:
|
||||
tags: [resources]
|
||||
summary: Registered read-only data sources
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/resources/subworkflows:
|
||||
get:
|
||||
tags: [resources]
|
||||
summary: Published workflows usable as subworkflows
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/data-sources:
|
||||
get:
|
||||
tags: [data-sources]
|
||||
summary: List data sources visible to the caller (own + shared)
|
||||
description: |
|
||||
Never returns the DSN or credential headers — only `masked_target`.
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
post:
|
||||
tags: [data-sources]
|
||||
summary: Register a data source (`shared: true` is admin-only)
|
||||
description: |
|
||||
`kind: sql` requires `dsn`; `kind: http` requires `headers`. The secret
|
||||
is encrypted on write and only ever decrypted inside the run executor.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DataSourceCreate"
|
||||
responses:
|
||||
"200":
|
||||
description: Created (masked view)
|
||||
"503":
|
||||
description: WORKFLOW_SECRET_KEY not configured
|
||||
/api/workflows/data-sources/{id}:
|
||||
get:
|
||||
tags: [data-sources]
|
||||
summary: Get one data source (masked view)
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/DataSourceId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
put:
|
||||
tags: [data-sources]
|
||||
summary: Update data source (owner or admin)
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/DataSourceId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
delete:
|
||||
tags: [data-sources]
|
||||
summary: Delete data source (owner or admin)
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/DataSourceId"
|
||||
responses:
|
||||
"200":
|
||||
description: '{ "deleted": true }'
|
||||
/api/workflows/data-sources/{id}/introspect:
|
||||
post:
|
||||
tags: [data-sources]
|
||||
summary: Introspect whitelisted schema/table/column metadata
|
||||
description: Returns the configured table allowlist only. Never returns sample rows or secrets.
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/DataSourceId"
|
||||
responses:
|
||||
"200":
|
||||
description: '{ dataSourceId, kind, tables, schemas }'
|
||||
/api/workflows/data-sources/{id}/validate-query:
|
||||
post:
|
||||
tags: [data-sources]
|
||||
summary: Validate SQL against read-only policy (no execution)
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/DataSourceId"
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [statement]
|
||||
properties:
|
||||
statement:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: '{ ok: true, statement }'
|
||||
"400":
|
||||
description: WORKFLOW_SQL_POLICY_DENIED
|
||||
/api/workflows/{workflow_id}/runs:
|
||||
post:
|
||||
tags: [runs]
|
||||
summary: Start a run against a published version
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/StartRunRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: |
|
||||
Run view plus `created`; `created: false` means the idempotencyKey
|
||||
matched an existing run (scoped per workflow).
|
||||
"400":
|
||||
description: WORKFLOW_INPUT_INVALID / WORKFLOW_VERSION_NOT_FOUND
|
||||
"429":
|
||||
description: WORKFLOW_LIMIT_EXCEEDED (per-user concurrent runs)
|
||||
get:
|
||||
tags: [runs]
|
||||
summary: List runs for a workflow
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/WorkflowId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/runs/{run_id}:
|
||||
get:
|
||||
tags: [runs]
|
||||
summary: Get run status projection plus current node runs
|
||||
description: |
|
||||
Never includes `resumeToken` — that is delivered on the event stream only.
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/RunId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
"403":
|
||||
description: WORKFLOW_FORBIDDEN (not owner, not admin)
|
||||
"404":
|
||||
description: WORKFLOW_RUN_NOT_FOUND
|
||||
/api/workflows/runs/{run_id}/events:
|
||||
get:
|
||||
tags: [runs]
|
||||
summary: Page durable events
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/RunId"
|
||||
- name: after
|
||||
in: query
|
||||
description: Exclusive `seq` cursor. `after_seq` is accepted as an alias.
|
||||
schema:
|
||||
type: integer
|
||||
default: 0
|
||||
- name: after_seq
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
- name: limit
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 200
|
||||
maximum: 1000
|
||||
responses:
|
||||
"200":
|
||||
description: '{ "events": [...], "lastSeq": 42 }'
|
||||
/api/workflows/runs/{run_id}/stream:
|
||||
get:
|
||||
tags: [runs]
|
||||
summary: SSE replay + live tail
|
||||
description: |
|
||||
Replays from `Last-Event-ID` (preferred) or `after` / `after_seq`, then
|
||||
tails live. Closes on the first terminal event; if the run is already
|
||||
terminal without one, a synthesised terminal frame is emitted so the
|
||||
client never hangs.
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/RunId"
|
||||
- name: after
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 0
|
||||
- name: after_seq
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
- name: Last-Event-ID
|
||||
in: header
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: text/event-stream
|
||||
headers:
|
||||
X-Workflow-Run-Status:
|
||||
description: Run status at connection time.
|
||||
schema:
|
||||
type: string
|
||||
content:
|
||||
text/event-stream:
|
||||
schema:
|
||||
type: string
|
||||
/api/workflows/runs/{run_id}/cancel:
|
||||
post:
|
||||
tags: [runs]
|
||||
summary: Request cancellation (idempotent)
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/RunId"
|
||||
responses:
|
||||
"200":
|
||||
description: |
|
||||
Run view plus `cancelled`; `false` means it was already terminal.
|
||||
/api/workflows/runs/{run_id}/resume:
|
||||
post:
|
||||
tags: [runs]
|
||||
summary: Resume after human_input
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/RunId"
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ResumeRunRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: Requeued
|
||||
"409":
|
||||
description: WORKFLOW_RUN_NOT_RESUMABLE / WORKFLOW_RESUME_TOKEN_INVALID
|
||||
/api/workflows/runs/{run_id}/retry:
|
||||
post:
|
||||
tags: [runs]
|
||||
summary: Retry a failed run from the first unfinished node
|
||||
description: |
|
||||
Creates a new queued run with `retryOfRunId` pointing at the failed
|
||||
original. Completed `workflow_node_runs` are copied so the engine
|
||||
resumes from the failed node; if nothing is replayable it is a full
|
||||
re-run of the same version and inputs. Only `failed` runs are retryable.
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/RunId"
|
||||
responses:
|
||||
"201":
|
||||
description: '{ ..., retryOfRunId, created: true }'
|
||||
"409":
|
||||
description: WORKFLOW_RUN_NOT_RETRYABLE
|
||||
"429":
|
||||
description: WORKFLOW_LIMIT_EXCEEDED
|
||||
/api/workflows/runs/{run_id}/artifacts:
|
||||
get:
|
||||
tags: [runs]
|
||||
summary: List artifacts for a run
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/RunId"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/workflows/embed/tickets:
|
||||
post:
|
||||
tags: [embed]
|
||||
summary: Issue a short-lived iframe ticket (authenticated parent)
|
||||
description: |
|
||||
`origin` must exactly match `workflows.embed.allowed_origins`. The
|
||||
response also carries `frameAncestors` for the host's CSP.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [workflowId, origin]
|
||||
properties:
|
||||
workflowId:
|
||||
type: string
|
||||
origin:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: '{ ticket, expiresIn, origin, frameAncestors }'
|
||||
"403":
|
||||
description: WORKFLOW_EMBED_ORIGIN_DENIED / WORKFLOW_FORBIDDEN
|
||||
"503":
|
||||
description: No signing key configured
|
||||
/api/workflows/embed/verify:
|
||||
post:
|
||||
tags: [embed]
|
||||
summary: Verify a ticket (single-use, best effort per process)
|
||||
description: |
|
||||
A ticket proves "this origin may embed this workflow for this user right
|
||||
now". It is NOT an API credential — embedded pages still authenticate
|
||||
their API calls with the normal session.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [ticket]
|
||||
properties:
|
||||
ticket:
|
||||
type: string
|
||||
origin:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: '{ ok, workflowId, userId, origin, expiresAt }'
|
||||
"401":
|
||||
description: WORKFLOW_EMBED_TICKET_INVALID (expired or replayed)
|
||||
"403":
|
||||
description: WORKFLOW_EMBED_ORIGIN_DENIED (origin mismatch)
|
||||
/api/workflow_api/canvas:
|
||||
post:
|
||||
tags: [coze-compat]
|
||||
summary: Coze canvas load adapter
|
||||
responses:
|
||||
"200":
|
||||
description: Coze DTO
|
||||
/api/workflow_api/save:
|
||||
post:
|
||||
tags: [coze-compat]
|
||||
summary: Coze canvas save adapter
|
||||
responses:
|
||||
"200":
|
||||
description: Saved
|
||||
/api/workflow_api/create:
|
||||
post:
|
||||
tags: [coze-compat]
|
||||
summary: Coze create workflow adapter
|
||||
responses:
|
||||
"200":
|
||||
description: Created
|
||||
/api/workflow_api/node_template_list:
|
||||
post:
|
||||
tags: [coze-compat]
|
||||
summary: Coze node template list adapter
|
||||
responses:
|
||||
"200":
|
||||
description: Templates
|
||||
components:
|
||||
parameters:
|
||||
WorkflowId:
|
||||
name: workflow_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
VersionId:
|
||||
name: version_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
RunId:
|
||||
name: run_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
DataSourceId:
|
||||
name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
schemas:
|
||||
WorkflowGraph:
|
||||
type: object
|
||||
description: Internal standard graph (see WORKFLOW_SCHEMA_V1_ZH.md)
|
||||
required: [schemaVersion, id, nodes, edges]
|
||||
properties:
|
||||
schemaVersion:
|
||||
type: string
|
||||
enum: ["1.0"]
|
||||
id:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
inputSchema:
|
||||
type: object
|
||||
outputSchema:
|
||||
type: object
|
||||
nodes:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/WorkflowNode"
|
||||
edges:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/WorkflowEdge"
|
||||
settings:
|
||||
$ref: "#/components/schemas/WorkflowGraphSettings"
|
||||
WorkflowNode:
|
||||
type: object
|
||||
required: [id, type]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- start
|
||||
- output
|
||||
- agent
|
||||
- skill
|
||||
- http
|
||||
- sql_read
|
||||
- code
|
||||
- transform
|
||||
- condition
|
||||
- merge
|
||||
- human_input
|
||||
- subworkflow
|
||||
- loop
|
||||
name:
|
||||
type: string
|
||||
config:
|
||||
type: object
|
||||
WorkflowEdge:
|
||||
type: object
|
||||
required: [id, source, target]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
source:
|
||||
type: string
|
||||
target:
|
||||
type: string
|
||||
sourcePort:
|
||||
type: string
|
||||
nullable: true
|
||||
WorkflowGraphSettings:
|
||||
type: object
|
||||
properties:
|
||||
runTimeoutSeconds:
|
||||
type: integer
|
||||
default: 1800
|
||||
nodeTimeoutSeconds:
|
||||
type: integer
|
||||
default: 300
|
||||
maxSteps:
|
||||
type: integer
|
||||
default: 200
|
||||
maxLoopIterations:
|
||||
type: integer
|
||||
default: 5
|
||||
maxParallelism:
|
||||
type: integer
|
||||
default: 4
|
||||
NodeResult:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
messages:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
artifacts:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/ArtifactRef"
|
||||
metadata:
|
||||
type: object
|
||||
warnings:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
ArtifactRef:
|
||||
type: object
|
||||
required: [artifactId, name]
|
||||
properties:
|
||||
artifactId:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
mimeType:
|
||||
type: string
|
||||
path:
|
||||
type: string
|
||||
sizeBytes:
|
||||
type: integer
|
||||
nullable: true
|
||||
preview:
|
||||
type: string
|
||||
nullable: true
|
||||
StartRunRequest:
|
||||
type: object
|
||||
properties:
|
||||
versionId:
|
||||
type: string
|
||||
description: Omit to use the latest published version.
|
||||
inputs:
|
||||
type: object
|
||||
idempotencyKey:
|
||||
type: string
|
||||
maxLength: 128
|
||||
executionMode:
|
||||
type: string
|
||||
enum: [normal]
|
||||
default: normal
|
||||
ResumeRunRequest:
|
||||
type: object
|
||||
required: [resumeToken]
|
||||
properties:
|
||||
resumeToken:
|
||||
type: string
|
||||
nodeId:
|
||||
type: string
|
||||
description: Defaults to the paused node from `pendingInput`.
|
||||
action:
|
||||
type: string
|
||||
default: submit
|
||||
values:
|
||||
type: object
|
||||
DataSourceCreate:
|
||||
type: object
|
||||
required: [name]
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
kind:
|
||||
type: string
|
||||
enum: [sql, http]
|
||||
default: sql
|
||||
dsn:
|
||||
type: string
|
||||
description: Write-only; required for `kind: sql`.
|
||||
headers:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: Write-only; required for `kind: http`.
|
||||
maxRows:
|
||||
type: integer
|
||||
default: 1000
|
||||
allowedTables:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
enabled:
|
||||
type: boolean
|
||||
default: true
|
||||
shared:
|
||||
type: boolean
|
||||
default: false
|
||||
description: Admin-only. Shared sources have a null owner.
|
||||
WorkflowEventEnvelope:
|
||||
type: object
|
||||
required: [schemaVersion, runId, workflowId, versionId, seq, event]
|
||||
properties:
|
||||
schemaVersion:
|
||||
type: string
|
||||
enum: ["1.0"]
|
||||
runId:
|
||||
type: string
|
||||
workflowId:
|
||||
type: string
|
||||
versionId:
|
||||
type: string
|
||||
seq:
|
||||
type: integer
|
||||
event:
|
||||
type: string
|
||||
nodeId:
|
||||
type: string
|
||||
nullable: true
|
||||
nodeRunId:
|
||||
type: string
|
||||
nullable: true
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
data:
|
||||
type: object
|
||||
WorkflowErrorBody:
|
||||
type: object
|
||||
required: [code, message]
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
message:
|
||||
type: string
|
||||
retryable:
|
||||
type: boolean
|
||||
nodeId:
|
||||
type: string
|
||||
nullable: true
|
||||
details:
|
||||
type: object
|
||||
Reference in new issue
Block a user