mirror of https://github.com/langgenius/dify.git synced 2026-06-13 04:01:12 +08:00

fix: GET query parameter OpenAPI contracts (#37378 )

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

2026-06-12 09:01:22 +00:00

31 KiB

Raw Blame History

OpenAPI

User-scoped programmatic API (bearer auth)

Version: 1.0

Available authorizations

Bearer (API Key Authentication)

Type: Bearer {your-api-key}
Name: Authorization
In: header

openapi

User-scoped operations

[GET] /_health

Responses

Code	Description	Schema
200	Health check	application/json: HealthResponse
default	Error	application/json: ErrorBody

[GET] /_version

Responses

Code	Description	Schema
200	Server version	application/json: ServerVersionResponse
default	Error	application/json: ErrorBody

[GET] /account

Responses

Code	Description	Schema
200	Account info	application/json: AccountResponse
default	Error	application/json: ErrorBody

[GET] /account/sessions

Parameters

Name	Located in	Description	Required	Schema
limit	query		No	integer, Default: 100
page	query		No	integer, Default: 1

Responses

Code	Description	Schema
200	Session list	application/json: SessionListResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[DELETE] /account/sessions/self

Responses

Code	Description	Schema
200	Session revoked	application/json: RevokeResponse
default	Error	application/json: ErrorBody

[DELETE] /account/sessions/{session_id}

Parameters

Name	Located in	Description	Required	Schema
session_id	path		Yes	string

Responses

Code	Description	Schema
200	Session revoked	application/json: RevokeResponse
default	Error	application/json: ErrorBody

[GET] /apps

Parameters

Name	Located in	Required	Schema
limit	query	No	integer, Default: 20
mode	query	No	string, Available values: "advanced-chat", "agent", "agent-chat", "channel", "chat", "completion", "rag-pipeline", "workflow"
name	query	No	string
page	query	No	integer, Default: 1
tag	query	No	string
workspace_id	query	Yes	string

Responses

Code	Description	Schema
200	App list	application/json: AppListResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /apps/{app_id}/check-dependencies

Parameters

Name	Located in	Description	Required	Schema
app_id	path		Yes	string

Responses

Code	Description	Schema
200	Dependencies checked	application/json: CheckDependenciesResult
default	Error	application/json: ErrorBody

[GET] /apps/{app_id}/describe

Parameters

Name	Located in	Description	Required	Schema
fields	query		No	string
app_id	path		Yes	string

Responses

Code	Description	Schema
200	App description	application/json: AppDescribeResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /apps/{app_id}/export

Parameters

Name	Located in	Description	Required	Schema
include_secret	query	Include encrypted secret values in the exported DSL	No	boolean
workflow_id	query	Export a specific workflow version instead of the current draft	No	string
app_id	path		Yes	string

Responses

Code	Description	Schema
200	Export successful	application/json: AppDslExportResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[POST] /apps/{app_id}/files/upload

Upload a file to use as an input variable when running the app

Parameters

Name	Located in	Description	Required	Schema
app_id	path		Yes	string

Responses

Code	Description	Schema
201	File uploaded successfully	application/json: FileResponse
400	Bad request — no file or filename missing
401	Unauthorized — invalid or expired bearer token
413	File too large
415	Unsupported file type or blocked extension
default	Error	application/json: ErrorBody

[GET] /apps/{app_id}/form/human_input/{form_token}

Parameters

Name	Located in	Description	Required	Schema
app_id	path		Yes	string
form_token	path		Yes	string

Responses

Code	Description
200	Form definition

[POST] /apps/{app_id}/form/human_input/{form_token}

Parameters

Name	Located in	Description	Required	Schema
app_id	path		Yes	string
form_token	path		Yes	string

Request Body

Required	Schema
Yes	application/json: HumanInputFormSubmitPayload

Responses

Code	Description	Schema
200	Form submitted	application/json: FormSubmitResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[POST] /apps/{app_id}/run

Parameters

Name	Located in	Description	Required	Schema
app_id	path		Yes	string

Request Body

Required	Schema
Yes	application/json: AppRunRequest

Responses

Code	Description	Schema
200	Run result (SSE stream)
422	Validation error	application/json: ErrorBody

[GET] /apps/{app_id}/tasks/{task_id}/events

Parameters

Name	Located in	Description	Required	Schema
app_id	path		Yes	string
task_id	path		Yes	string

Responses

Code	Description
200	SSE event stream

[POST] /apps/{app_id}/tasks/{task_id}/stop

Parameters

Name	Located in	Description	Required	Schema
app_id	path		Yes	string
task_id	path		Yes	string

Responses

Code	Description	Schema
200	Task stopped	application/json: TaskStopResponse
default	Error	application/json: ErrorBody

[POST] /oauth/device/approve

Request Body

Required	Schema
Yes	application/json: DeviceMutateRequest

Responses

Code	Description	Schema
200	Approved	application/json: DeviceMutateResponse

[POST] /oauth/device/code

Request Body

Required	Schema
Yes	application/json: DeviceCodeRequest

Responses

Code	Description	Schema
200	Device code created	application/json: DeviceCodeResponse

[POST] /oauth/device/deny

Request Body

Required	Schema
Yes	application/json: DeviceMutateRequest

Responses

Code	Description	Schema
200	Denied	application/json: DeviceMutateResponse

[GET] /oauth/device/lookup

Parameters

Name	Located in	Description	Required	Schema
user_code	query		Yes	string

Responses

Code	Description	Schema
200	Device lookup result	application/json: DeviceLookupResponse

[POST] /oauth/device/token

Request Body

Required	Schema
Yes	application/json: DevicePollRequest

Responses

Code	Description
200	Success

[GET] /permitted-external-apps

Parameters

Name	Located in	Required	Schema
limit	query	No	integer, Default: 20
mode	query	No	string, Available values: "advanced-chat", "agent", "agent-chat", "channel", "chat", "completion", "rag-pipeline", "workflow"
name	query	No	string
page	query	No	integer, Default: 1

Responses

Code	Description	Schema
200	Permitted external apps list	application/json: PermittedExternalAppsListResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /workspaces

Responses

Code	Description	Schema
200	Workspace list	application/json: WorkspaceListResponse
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}

