dify/api/openapi/markdown/openapi-openapi.md

OpenAPI

User-scoped programmatic API (bearer auth)

Version: 1.0

Available authorizations

Bearer (HTTP, bearer)

Use the Service API key as a Bearer token in the Authorization header. Bearer format: API_KEY

---

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	Description	Required	Schema
limit	query		No	integer, Default: 20
mode	query	App types the app usage face (get app) lists and filters. A curated subset of :class:AppMode: the real, user-facing app categories. Excludes runtime-only mode tags that are not standalone apps (rag-pipeline is a knowledge Pipeline; channel is unused) and the roster-owned agent type (surfaced through the roster, not this list). Members reference AppMode.*.value so the subset relationship is type-checked: dropping a member from AppMode breaks this at import. This is the single source for the listable set — params, filters, and the generated CLI whitelist all derive from it.	No	string, Available values: "advanced-chat", "agent-chat", "chat", "completion", "workflow"
name	query		No	string
page	query		No	integer, Default: 1
workspace_id	query		Yes	string (uuid)

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}

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}/dependencies:check

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}/dsl

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 (uuid)
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 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}/human-input-forms/{form_token}

Parameters

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

Responses

Code	Description	Schema
200	Form definition	application/json: HumanInputFormDefinitionResponse

[POST] /apps/{app_id}/human-input-forms/{form_token}:submit

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

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

Parameters

Name	Located in	Description	Required	Schema
continue_on_pause	query	Whether to keep the event stream open on pause	No	boolean
include_state_snapshot	query	Whether to include workflow state snapshots	No	boolean
app_id	path		Yes	string
task_id	path		Yes	string

Responses

Code	Description	Schema
200	SSE event stream	application/json: EventStreamResponse

[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] /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)	application/json: EventStreamResponse
422	Validation 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	Schema
200	Device token	application/json: DeviceTokenResponse

[GET] /permitted-external-apps

Parameters

Name	Located in	Description	Required	Schema
limit	query		No	integer, Default: 20
mode	query	App types the app usage face (get app) lists and filters. A curated subset of :class:AppMode: the real, user-facing app categories. Excludes runtime-only mode tags that are not standalone apps (rag-pipeline is a knowledge Pipeline; channel is unused) and the roster-owned agent type (surfaced through the roster, not this list). Members reference AppMode.*.value so the subset relationship is type-checked: dropping a member from AppMode breaks this at import. This is the single source for the listable set — params, filters, and the generated CLI whitelist all derive from it.	No	string, Available values: "advanced-chat", "agent-chat", "chat", "completion", "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] /permitted-external-apps/{app_id}

Parameters

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

Responses

Code	Description	Schema
200	Permitted external app description	application/json: AppDescribeResponse
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}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs:cat

Read KnowledgeFS entry content (cat)

Reads a bounded text portion of one entry, equivalent to difyctl fs cat. Content follows stable source order. When next_page_token is present, reuse it with the same path and consistency_class. total is not returned because this response is a bounded content stream, not a collection. Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before request validation, and knowledge-space membership is revalidated for every call. A hidden or missing knowledge space or entry uses the same 404 response. These operations are read-only and do not emit mutation audit events.

Parameters

Name	Located in	Description	Required	Schema
knowledge_space_id	path	Stable Dify knowledge-space resource ID; treat it as opaque.	Yes	string
workspace_id	path	Dify workspace ID that owns the knowledge space.	Yes	string
consistency_class	query	Optional KnowledgeFS read-consistency policy.	No	string, Available values: "cache-consistent", "eventual-preview", "path-consistent", "snapshot-consistent"
page_size	query	Maximum source segments to read (1-100); ignored when the selected entry has one bounded content value.	No	integer, Default: 100
page_token	query	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No	string
path	query	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes	string

Responses

