Dify x OpenAPI

English | 中文

Warning

This project will be discontinued due to Dify's official OpenAPI support. See https://docs.dify.ai/api-reference/chat/send-chat-message. You can copy the OpenAPI schema from there (I haven't checked the official documentation for a long time, and I just discovered this new tab a few minutes ago...) see the issue #31 to config and check swagger-ui of self-hosted dify version

Provides OpenAPI Schema for Dify API, which can be previewed using OpenAPI UI or used to generate clients with OpenAPI Generator

Swagger UI Preview online

Application APIs

• Chat Application - SwaggerUI(English)
• Advanced Chat Application - SwaggerUI(English)
• Text Generation Application - SwaggerUI(English)
• Workflow Application - SwaggerUI(English)

Knowledge Base APIs

• Knowledge Base - SwaggerUI(English)
• External Knowledge - SwaggerUI(English)

Note

There are some web UIs that support OpenAPI schema. You can take a look and use them in your way

• https://github.com/rapi-doc/RapiDoc

API List

Tip

This indicates that the API has passed at least one test case request. If you find any API errors, feel free to submit an issue or PR!

• Knowledge Base: OpenAPI Schema(中文) | OpenAPI Schema(English) | Official Documentation Source

  • POST /datasets - Create empty knowledge base
  • POST /datasets/{dataset_id} - Update knowledge base
  • GET /datasets/{dataset_id}/documents - Get document list
  • DELETE /datasets/{dataset_id}/documents/{document_id} - Delete document
  • POST /datasets/{dataset_id}/document/create-by-text - Create document by text
  • POST /datasets/{dataset_id}/document/create-by-file - Create document by file
  • PUT /datasets/{dataset_id}/documents/{document_id} - Update document
  • POST /datasets/{dataset_id}/documents/{document_id}/update-by-file - Update document by file
  • GET /datasets/{dataset_id}/documents/{document_id}/upload-file - Get upload file
  • GET /datasets/{dataset_id}/documents/{batch}/indexing-status - Get document embedding status
  • PATCH /datasets/{dataset_id}/documents/status/{action} - Batch update document status
  • GET /datasets/{dataset_id}/documents/{document_id}/segments - Query document segments
  • POST /datasets/{dataset_id}/documents/{document_id}/segments - Create document segment
  • DELETE /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} - Delete document segment
  • POST /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} - Update document segment
  • POST /datasets/{dataset_id}/metadata - Create metadata
  • GET /datasets/{dataset_id}/metadata - List dataset metadata
  • PATCH /datasets/{dataset_id}/metadata/{metadata_id} - Update metadata
  • DELETE /datasets/{dataset_id}/metadata/{metadata_id} - Delete metadata
  • POST /datasets/{dataset_id}/metadata/built-in/{action} - Enable/disable built-in metadata
  • POST /datasets/{dataset_id}/documents/metadata - Update document metadata
  • GET /datasets/{dataset_id}/documents/{document_id}/segments/{segment_id} - View document segment detail
  • POST /datasets/tags - Create knowledge base tag
  • GET /datasets/tags - Get knowledge base tags
  • PATCH /datasets/tags - Update knowledge base tag name
  • DELETE /datasets/tags - Delete knowledge base tag
  • POST /datasets/tags/binding - Bind dataset to tag
  • POST /datasets/tags/unbinding - Unbind dataset from tag
  • POST /datasets/{dataset_id}/tags - Query dataset bound tags
  • POST /datasets/{dataset_id}/retrieval - Retrieve with metadata filtering conditions

• Chat Application: OpenAPI Schema(中文) | OpenAPI Schema(English) | Official Documentation Source

  • POST /chat-messages - Send conversation message
  • POST /files/upload - Upload file
  • POST /messages/{message_id}/feedbacks - Message feedback
  • POST /conversations/{conversation_id}/name - Rename conversation
  • DELETE /conversations/{conversation_id} - Delete conversation
  • GET /messages - Get conversation history messages
  • GET /conversations/{conversation_id}/variables - Get conversation variables
  • GET /app/feedbacks - Get application feedbacks
  • GET /site - Get application WebApp settings
  • GET /info - Get application basic information
  • GET /parameters - Get application parameters

• Advanced Chat Application: OpenAPI Schema(中文) | OpenAPI Schema(English) | Official Documentation Source

  • POST /audio-to-text - Speech to text
  • POST /text-to-audio - Text to speech
  • GET /apps/annotations - Get annotation list
  • POST /apps/annotations - Create annotation
  • PUT /apps/annotations/{annotation_id} - Update annotation
  • DELETE /apps/annotations/{annotation_id} - Delete annotation
  • POST /apps/annotation-reply/{action} - Initialize annotation reply settings
  • GET /apps/annotation-reply/{action}/status/{job_id} - Check annotation reply settings status
  • GET /app/feedbacks - Get application feedbacks
  • GET /site - Get application WebApp settings
  • GET /conversations/{conversation_id}/variables - Get conversation variables
  • GET /info - Get application basic information
  • GET /parameters - Get application parameters

• Text Generation Application: OpenAPI Schema(中文) | OpenAPI Schema(English) | Official Documentation Source

  • POST /completion-messages - Send message

• Workflow Application: OpenAPI Schema(中文) | OpenAPI Schema(English) | Official Documentation Source

  • POST /workflows/run - Execute workflow
  • GET /workflows/run/{workflow_run_id} - Get workflow execution status
  • POST /workflows/tasks/{task_id}/stop - Stop response
  • GET /workflows/logs - Get workflow logs
  • GET /site - Get application WebApp settings

• External Knowledge: OpenAPI Schema(中文) | OpenAPI Schema(English) | Official Documentation Source

  • POST /retrieval - Retrieve knowledge content

Project Structure

.
├── schema/           # OpenAPI schema
├── src/             # Generated client code
├── tests/           # Test client code to verify schema/* correctness
└── configs/         # Code generator configuration

Contribution & Local Development

Install these tools:

• uv - Python package manager
• just - Alternative to Makefile
• ruff - Python code formatting and checking tool

See CONTRIBUTING.md for more inspiration

Development Process

Maintaining Unit Tests

1. Install dependencies:

uv venv && uv pip install -e ".[dev]"

2. Generate client code:

just gen-client

3. Preview API documentation:

just run-openapi-ui

4. Edit environment variables:

cp .env.example .env
# Fill in the relevant variables

5. Run tests:

just test

6. Submit PR

Maintaining Multilingual Support

1. Add a language overlay file, e.g., ./schema/overlays/app_chat.en.overlay.yaml
2. Run just apply-i18n-overlay-to-openapi-schema to generate the corresponding language schema (if it is a new language, please check if it is handled in justfile)
3. Run just run-openapi-ui to preview API documentation
4. Submit PR