Parameters

Name	Located in	Description	Required	Schema
workspace_id	path		Yes	string

Responses

Code	Description	Schema
200	Workspace detail	application/json: WorkspaceDetailResponse
default	Error	application/json: ErrorBody

[POST] /workspaces/{workspace_id}/apps/imports

Parameters

Name	Located in	Description	Required	Schema
workspace_id	path		Yes	string

Request Body

Required	Schema
Yes	application/json: AppDslImportPayload

Responses

Code	Description	Schema
200	Import completed	application/json: Import
202	Import pending confirmation	application/json: Import
400	Import failed	application/json: Import
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[POST] /workspaces/{workspace_id}/apps/imports/{import_id}/confirm

Parameters

Name	Located in	Description	Required	Schema
import_id	path		Yes	string
workspace_id	path		Yes	string

Responses

Code	Description	Schema
200	Import confirmed	application/json: Import
400	Import failed	application/json: Import
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}/members

Parameters

Name	Located in	Required	Schema
limit	query	No	integer, Default: 20
page	query	No	integer, Default: 1
workspace_id	path	Yes	string

Responses

Code	Description	Schema
200	Member list	application/json: MemberListResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[POST] /workspaces/{workspace_id}/members

Parameters

Name	Located in	Description	Required	Schema
workspace_id	path		Yes	string

Request Body

Required	Schema
Yes	application/json: MemberInvitePayload

Responses

Code	Description	Schema
201	Member invited	application/json: MemberInviteResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[DELETE] /workspaces/{workspace_id}/members/{member_id}

Parameters

Name	Located in	Description	Required	Schema
member_id	path		Yes	string
workspace_id	path		Yes	string

Responses

Code	Description	Schema
200	Member removed	application/json: MemberActionResponse
default	Error	application/json: ErrorBody

[PUT] /workspaces/{workspace_id}/members/{member_id}/role

Parameters

Name	Located in	Description	Required	Schema
member_id	path		Yes	string
workspace_id	path		Yes	string

Request Body

Required	Schema
Yes	application/json: MemberRoleUpdatePayload

Responses

Code	Description	Schema
200	Role updated	application/json: MemberActionResponse
422	Validation error	application/json: ErrorBody
default	Error	application/json: ErrorBody

[POST] /workspaces/{workspace_id}/switch

Parameters

Name	Located in	Description	Required	Schema
workspace_id	path		Yes	string

Responses

Code	Description	Schema
200	Workspace detail	application/json: WorkspaceDetailResponse
default	Error	application/json: ErrorBody

Schemas

AccountPayload

Name	Type	Required
email	string	Yes
id	string	Yes
name	string	Yes

AccountResponse

Name	Type	Required
account	AccountPayload	No
default_workspace_id	string	No
subject_email	string	No
subject_issuer	string	No
subject_type	string	Yes
workspaces	[ WorkspacePayload ], Default:	No

AppDescribeInfo

Name	Type	Required
author	string	No
description	string	No
id	string	Yes
is_agent	boolean	No
mode	string	Yes
name	string	Yes
service_api_enabled	boolean	Yes
tags	[ TagItem ], Default:	No
updated_at	string	No

AppDescribeQuery

?fields= allow-list for GET /apps//describe.

Empty / omitted → all blocks. Unknown member → ValidationError → 422.

Name	Type	Description	Required
fields	string		No

AppDescribeResponse

Name	Type	Required
info	AppDescribeInfo	No
input_schema	object	No
parameters	object	No

AppDslExportQuery

Query parameters for GET /apps/<app_id>/export.

Name	Type	Description	Required
include_secret	boolean	Include encrypted secret values in the exported DSL	No
workflow_id	string	Export a specific workflow version instead of the current draft	No

AppDslExportResponse

Export DSL response.

Name	Type	Description	Required
data	string	DSL YAML string	Yes

AppDslImportPayload

Request body for POST /workspaces/<workspace_id>/apps/imports.

Name	Type	Description	Required
app_id	string	Existing app ID to overwrite (workflow/advanced-chat apps only)	No
description	string	Override the app description from the DSL	No
icon	string		No
icon_background	string		No
icon_type	string		No
mode	string, Available values: "yaml-content", "yaml-url"	Import mode: yaml-content or yaml-url Enum: `"yaml-content"`, `"yaml-url"`	Yes
name	string	Override the app name from the DSL	No
yaml_content	string	Inline YAML DSL string (required when mode is yaml-content)	No
yaml_url	string	Remote URL to fetch YAML from (required when mode is yaml-url)	No

AppInfoResponse

Name	Type	Required
author	string	No
description	string	No
id	string	Yes
mode	string	Yes
name	string	Yes
tags	[ TagItem ], Default:	No

AppListQuery

mode is a closed enum.

Name	Type	Required
limit	integer, Default: 20	No
mode	AppMode	No
name	string	No
page	integer, Default: 1	No
tag	string	No
workspace_id	string	Yes

AppListResponse

Name	Type	Required
data	[ AppListRow ]	Yes
has_more	boolean	Yes
limit	integer	Yes
page	integer	Yes
total	integer	Yes

AppListRow

Name	Type	Required
created_by_name	string	No
description	string	No
id	string	Yes
mode	AppMode	Yes
name	string	Yes
tags	[ TagItem ], Default:	No
updated_at	string	No
workspace_id	string	No
workspace_name	string	No

AppMode

Name	Type	Description	Required
AppMode	string

AppRunRequest

Name	Type	Required
auto_generate_name	boolean, Default: true	No
conversation_id	string	No
files	[ object ]	No
inputs	object	Yes
query	string	No
workflow_id	string	No
workspace_id	string	No

CheckDependenciesResult

Name	Type	Description	Required
leaked_dependencies	[ PluginDependency ]		No

DeviceCodeRequest

Name	Type	Description	Required
client_id	string		Yes
device_label	string		Yes

DeviceCodeResponse

Name	Type	Required
device_code	string	Yes
expires_in	integer	Yes
interval	integer	Yes
user_code	string	Yes
verification_uri	string	Yes

DeviceLookupQuery

Name	Type	Description	Required
user_code	string		Yes

DeviceLookupResponse

Name	Type	Required
client_id	string	No
expires_in_remaining	integer	No
valid	boolean	Yes

DeviceMutateRequest

Name	Type	Description	Required
user_code	string		Yes

DeviceMutateResponse

Name	Type	Description	Required
status	string		Yes

DevicePollRequest

Name	Type	Description	Required
client_id	string		Yes
device_code	string		Yes

ErrorBody

Canonical non-2xx body. code is typed str (not the enum) so the generated client schema stays an open enum — old CLIs keep parsing when a future server adds a code. Formatter tests pin emitted values to the enum.

Name	Type	Required
code	string	Yes
details	[ ErrorDetail ]	No
hint	string	No
message	string	Yes
status	integer	Yes

ErrorDetail

Name	Type	Required
loc	[ ], Default:	No
msg	string	Yes
type	string	Yes

FileResponse

Name	Type	Required
conversation_id	string	No
created_at	integer	No
created_by	string	No
extension	string	No
file_key	string	No
id	string	Yes
mime_type	string	No
name	string	Yes
original_url	string	No
preview_url	string	No
reference	string	No
size	integer	Yes
source_url	string	No
tenant_id	string	No
user_id	string	No

FormSubmitResponse

Empty 200 body for POST /apps//form/human_input/. extra='forbid' pins additionalProperties: false so the generated contract is an exact {} rather than an under-annotated open object.

Name	Type	Description	Required

Github

Name	Type	Required
github_plugin_unique_identifier	string	Yes
package	string	Yes
repo	string	Yes
version	string	Yes

HealthResponse

Liveness payload for GET /openapi/v1/_health — no auth required.

Name	Type	Description	Required
ok	boolean		Yes

HumanInputFormSubmitPayload

Name	Type	Description	Required
action	string		Yes
inputs	object	Submitted human input values keyed by output variable name. Use a string for paragraph or select input values, a file mapping for file inputs, and a list of file mappings for file-list inputs. Local file mappings use `transfer_method=local_file` with `upload_file_id`; remote file mappings use `transfer_method=remote_url` with `url` or `remote_url`.	Yes

Import

Name	Type	Required
app_id	string	No
app_mode	string	No
current_dsl_version	string, Default: 0.6.0	No
error	string	No
id	string	Yes
imported_dsl_version	string	No
status	ImportStatus	Yes

ImportStatus

Name	Type	Description	Required
ImportStatus	string

JsonValue

Name	Type	Description	Required
JsonValue

Marketplace

Name	Type	Description	Required
marketplace_plugin_unique_identifier	string		Yes
version	string		No

MemberActionResponse

Name	Type	Description	Required
result	string, Default: success		No

MemberInvitePayload

Name	Type	Description	Required
email	string		Yes
role	string, Available values: "admin", "normal"	Enum: `"admin"`, `"normal"`	Yes

MemberInviteResponse

Name	Type	Required
email	string	Yes
invite_url	string	Yes
member_id	string	Yes
result	string, Default: success	No
role	string	Yes
tenant_id	string	Yes

MemberListQuery

Strict (extra='forbid').

Name	Type	Description	Required
limit	integer, Default: 20		No
page	integer, Default: 1		No

MemberListResponse

Name	Type	Required
data	[ MemberResponse ]	Yes
has_more	boolean	Yes
limit	integer	Yes
page	integer	Yes
total	integer	Yes

MemberResponse

Name	Type	Required
avatar	string	No
email	string	Yes
id	string	Yes
name	string	Yes
role	string	Yes
status	string	Yes

MemberRoleUpdatePayload

Name	Type	Description	Required
role	string, Available values: "admin", "normal"	Enum: `"admin"`, `"normal"`	Yes

MessageMetadata

Name	Type	Description	Required
retriever_resources	[ object ], Default:		No
usage	UsageInfo		No

OpenApiErrorCode

Name	Type	Description	Required
OpenApiErrorCode	string

Package

Name	Type	Description	Required
plugin_unique_identifier	string		Yes
version	string		No

PermittedExternalAppsListQuery

Strict (extra='forbid').

Name	Type	Required
limit	integer, Default: 20	No
mode	AppMode	No
name	string	No
page	integer, Default: 1	No

PermittedExternalAppsListResponse

Name	Type	Required
data	[ AppListRow ]	Yes
has_more	boolean	Yes
limit	integer	Yes
page	integer	Yes
total	integer	Yes

PluginDependency

Name	Type	Required
current_identifier	string	No
type	Type	Yes
value	Github Marketplace Package	Yes

RevokeResponse

Name	Type	Description	Required
status	string		Yes

ServerVersionResponse

Meta endpoint payload for GET /openapi/v1/_version — no auth required.

Name	Type	Description	Required
edition	string, Available values: "CLOUD", "SELF_HOSTED"	Enum: `"CLOUD"`, `"SELF_HOSTED"`	Yes
version	string		Yes

SessionListQuery

Pagination for GET /account/sessions. Strict (extra='forbid').

Name	Type	Description	Required
limit	integer, Default: 100		No
page	integer, Default: 1		No

SessionListResponse

Name	Type	Required
data	[ SessionRow ]	Yes
has_more	boolean	Yes
limit	integer	Yes
page	integer	Yes
total	integer	Yes

SessionRow

Name	Type	Required
client_id	string	Yes
created_at	string	No
device_label	string	Yes
expires_at	string	No
id	string	Yes
last_used_at	string	No
prefix	string	Yes

TagItem

Name	Type	Description	Required
name	string		Yes

TaskStopResponse

200 body for POST /apps//tasks/<task_id>/stop. The handler always returns {"result": "success"}, so result is required (no default) — the generated contract types it as a required 'success' rather than an optional field.

Name	Type	Description	Required
result	string		Yes

Type

Name	Type	Description	Required
Type	string

UsageInfo

Name	Type	Required
completion_tokens	integer	No
prompt_tokens	integer	No
total_tokens	integer	No

WorkflowRunData

Name	Type	Required
created_at	integer	No
elapsed_time	number	No
error	string	No
finished_at	integer	No
id	string	Yes
outputs	object	No
status	string	Yes
total_steps	integer	No
total_tokens	integer	No
workflow_id	string	Yes

WorkspaceDetailResponse

Name	Type	Required
created_at	string	No
current	boolean	Yes
id	string	Yes
name	string	Yes
role	string	Yes
status	string	Yes

WorkspaceListResponse

Name	Type	Description	Required
workspaces	[ WorkspaceSummaryResponse ]		Yes

WorkspacePayload

Name	Type	Required
id	string	Yes
name	string	Yes
role	string	Yes

WorkspaceSummaryResponse

Name	Type	Required
current	boolean	Yes
id	string	Yes
name	string	Yes
role	string	Yes
status	string	Yes

31 KiB Raw Blame History

OpenAPI

Version: 1.0

Available authorizations

Bearer (API Key Authentication)

openapi

[GET] /_health

Responses

[GET] /_version

Responses

[GET] /account

Responses

[GET] /account/sessions

Parameters

Responses

[DELETE] /account/sessions/self

Responses

[DELETE] /account/sessions/{session_id}

Parameters

Responses

[GET] /apps

Parameters

Responses

[GET] /apps/{app_id}/check-dependencies

Parameters

Responses

[GET] /apps/{app_id}/describe

Parameters

Responses

[GET] /apps/{app_id}/export

Parameters

Responses

[POST] /apps/{app_id}/files/upload

Parameters

Responses

[GET] /apps/{app_id}/form/human_input/{form_token}

Parameters

Responses

[POST] /apps/{app_id}/form/human_input/{form_token}

Parameters

Request Body

Responses

[POST] /apps/{app_id}/run

Parameters

Request Body

Responses

[GET] /apps/{app_id}/tasks/{task_id}/events

Parameters

Responses

[POST] /apps/{app_id}/tasks/{task_id}/stop

Parameters

Responses

[POST] /oauth/device/approve

Request Body

Responses

[POST] /oauth/device/code

Request Body

Responses

[POST] /oauth/device/deny

Request Body

Responses

[GET] /oauth/device/lookup

Parameters

Responses

[POST] /oauth/device/token

Request Body

Responses

[GET] /permitted-external-apps

Parameters

Responses

[GET] /workspaces

Responses

[GET] /workspaces/{workspace_id}

Parameters

Responses

[POST] /workspaces/{workspace_id}/apps/imports

Parameters

Request Body

Responses

[POST] /workspaces/{workspace_id}/apps/imports/{import_id}/confirm

31 KiB

Raw Blame History