General Discussion [Question] Clarification on the moderation request/response format for API extension

[DreamJokerMJ]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

Hi Dify team,

I'm trying to build a custom content moderation service and integrate it via the API Extension feature. I’ve checked the documentation, but I’m still not completely sure about the exact request and response contract for the moderation point.

Could you please clarify the following:

1. Request format
   What is the exact JSON structure Dify sends to my external endpoint when it acts as a moderation extension?
   I’ve seen field names like point, params, app_id, content, user, and type in some examples. Is the schema below correct?

   {
     "point": "moderation",
     "params": {
       "app_id": "string",
       "content": "string",
       "user": "string (optional)",
       "type": "input" | "output"
     }
   }

2. Response format
   What fields should my endpoint return so that Dify correctly interprets the result?
   I understand flagged (boolean) and preset_response (string) are the core fields. But:

   • Is there an action field? If yes, is "block" the only supported value?
   • Can I return additional fields (e.g. a sanitized version of the content) that Dify will use to replace the original input/output?
   • What exactly happens when flagged is true vs false? Will the pipeline immediately stop and return preset_response to the user, or can I also choose to “pass with warning”?

3. Error handling
   If my moderation service is down or returns a non-200 status, does Dify treat that as flagged: true by default?

Having the precise specification will help me build a reliable integration. Thank you very much!

[DreamJokerMJ]

@dosu
Do you know the description of the moderation request/response format for API extensions.

[dosubot[bot]]

Hi @DreamJokerMJ! Here's a full breakdown of the moderation API Extension contract based on the Dify source code:

---

1. Request Format

Dify sends a POST request with Content-Type: application/json and an Authorization: Bearer {api_key} header [1]. Timeouts are 5s (connect) and 60s (read) [2].

The JSON body uses this envelope [3]:

{
  "point": "<extension_point>",
  "params": { ... }
}

Extension points [4]:

• "app.moderation.input" — for input moderation
• "app.moderation.output" — for output moderation

Input params [5]:

{
  "app_id": "string",
  "inputs": { "var1": "value1" },
  "query": "user's query text"
}

Output params [6]:

{
  "app_id": "string",
  "text": "LLM-generated output text"
}

Note: The schema in your question (content, user, type) doesn't match the actual implementation. The real fields are inputs/query for input and text for output.

---

2. Response Format

Your endpoint must return HTTP 200 with valid JSON [7].

For input moderation [8]:

{
  "flagged": false,
  "action": "direct_output",
  "preset_response": "",
  "inputs": {},
  "query": ""
}

For output moderation [9]:

{
  "flagged": false,
  "action": "direct_output",
  "preset_response": "",
  "text": ""
}

The action field supports two values:

• "direct_output" — blocks the content entirely; preset_response is returned to the user
• "overridden" — allows the request to proceed with sanitized content (you supply replacement inputs/query or text)

So yes, you can return a sanitized version of the content. Use action: "overridden" and provide the modified fields.

---

3. Flagged Behavior

Scenario	Result
flagged: false	Content passes through unchanged
flagged: true + action: "direct_output"	Pipeline stops, preset_response is returned to the user [10]
flagged: true + action: "overridden"	Processing continues with your sanitized content replacing the original [11]

There is no "pass with warning" mode — it's either block or replace.

---

4. Error Handling

This is where input and output moderation diverge significantly:

Error Scenario	Input Moderation	Output Moderation
Non-200 status	Request FAILS with error	Content passes through unmoderated [12]
Timeout	Request FAILS	Content passes through
Network error	Request FAILS	Content passes through
Invalid JSON response	Request FAILS	Content passes through

Input moderation has no graceful fallback — if your service is down, the user's request will fail entirely (not treated as flagged: true, just an error) [13].

Output moderation fails open — errors are logged and the original LLM output is shown unmodified [12].

---

Given this asymmetry, I'd recommend making your moderation service highly available and fast, especially for input moderation, since any downtime will block all user requests.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.