Code	Description	Schema
200	Knowledge-space entry content	application/json: KnowledgeFSEntryReadContentResponse
400	Invalid KnowledgeFS request	application/json: ErrorBody
401	Missing or invalid OAuth account bearer	application/json: ErrorBody
403	Caller lacks workspace or knowledge-space read access	application/json: ErrorBody
404	Knowledge space or entry is missing or hidden	application/json: ErrorBody
409	Requested consistency conflicts with current state	application/json: ErrorBody
413	Request exceeds a KnowledgeFS operational bound	application/json: ErrorBody
422	Request validation failed or the request was rejected	application/json: ErrorBody
503	KnowledgeFS is temporarily unavailable	application/json: ErrorBody
default	Error	application/json: ErrorBody

[POST] /workspaces/{workspace_id}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs:diff

Compare two KnowledgeFS entries (diff)

Performs a side-effect-free comparison, equivalent to difyctl fs diff. POST is used because this is a structured query and an optional semantic summary can consume model quota. Automatic retries are not safe when include_semantic_summary=true because each retry can consume quota again. Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before request validation, and knowledge-space membership is revalidated for every call. A hidden or missing knowledge space or entry uses the same 404 response. These operations are read-only and do not emit mutation audit events.

Parameters

Name	Located in	Description	Required	Schema
knowledge_space_id	path	Stable Dify knowledge-space resource ID; treat it as opaque.	Yes	string
workspace_id	path	Dify workspace ID that owns the knowledge space.	Yes	string

Request Body

Required	Schema
Yes	application/json: KnowledgeFSEntryComparePayload

Responses

Code	Description	Schema
200	Knowledge-space entry comparison	application/json: KnowledgeFSEntryComparisonResponse
400	Invalid KnowledgeFS request	application/json: ErrorBody
401	Missing or invalid OAuth account bearer	application/json: ErrorBody
403	Caller lacks workspace or knowledge-space read access	application/json: ErrorBody
404	Knowledge space or entry is missing or hidden	application/json: ErrorBody
409	Requested consistency conflicts with current state	application/json: ErrorBody
413	Request exceeds a KnowledgeFS operational bound	application/json: ErrorBody
422	Request validation failed or the request was rejected	application/json: ErrorBody
503	KnowledgeFS is temporarily unavailable	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs:find

Find KnowledgeFS entries (find)

Searches entries beneath path by name, resource type, or an exact metadata key/value pair, equivalent to difyctl fs find. Results use the canonical, stable KnowledgeFS traversal order. The opaque next_page_token captures that order; reuse it with unchanged filters and consistency_class. total is intentionally omitted because tenant-aware visibility scans are bounded and an exact count can require an unbounded scan. Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before request validation, and knowledge-space membership is revalidated for every call. A hidden or missing knowledge space or entry uses the same 404 response. These operations are read-only and do not emit mutation audit events.

Parameters

Name	Located in	Description	Required	Schema
knowledge_space_id	path	Stable Dify knowledge-space resource ID; treat it as opaque.	Yes	string
workspace_id	path	Dify workspace ID that owns the knowledge space.	Yes	string
consistency_class	query	Optional KnowledgeFS read-consistency policy.	No	string, Available values: "cache-consistent", "eventual-preview", "path-consistent", "snapshot-consistent"
metadata_key	query	Exact metadata key; metadata_value must be supplied with it.	No	string
metadata_value	query	Exact metadata value; metadata_key must be supplied with it.	No	string
name_contains	query		No	string
page_size	query	Maximum number of results to return (1-100).	No	integer, Default: 20
page_token	query	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No	string
path	query	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes	string
resource_type	query		No	string, Available values: "artifact", "document", "evidence", "node", "source", "workspace"

Responses

Code	Description	Schema
200	Knowledge-space entry search results	application/json: KnowledgeFSEntryListResponse
400	Invalid KnowledgeFS request	application/json: ErrorBody
401	Missing or invalid OAuth account bearer	application/json: ErrorBody
403	Caller lacks workspace or knowledge-space read access	application/json: ErrorBody
404	Knowledge space or entry is missing or hidden	application/json: ErrorBody
409	Requested consistency conflicts with current state	application/json: ErrorBody
413	Request exceeds a KnowledgeFS operational bound	application/json: ErrorBody
422	Request validation failed or the request was rejected	application/json: ErrorBody
503	KnowledgeFS is temporarily unavailable	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs:grep

