openapi: 3.1.0
info:
  title: Dify API
  description: >-
    Dify is an open-source platform for building AI applications and agentic
    workflows. This API provides access to chat messages, completion
    messages, workflow execution, conversations, knowledge bases (datasets)
    and file uploads.
  version: "1.0"
servers:
  - url: https://api.dify.ai/v1
    description: Dify Cloud API
security:
  - bearerAuth: []
tags:
  - name: Chat
  - name: Completion
  - name: Workflows
  - name: Conversations
  - name: Datasets
  - name: Files
paths:
  /chat-messages:
    post:
      tags: [Chat]
      summary: Send a chat message
      operationId: sendChatMessage
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputs, query, user]
              properties:
                inputs:
                  type: object
                query:
                  type: string
                response_mode:
                  type: string
                  enum: [streaming, blocking]
                conversation_id:
                  type: string
                user:
                  type: string
                files:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Chat response
  /chat-messages/{task_id}/stop:
    post:
      tags: [Chat]
      summary: Stop a generating chat message
      operationId: stopChatMessage
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Stopped
  /completion-messages:
    post:
      tags: [Completion]
      summary: Send a completion request
      operationId: sendCompletion
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputs, user]
              properties:
                inputs:
                  type: object
                response_mode:
                  type: string
                  enum: [streaming, blocking]
                user:
                  type: string
      responses:
        '200':
          description: Completion response
  /completion-messages/{task_id}/stop:
    post:
      tags: [Completion]
      summary: Stop completion generation
      operationId: stopCompletion
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Stopped
  /workflows/run:
    post:
      tags: [Workflows]
      summary: Execute a workflow
      operationId: runWorkflow
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [inputs, user]
              properties:
                inputs:
                  type: object
                response_mode:
                  type: string
                  enum: [streaming, blocking]
                user:
                  type: string
      responses:
        '200':
          description: Workflow result
  /workflows/{task_id}/stop:
    post:
      tags: [Workflows]
      summary: Stop a running workflow
      operationId: stopWorkflow
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Stopped
  /workflows/run/{workflow_run_id}:
    get:
      tags: [Workflows]
      summary: Get a workflow run detail
      operationId: getWorkflowRun
      parameters:
        - name: workflow_run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workflow run details
  /conversations:
    get:
      tags: [Conversations]
      summary: List conversations
      operationId: listConversations
      parameters:
        - name: user
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Conversations
  /conversations/{conversation_id}:
    delete:
      tags: [Conversations]
      summary: Delete a conversation
      operationId: deleteConversation
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
  /conversations/{conversation_id}/name:
    post:
      tags: [Conversations]
      summary: Rename a conversation
      operationId: renameConversation
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Renamed
  /datasets:
    get:
      tags: [Datasets]
      summary: List knowledge bases / datasets
      operationId: listDatasets
      responses:
        '200':
          description: Datasets
  /datasets/{dataset_id}/retrieve:
    post:
      tags: [Datasets]
      summary: Test retrieval against a dataset
      operationId: datasetRetrieve
      parameters:
        - name: dataset_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                retrieval_model:
                  type: object
      responses:
        '200':
          description: Retrieval results
  /files/upload:
    post:
      tags: [Files]
      summary: Upload a file
      operationId: uploadFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, user]
              properties:
                file:
                  type: string
                  format: binary
                user:
                  type: string
      responses:
        '200':
          description: File uploaded
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer