Endpoint Plugin

Endpoints are HTTP interfaces exposed by a plugin for integration with external systems. This guide explains their structure using the Neko Cat project as an example.

Group Definition#

An Endpoint group is a collection of multiple Endpoints. When you create a new Endpoint in a Dify plugin, you may need to fill in the following configuration.

Besides the Endpoint Name, you can add form items by writing the group’s configuration. After saving, you can see the multiple interfaces the group contains, all sharing the same configuration.

Structure#

• settings (map[string] ProviderConfig): Endpoint configuration definition.
• endpoints (list[string], required): Points to the specific endpoint interface definitions.

settings:  api_key:    type: secret-input    required: true    label:      en_US: API key      zh_Hans: API key      ja_Jp: API key      pt_BR: API key    placeholder:      en_US: Please input your API key      zh_Hans: 请输入你的 API key      ja_Jp: あなたの API key を入れてください      pt_BR: Por favor, insira sua chave APIendpoints:  - endpoints/duck.yaml  - endpoints/neko.yaml

Interface Definition#

• path (string): Follows the Werkzeug interface standard.
• method (string): Interface method; supports only HEAD, GET, POST, PUT, DELETE, and OPTIONS.
• extra (object): Configuration information beyond the basic details.
  • python (object)
    • source (string): The source code that implements this interface.

path: "/duck/<app_id>"method: "GET"extra:  python:    source: "endpoints/duck.py"

Interface Implementation#

Implement a subclass of dify_plugin.Endpoint and its _invoke method.

• Input parameters
  • r (Request): The Request object from werkzeug.
  • values (Mapping): Path parameters parsed from the path.
  • settings (Mapping): Configuration information for this Endpoint.
• Return
  • A Response object from werkzeug; streaming responses are supported.
  • Returning a string directly is not supported.

Example code:

import jsonfrom typing import Mappingfrom werkzeug import Request, Responsefrom dify_plugin import Endpointclass Duck(Endpoint):    def _invoke(self, r: Request, values: Mapping, settings: Mapping) -> Response:        """        Invokes the endpoint with the given request.        """        app_id = values["app_id"]        def generator():            yield f"{app_id} <br>"        return Response(generator(), status=200, content_type="text/html")

Notes#

• Endpoints are only instantiated when the plugin is called; they are not long-running services.
• Pay attention to security when developing Endpoints, and avoid executing dangerous operations.
• Endpoints can handle webhook callbacks or provide interfaces for other systems to connect to.

If you’re new to plugin development, start with Getting Started with Plugin Development and the Developer Cheatsheet.

Related Resources#

• Basic Concepts of Plugin Development: The overall architecture of plugin development.
• Neko Cat Example: An example of extension plugin development.
• General Specifications Definition: Common structures like ProviderConfig.
• Develop a Slack Bot Plugin Example: Another plugin development example.
• Getting Started with Plugin Development: Develop a plugin from scratch.
• Reverse Invocation of Dify Services: Use the reverse invocation feature.