Search KnowledgeFS content (grep)

Searches readable content beneath path, equivalent to difyctl fs grep. Matches follow canonical entry traversal order and source-offset order within each entry. Results use the canonical, stable KnowledgeFS traversal order. The opaque next_page_token captures that order; reuse it with unchanged filters and consistency_class. total is intentionally omitted because tenant-aware visibility scans are bounded and an exact count can require an unbounded scan. Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before request validation, and knowledge-space membership is revalidated for every call. A hidden or missing knowledge space or entry uses the same 404 response. These operations are read-only and do not emit mutation audit events.

Parameters

Name	Located in	Description	Required	Schema
knowledge_space_id	path	Stable Dify knowledge-space resource ID; treat it as opaque.	Yes	string
workspace_id	path	Dify workspace ID that owns the knowledge space.	Yes	string
consistency_class	query	Optional KnowledgeFS read-consistency policy.	No	string, Available values: "cache-consistent", "eventual-preview", "path-consistent", "snapshot-consistent"
page_size	query	Maximum number of results to return (1-100).	No	integer, Default: 20
page_token	query	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No	string
path	query	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes	string
text	query	Text to find in readable entry content.	Yes	string
timeout_ms	query	Optional search time budget in milliseconds (1-10000).	No	integer

Responses

Code	Description	Schema
200	Knowledge-space content matches	application/json: KnowledgeFSEntryContentSearchResponse
400	Invalid KnowledgeFS request	application/json: ErrorBody
401	Missing or invalid OAuth account bearer	application/json: ErrorBody
403	Caller lacks workspace or knowledge-space read access	application/json: ErrorBody
404	Knowledge space or entry is missing or hidden	application/json: ErrorBody
409	Requested consistency conflicts with current state	application/json: ErrorBody
413	Request exceeds a KnowledgeFS operational bound	application/json: ErrorBody
422	Request validation failed or the request was rejected	application/json: ErrorBody
503	KnowledgeFS is temporarily unavailable	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs:ls

List a KnowledgeFS directory (ls)

Lists direct child entries under path, equivalent to difyctl fs ls. Results use the canonical, stable KnowledgeFS traversal order. The opaque next_page_token captures that order; reuse it with unchanged filters and consistency_class. total is intentionally omitted because tenant-aware visibility scans are bounded and an exact count can require an unbounded scan. Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before request validation, and knowledge-space membership is revalidated for every call. A hidden or missing knowledge space or entry uses the same 404 response. These operations are read-only and do not emit mutation audit events.

Parameters

Name	Located in	Description	Required	Schema
knowledge_space_id	path	Stable Dify knowledge-space resource ID; treat it as opaque.	Yes	string
workspace_id	path	Dify workspace ID that owns the knowledge space.	Yes	string
consistency_class	query	Optional KnowledgeFS read-consistency policy.	No	string, Available values: "cache-consistent", "eventual-preview", "path-consistent", "snapshot-consistent"
page_size	query	Maximum number of results to return (1-100).	No	integer, Default: 20
page_token	query	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No	string
path	query	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes	string

Responses

Code	Description	Schema
200	Knowledge-space entry page	application/json: KnowledgeFSEntryListResponse
400	Invalid KnowledgeFS request	application/json: ErrorBody
401	Missing or invalid OAuth account bearer	application/json: ErrorBody
403	Caller lacks workspace or knowledge-space read access	application/json: ErrorBody
404	Knowledge space or entry is missing or hidden	application/json: ErrorBody
409	Requested consistency conflicts with current state	application/json: ErrorBody
413	Request exceeds a KnowledgeFS operational bound	application/json: ErrorBody
422	Request validation failed or the request was rejected	application/json: ErrorBody
503	KnowledgeFS is temporarily unavailable	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs:stat

Inspect a KnowledgeFS entry (stat)

Returns stable metadata for one entry selected by canonical virtual path without reading content, equivalent to difyctl fs stat. Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before request validation, and knowledge-space membership is revalidated for every call. A hidden or missing knowledge space or entry uses the same 404 response. These operations are read-only and do not emit mutation audit events.

Parameters

