Custom Endpoints

• moderation Sensitive content moderation
• external_data_tool External data tools

​

API Specification

POST {Your-API-Endpoint}

​

Header

​

Request Body

{
    "point":  string, //  Extension point, different modules may contain multiple extension points
    "params": {
        ...  // Parameters passed to each module extension point
    }
}

​

API Response

{
    ...  // Content returned by the API, see the specification design of different modules for different extension point returns
}

​

Validation

​

Header

Content-Type: application/json
Authorization: Bearer {api_key}

​

Request Body

{
    "point": "ping"
}

​

Expected API Response

{
    "result": "pong"
}

​

Example

​

API Example

POST https://fake-domain.com/api/dify/receive

Content-Type: application/json
Authorization: Bearer 123456

{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "How's the weather today?"
    }
}

{
    "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
}

​

Code Example

1. Install dependencies
   pip install fastapi[all] uvicorn
   
2. Write code according to the interface specification
   from fastapi import FastAPI, Body, HTTPException, Header
   from pydantic import BaseModel
   
   app = FastAPI()
   
   
   class InputData(BaseModel):
       point: str
       params: dict = {}
   
   
   @app.post("/api/dify/receive")
   async def dify_receive(data: InputData = Body(...), authorization: str = Header(None)):
       """
       Receive API query data from Dify.
       """
       expected_api_key = "123456"  # TODO Your API key of this API
       auth_scheme, _, api_key = authorization.partition(' ')
   
       if auth_scheme.lower() != "bearer" or api_key != expected_api_key:
           raise HTTPException(status_code=401, detail="Unauthorized")
   
       point = data.point
   
       # for debug
       print(f"point: {point}")
   
       if point == "ping":
           return {
               "result": "pong"
           }
       if point == "app.external_data_tool.query":
           return handle_app_external_data_tool_query(params=data.params)
       # elif point == "{point name}":
           # TODO other point implementation here
   
       raise HTTPException(status_code=400, detail="Not implemented")
   
   
   def handle_app_external_data_tool_query(params: dict):
       app_id = params.get("app_id")
       tool_variable = params.get("tool_variable")
       inputs = params.get("inputs")
       query = params.get("query")
   
       # for debug
       print(f"app_id: {app_id}")
       print(f"tool_variable: {tool_variable}")
       print(f"inputs: {inputs}")
       print(f"query: {query}")
   
       # TODO your external data tool query implementation here, 
       #  return must be a dict with key "result", and the value is the query result
       if inputs.get("location") == "London":
           return {
               "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind "
                         "Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
           }
       else:
           return {"result": "Unknown city"}
   
3. Start the API service. The default port is 8000, the complete API address is: http://127.0.0.1:8000/api/dify/receive, and the configured API Key is 123456.
   uvicorn main:app --reload --host 0.0.0.0
   
4. Configure this API in Dify.
5. Select this custom endpoint in the App.

{
    "point": "app.external_data_tool.query",
    "params": {
        "app_id": "61248ab4-1125-45be-ae32-0ce91334d021",
        "tool_variable": "weather_retrieve",
        "inputs": {
            "location": "London"
        },
        "query": "How's the weather today?"
    }
}

{
    "result": "City: London\nTemperature: 10°C\nRealFeel®: 8°C\nAir Quality: Poor\nWind Direction: ENE\nWind Speed: 8 km/h\nWind Gusts: 14 km/h\nPrecipitation: Light rain"
}

​

Local Debugging

1. Go to https://ngrok.com, register and download the Ngrok file.
   
2. After downloading, go to the download directory, extract the archive according to the instructions below, and execute the initialization script in the instructions.
   unzip /path/to/ngrok.zip
   ./ngrok config add-authtoken your-token
   
3. Check the port of your local API service:
   
   And run the following command to start:
   ./ngrok http port-number
   
   A successful startup example looks like this:
   
4. Find the Forwarding address, as shown above: https://177e-159-223-41-52.ngrok-free.app (this is an example domain, please replace with your own), which is the public domain.

​

Deploy Custom Endpoints Using Cloudflare Workers