Name	Located in	Description	Required	Schema
knowledge_space_id	path	Stable Dify knowledge-space resource ID; treat it as opaque.	Yes	string
workspace_id	path	Dify workspace ID that owns the knowledge space.	Yes	string
consistency_class	query	Optional KnowledgeFS read-consistency policy.	No	string, Available values: "cache-consistent", "eventual-preview", "path-consistent", "snapshot-consistent"
path	query	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes	string

Responses

Code	Description	Schema
200	Knowledge-space entry metadata	application/json: KnowledgeFSEntryMetadataResponse
400	Invalid KnowledgeFS request	application/json: ErrorBody
401	Missing or invalid OAuth account bearer	application/json: ErrorBody
403	Caller lacks workspace or knowledge-space read access	application/json: ErrorBody
404	Knowledge space or entry is missing or hidden	application/json: ErrorBody
409	Requested consistency conflicts with current state	application/json: ErrorBody
413	Request exceeds a KnowledgeFS operational bound	application/json: ErrorBody
422	Request validation failed or the request was rejected	application/json: ErrorBody
503	KnowledgeFS is temporarily unavailable	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs:tree

Traverse a KnowledgeFS directory (tree)

Returns a depth- and page-size-bounded tree rooted at path, equivalent to difyctl fs tree. Results use the canonical, stable KnowledgeFS traversal order. The opaque next_page_token captures that order; reuse it with unchanged filters and consistency_class. total is intentionally omitted because tenant-aware visibility scans are bounded and an exact count can require an unbounded scan. Requires an OAuth account bearer with WORKSPACE_READ. Authentication and workspace scope are checked before request validation, and knowledge-space membership is revalidated for every call. A hidden or missing knowledge space or entry uses the same 404 response. These operations are read-only and do not emit mutation audit events.

Parameters

Name	Located in	Description	Required	Schema
knowledge_space_id	path	Stable Dify knowledge-space resource ID; treat it as opaque.	Yes	string
workspace_id	path	Dify workspace ID that owns the knowledge space.	Yes	string
consistency_class	query	Optional KnowledgeFS read-consistency policy.	No	string, Available values: "cache-consistent", "eventual-preview", "path-consistent", "snapshot-consistent"
depth	query	Maximum tree depth (1-8).	No	integer
page_size	query	Maximum number of results to return (1-100).	No	integer, Default: 20
page_token	query	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No	string
path	query	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes	string

Responses

Code	Description	Schema
200	Knowledge-space entry tree	application/json: KnowledgeFSEntryTreeResponse
400	Invalid KnowledgeFS request	application/json: ErrorBody
401	Missing or invalid OAuth account bearer	application/json: ErrorBody
403	Caller lacks workspace or knowledge-space read access	application/json: ErrorBody
404	Knowledge space or entry is missing or hidden	application/json: ErrorBody
409	Requested consistency conflicts with current state	application/json: ErrorBody
413	Request exceeds a KnowledgeFS operational bound	application/json: ErrorBody
422	Request validation failed or the request was rejected	application/json: ErrorBody
503	KnowledgeFS is temporarily unavailable	application/json: ErrorBody
default	Error	application/json: ErrorBody

[GET] /workspaces/{workspace_id}/members

Parameters

Name	Located in	Description	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

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

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	Description	Required
email	string		Yes
id	string		Yes
name	string		Yes

AccountResponse

Name	Type	Description	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	Description	Required
description	string		No
id	string		Yes
is_agent	boolean		No
mode	string		Yes
name	string		Yes
service_api_enabled	boolean		Yes
updated_at	string		No

AppDescribeQuery

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

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

Name	Type	Description	Required
fields	string		No

AppDescribeResponse

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

AppDslExportQuery

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

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

AppInfo

Name	Type	Description	Required
description	string		No
id	string		Yes
mode	string		Yes
name	string		Yes

AppListQuery

mode is a closed enum of listable app types.

Name	Type	Description	Required
limit	integer, Default: 20		No
mode	SupportedAppType		No
name	string		No
page	integer, Default: 1		No
workspace_id	string (uuid)		Yes

AppListResponse

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

AppListRow

Name	Type	Description	Required
description	string		No
id	string		Yes
mode	AppMode		Yes
name	string		Yes
updated_at	string		No
workspace_id	string		No
workspace_name	string		No

AppMode

Name	Type	Description	Required
AppMode	string

AppRunRequest

Name	Type	Description	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

DeploymentEdition

Enum representing the deployment edition of the platform.

Name	Type	Description	Required
DeploymentEdition	string	Enum representing the deployment edition of the platform.

DeviceCodeRequest

Name	Type	Description	Required
client_id	string		Yes
device_label	string		Yes

DeviceCodeResponse

Name	Type	Description	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	Description	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

DeviceTokenResponse

Name	Type	Description	Required
account	AccountPayload		No
default_workspace_id	string		No
expires_at	string		Yes
subject_email	string		No
subject_issuer	string		No
subject_type	string, Available values: "account", "external_sso"	Enum: "account", "external_sso"	Yes
token	string		Yes
token_id	string		Yes
workspaces	[ WorkspacePayload ], Default:		No

DslImportWarning

Portable DSL reference that could not be restored in the target workspace.

Name	Type	Description	Required
code	string		Yes
details	object		No
message	string		Yes
path	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	Description	Required
code	string		Yes
details	[ ErrorDetail ]		No
hint	string		No
message	string		Yes
status	integer		Yes

ErrorDetail

Name	Type	Description	Required
loc	[ string integer ]		No
msg	string		Yes
type	string		Yes

EventStreamResponse

Name	Type	Description	Required
EventStreamResponse	string

FileResponse

Name	Type	Description	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//human-input-forms/:submit. 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	Description	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

HumanInputFormDefinitionResponse

Name	Type	Description	Required
expiration_time	integer		No
form_content	string		Yes
inputs	[ object ]		No
resolved_default_values	object		Yes
user_actions	[ object ]		No

HumanInputFormSubmitPayload

Name	Type	Description	Required
action	string	ID of the action button the recipient selected. Must match one of the id values from the form's user_actions list.	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	Description	Required
app_id	string		No
app_mode	string		No
current_dsl_version	string, Default: 0.7.0		No
error	string		No
id	string		Yes
imported_dsl_version	string		No
permission_keys	[ string ]		No
status	ImportStatus		Yes
warnings	[ DslImportWarning ]		No

ImportStatus

Name	Type	Description	Required
ImportStatus	string

JsonValue

Name	Type	Description	Required
JsonValue

KnowledgeFSConsistencyClass

Name	Type	Description	Required
KnowledgeFSConsistencyClass	string

KnowledgeFSEntryComparePayload

Name	Type	Description	Required
consistency_class	KnowledgeFSConsistencyClass	Optional KnowledgeFS read-consistency policy.	No
include_semantic_summary	boolean	Whether to generate a bounded semantic change summary. This can consume model quota.	No
mode	string	Comparison granularity.	No
new_path	string	Canonical path of the entry to compare.	Yes
old_path	string	Canonical path of the baseline entry.	Yes

KnowledgeFSEntryComparisonOperationResponse

Name	Type	Description	Required
kind	string, Available values: "delete", "equal", "insert"	Enum: "delete", "equal", "insert"	Yes
new_end	integer		No
new_start	integer		No
old_end	integer		No
old_start	integer		No
text	string		Yes

KnowledgeFSEntryComparisonResponse

Name	Type	Description	Required
mode	string, Available values: "line", "word"	Enum: "line", "word"	Yes
new_path	string		Yes
old_path	string		Yes
operations	[ KnowledgeFSEntryComparisonOperationResponse ]		Yes
semantic	KnowledgeFSEntrySemanticSummaryResponse		No
stats	KnowledgeFSEntryComparisonStatsResponse		Yes

KnowledgeFSEntryComparisonStatsResponse

Name	Type	Description	Required
delete	integer		Yes
equal	integer		Yes
insert	integer		Yes

KnowledgeFSEntryContentMatchResponse

Name	Type	Description	Required
end_offset	integer		Yes
kind	string, Available values: "node", "segment"	Enum: "node", "segment"	Yes
metadata	object		Yes
node_id	string		No
path	string		Yes
segment_id	string		No
snippet	string		Yes
start_offset	integer		Yes

KnowledgeFSEntryContentSearchQuery

Name	Type	Description	Required
consistency_class	KnowledgeFSConsistencyClass	Optional KnowledgeFS read-consistency policy.	No
page_size	integer, Default: 20	Maximum number of results to return (1-100).	No
page_token	string	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No
path	string	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes
text	string	Text to find in readable entry content.	Yes
timeout_ms	integer	Optional search time budget in milliseconds (1-10000).	No

KnowledgeFSEntryContentSearchResponse

Name	Type	Description	Required
data	[ KnowledgeFSEntryContentMatchResponse ]		Yes
has_more	boolean		Yes
next_page_token	string	Opaque continuation token for the next page; null when no continuation is available.	No
path	string		Yes
truncated	boolean	Whether operational bounds made the result incomplete, even when no continuation is available.	Yes

KnowledgeFSEntryInspectQuery

Name	Type	Description	Required
consistency_class	KnowledgeFSConsistencyClass	Optional KnowledgeFS read-consistency policy.	No
path	string	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes

KnowledgeFSEntryListQuery

List direct children in stable KnowledgeFS traversal order.

Name	Type	Description	Required
consistency_class	KnowledgeFSConsistencyClass	Optional KnowledgeFS read-consistency policy.	No
page_size	integer, Default: 20	Maximum number of results to return (1-100).	No
page_token	string	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No
path	string	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes

KnowledgeFSEntryListResponse

Name	Type	Description	Required
consistency_class	string	Open response value. Clients must tolerate unknown future values and fall back to generic display behavior.	No
data	[ KnowledgeFSEntryResponse ]		Yes
has_more	boolean		Yes
next_page_token	string	Opaque continuation token for the next page; null when no continuation is available.	No
path	string		Yes
preview	boolean		No
truncated	boolean	Whether operational bounds made the result incomplete, even when no continuation is available.	Yes

KnowledgeFSEntryMetadataResponse

Name	Type	Description	Required
consistency_class	string	Open response value. Clients must tolerate unknown future values and fall back to generic display behavior.	No
content_type	string		No
metadata	object		Yes
parser_status	string	Open response value. Clients must tolerate unknown future values and fall back to generic display behavior.	No
path	string		Yes
preview	boolean		No
resource_type	string	Open response value. Clients must tolerate unknown future values and fall back to generic display behavior.	Yes
sha256	string		No
size_bytes	integer		No
target_id	string		Yes
version	integer		No

KnowledgeFSEntryReadContentQuery

Name	Type	Description	Required
consistency_class	KnowledgeFSConsistencyClass	Optional KnowledgeFS read-consistency policy.	No
page_size	integer, Default: 100	Maximum source segments to read (1-100); ignored when the selected entry has one bounded content value.	No
page_token	string	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No
path	string	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes

KnowledgeFSEntryReadContentResponse

Name	Type	Description	Required
content_type	string		Yes
has_more	boolean		Yes
next_page_token	string	Opaque continuation token for the next page; null when no continuation is available.	No
path	string		Yes
text	string		Yes
truncated	boolean	Whether operational bounds made the content incomplete, even when no continuation is available.	Yes

KnowledgeFSEntryResponse

Name	Type	Description	Required
kind	string, Available values: "directory", "resource"	Enum: "directory", "resource"	Yes
metadata	object		Yes
name	string		Yes
path	string		Yes
resource_type	string	Open response value. Clients must tolerate unknown future values and fall back to generic display behavior.	No
target_id	string		No
version	integer		No

KnowledgeFSEntrySearchQuery

Name	Type	Description	Required
consistency_class	KnowledgeFSConsistencyClass	Optional KnowledgeFS read-consistency policy.	No
metadata_key	string	Exact metadata key; metadata_value must be supplied with it.	No
metadata_value	string	Exact metadata value; metadata_key must be supplied with it.	No
name_contains	string		No
page_size	integer, Default: 20	Maximum number of results to return (1-100).	No
page_token	string	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No
path	string	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes
resource_type	KnowledgeFSResourceType		No

KnowledgeFSEntrySemanticChangeResponse

Name	Type	Description	Required
category	string		Yes
evidence	[ string ]		Yes
summary	string		Yes

KnowledgeFSEntrySemanticSummaryResponse

Name	Type	Description	Required
changes	[ KnowledgeFSEntrySemanticChangeResponse ]		Yes
metadata	object		Yes
model	string		No
summary	string		Yes

KnowledgeFSEntryTreeNodeResponse

Name	Type	Description	Required
children	[ KnowledgeFSEntryTreeNodeResponse ]		No
kind	string, Available values: "directory", "resource"	Enum: "directory", "resource"	Yes
metadata	object		Yes
name	string		Yes
path	string		Yes
resource_type	string	Open response value. Clients must tolerate unknown future values and fall back to generic display behavior.	No
target_id	string		No
version	integer		No

KnowledgeFSEntryTreeQuery

Name	Type	Description	Required
consistency_class	KnowledgeFSConsistencyClass	Optional KnowledgeFS read-consistency policy.	No
depth	integer	Maximum tree depth (1-8).	No
page_size	integer, Default: 20	Maximum number of results to return (1-100).	No
page_token	string	Opaque continuation token returned as next_page_token. Repeat the same query without inspecting the token.	No
path	string	Canonical KnowledgeFS virtual path under /sources, /knowledge, /evidence, or /workspaces.	Yes

KnowledgeFSEntryTreeResponse

Name	Type	Description	Required
consistency_class	string	Open response value. Clients must tolerate unknown future values and fall back to generic display behavior.	No
has_more	boolean		Yes
next_page_token	string	Opaque continuation token for the next page; null when no continuation is available.	No
path	string		Yes
preview	boolean		No
root	KnowledgeFSEntryTreeNodeResponse		Yes
truncated	boolean	Whether operational bounds made the result incomplete, even when no continuation is available.	Yes

KnowledgeFSResourceType

Name	Type	Description	Required
KnowledgeFSResourceType	string

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	Description	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	Description	Required
data	[ MemberResponse ]		Yes
has_more	boolean		Yes
limit	integer		Yes
page	integer		Yes
total	integer		Yes

MemberResponse

Name	Type	Description	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	Description	Required
limit	integer, Default: 20		No
mode	SupportedAppType		No
name	string		No
page	integer, Default: 1		No

PermittedExternalAppsListResponse

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

PluginDependency

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

PluginDependencyType

Name	Type	Description	Required
PluginDependencyType	string

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	DeploymentEdition		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	Description	Required
data	[ SessionRow ]		Yes
has_more	boolean		Yes
limit	integer		Yes
page	integer		Yes
total	integer		Yes

SessionRow

Name	Type	Description	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

SimpleResultResponse

Name	Type	Description	Required
result	string		Yes

SupportedAppType

App types the app usage face (get app) lists and filters.

A curated subset of :class:AppMode: the real, user-facing app categories. Excludes runtime-only mode tags that are not standalone apps (rag-pipeline is a knowledge Pipeline; channel is unused) and the roster-owned agent type (surfaced through the roster, not this list).

Members reference AppMode.*.value so the subset relationship is type-checked: dropping a member from AppMode breaks this at import. This is the single source for the listable set — params, filters, and the generated CLI whitelist all derive from it.

Name	Type	Description	Required
SupportedAppType	string	App types the app usage face (get app) lists and filters. A curated subset of :class:AppMode: the real, user-facing app categories. Excludes runtime-only mode tags that are not standalone apps (rag-pipeline is a knowledge Pipeline; channel is unused) and the roster-owned agent type (surfaced through the roster, not this list). Members reference AppMode.*.value so the subset relationship is type-checked: dropping a member from AppMode breaks this at import. This is the single source for the listable set — params, filters, and the generated CLI whitelist all derive from it.

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

UsageInfo

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

WorkflowRunData

Name	Type	Description	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	Description	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	Description	Required
id	string		Yes
name	string		Yes
role	string		Yes

WorkspaceSummaryResponse

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