Chatbot - Dify Docs

Chat applications support session persistence, allowing previous chat history to be used as context for responses. This can be applicable for chatbot, customer service AI, etc.

Base URL

https://api.dify.ai/v1

Authentication

The Service API uses API-Key authentication.

For all API requests, include your API Key in the Authorization HTTP Header, as shown below:

Authorization: Bearer {YOUR_API_KEY}

POST /chat-messages Send Chat Message

Send a request to the chat application.

Request Body

query (string): User Input/Question content.
inputs (object, optional, default {}): Allows the entry of various variable values defined by the App. The inputs parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable.
response_mode (string): The mode of response return, supporting:
- streaming: Streaming mode (recommended), implements a typewriter-like output through SSE (Server-Sent Events).
- blocking: Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long). Due to Cloudflare restrictions, the request will be interrupted without a return after 100 seconds. Note: blocking mode is not supported in Agent Assistant mode.
user (string): User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.
conversation_id (string, optional): Conversation ID. To continue the conversation based on previous chat records, it is necessary to pass the previous message’s conversation_id.
files (array[object], optional): File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability.
- type (string): Supported type: image (currently only supports image type).
- transfer_method (string): Transfer method, remote_url for image URL / local_file for file upload.
- url (string, conditional): Image URL (when the transfer method is remote_url).
- upload_file_id (string, conditional): Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is local_file).
auto_generate_name (bool, optional, default true): Auto-generate title. If set to false, can achieve async title generation by calling the conversation rename API and setting auto_generate to true.

Response

When response_mode is blocking, returns a ChatCompletionResponse object. When response_mode is streaming, returns a ChunkChatCompletionResponse stream.

ChatCompletionResponse

Returns the complete App result, Content-Type is application/json.

event (string): Event type, fixed as message.
task_id (string): Task ID, used for request tracking and the Stop Generate API.
id (string): Unique ID.
message_id (string): Unique message ID.
conversation_id (string): Conversation ID.
mode (string): App mode, fixed as chat.
answer (string): Complete response content.
metadata (object): Metadata.
- usage (Usage): Model usage information.
- retriever_resources (array[RetrieverResource]): Citation and Attribution List.
created_at (int): Message creation timestamp, e.g., 1705395332.

ChunkChatCompletionResponse

Returns the stream chunks outputted by the App, Content-Type is text/event-stream. Each streaming chunk starts with data:, separated by two newline characters \n\n, as shown below:

data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n

The structure of the streaming chunks varies depending on the event:

event: message: LLM returns text chunk event, i.e., the complete text is output in a chunked fashion.
- task_id (string): Task ID, used for request tracking and the below Stop Generate API.
- message_id (string): Unique message ID.
- conversation_id (string): Conversation ID.
- answer (string): LLM returned text chunk content.
- created_at (int): Creation timestamp, e.g., 1705395332.
event: agent_message: LLM returns text chunk event, i.e., with Agent Assistant enabled, the complete text is output in a chunked fashion (Only supported in Agent mode).
- task_id (string): Task ID.
- message_id (string): Unique message ID.
- conversation_id (string): Conversation ID.
- answer (string): LLM returned text chunk content.
- created_at (int): Creation timestamp.
event: tts_message: TTS audio stream event. Speech synthesis output. Content is an audio block in Mp3 format, base64 encoded. Decode base64 and feed to player. (Available only when auto-play is enabled).
- task_id (string): Task ID.
- message_id (string): Unique message ID.
- audio (string): Base64 encoded audio content.
- created_at (int): Creation timestamp.
event: tts_message_end: TTS audio stream end event.
- task_id (string): Task ID.
- message_id (string): Unique message ID.
- audio (string): Empty string for this event.
- created_at (int): Creation timestamp.
event: agent_thought: Thought of Agent, contains LLM thought, tool call input/output (Only supported in Agent mode).
- id (string): Agent thought ID.
- task_id (string): Task ID.
- message_id (string): Unique message ID.
- position (int): Position of current agent thought.
- thought (string): What LLM is thinking.
- observation (string): Response from tool calls.
- tool (string): List of tools called, separated by ;.
- tool_input (string): JSON formatted tool input. E.g., {"dalle3": {"prompt": "a cute cat"}}.
- created_at (int): Creation timestamp.
- message_files (array[string]): File IDs.
  - file_id (string): File ID.
- conversation_id (string): Conversation ID.
event: message_file: Message file event, a new file created by a tool.
- id (string): File unique ID.
- type (string): File type, currently only “image”.
- belongs_to (string): Belongs to, will only be ‘assistant’ here.
- url (string): Remote URL of the file.
- conversation_id (string): Conversation ID.
event: message_end: Message end event, streaming has ended.
- task_id (string): Task ID.
- message_id (string): Unique message ID.
- conversation_id (string): Conversation ID.
- metadata (object): Metadata.
  - usage (Usage): Model usage information.
  - retriever_resources (array[RetrieverResource]): Citation and Attribution List.
event: message_replace: Message content replacement event. If content moderation flags content, it’s replaced via this event.
- task_id (string): Task ID.
- message_id (string): Unique message ID.
- conversation_id (string): Conversation ID.
- answer (string): Replacement content.
- created_at (int): Creation timestamp.
event: error: Exceptions during streaming. Reception ends the stream.
- task_id (string): Task ID.
- message_id (string): Unique message ID.
- status (int): HTTP status code.
- code (string): Error code.
- message (string): Error message.
event: ping: Ping event every 10 seconds to keep the connection alive.

Errors

404, Conversation does not exist.
400, invalid_param, abnormal parameter input.
400, app_unavailable, App configuration unavailable.
400, provider_not_initialize, no available model credential configuration.
400, provider_quota_exceeded, model invocation quota insufficient.
400, model_currently_not_support, current model unavailable.
400, completion_request_error, text generation failed.
500, internal server error.

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "inputs": {},
    "query": "What are the specs of the iPhone 13 Pro Max?",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "abc-123",
    "files": [
      {
        "type": "image",
        "transfer_method": "remote_url",
        "url": "https://cloud.dify.ai/logo/logo-site.png"
      }
    ]
}'

{
    "event": "message",
    "task_id": "c3800678-a077-43df-a102-53f23ed20b88", 
    "id": "9da23599-e713-473b-982c-4328d4f5c78a",
    "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
    "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
    "mode": "chat",
    "answer": "iPhone 13 Pro Max specs are listed here:...",
    "metadata": {
        "usage": {
            "prompt_tokens": 1033,
            "prompt_unit_price": "0.001",
            "prompt_price_unit": "0.001",
            "prompt_price": "0.0010330",
            "completion_tokens": 128,
            "completion_unit_price": "0.002",
            "completion_price_unit": "0.001",
            "completion_price": "0.0002560",
            "total_tokens": 1161,
            "total_price": "0.0012890",
            "currency": "USD",
            "latency": 0.7682376249867957
        },
        "retriever_resources": [
            {
                "position": 1,
                "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
                "dataset_name": "iPhone",
                "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
                "document_name": "iPhone List",
                "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
                "score": 0.98457545,
                "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
            }
        ]
    },
    "created_at": 1705407629
}

POST /files/upload File Upload

Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. Supports png, jpg, jpeg, webp, gif formats. Uploaded files are for use by the current end-user only.

Request Body

This interface requires a multipart/form-data request.

file (File, Required): The file to be uploaded.
user (string, Required): User identifier, defined by the developer’s rules, must be unique within the application.

Response

After a successful upload, the server will return the file’s ID and related information.

id (uuid): ID.
name (string): File name.
size (int): File size (bytes).
extension (string): File extension.
mime_type (string): File mime-type.
created_by (uuid): End-user ID.
created_at (timestamp): Creation timestamp, e.g., 1705395332.

Errors

400, no_file_uploaded, a file must be provided.
400, too_many_files, currently only one file is accepted.
400, unsupported_preview, the file does not support preview.
400, unsupported_estimate, the file does not support estimation.
413, file_too_large, the file is too large.
415, unsupported_file_type, unsupported extension.
503, s3_connection_failed, unable to connect to S3 service.
503, s3_permission_denied, no permission to upload files to S3.
503, s3_file_too_large, file exceeds S3 size limit.
500, internal server error.

'Authorization: Bearer {YOUR_API_KEY}' \ --form
'file=@"/path/to/your/localfile.png";type=image/png' \ --form
'user="abc-123"' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}

POST /chat-messages/:task_id/stop Stop Generate

Only supported in streaming mode.

Path Parameters

task_id (string): Task ID, can be obtained from the streaming chunk return.

Request Body

user (string, Required): User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface.

Response

result (string): Always returns “success”.

curl -X POST 'https://api.dify.ai/v1/chat-messages/:task_id/stop' \
-H 'Authorization: Bearer {YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "user": "abc-123"
}'

{
  "result": "success"
}

POST /messages/:message_id/feedbacks Message Feedback

End-users can provide feedback messages, facilitating application developers to optimize expected outputs.

Path Parameters

message_id (string): Message ID.

Request Body

rating (string): Upvote as like, downvote as dislike, revoke upvote/downvote as null.
user (string): User identifier, defined by the developer’s rules, must be unique within the application.
content (string, optional): The specific content of message feedback.

Response

result (string): Always returns “success”.

curl -X POST 'https://api.dify.ai/v1/messages/:message_id/feedbacks' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "rating": "like",
    "user": "abc-123",
    "content": "message feedback information"
}'

{
  "result": "success"
}

GET /messages/:message_id/suggested Next Suggested Questions

Get next questions suggestions for the current message.

Path Parameters

message_id (string): Message ID.

Query Parameters

user (string): User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.

{message_id}/suggested?user=abc-123' \ --header 'Authorization: Bearer {
    YOUR_API_KEY
}' \ --header 'Content-Type: application/json' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"result": "success",
"data": [
    "a",
    "b",
    "c"
]
}

GET /messages Get Conversation History Messages

Returns historical chat records in a scrolling load format, with the first page returning the latest {limit} messages, i.e., in reverse order.

Query Parameters

conversation_id (string): Conversation ID.
user (string): User identifier.
first_id (string, optional): The ID of the first chat record on the current page, default is null.
limit (int, optional, default 20): How many chat history messages to return in one request.

Response

data (array[object]): Message list.
- id (string): Message ID.
- conversation_id (string): Conversation ID.
- inputs (object): User input parameters.
- query (string): User input / question content.
- message_files (array[object]): Message files.
  - id (string): ID.
  - type (string): File type, image for images.
  - url (string): Preview image URL.
  - belongs_to (string): Belongs to, user or assistant.
- agent_thoughts (array[object]): Agent thought (Empty if it’s a Basic Assistant).
  - id (string): Agent thought ID.
  - message_id (string): Unique message ID.
  - position (int): Position of current agent thought.
  - thought (string): What LLM is thinking.
  - observation (string): Response from tool calls.
  - tool (string): List of tools called, separated by ;.
  - tool_input (string): JSON formatted tool input.
  - created_at (int): Creation timestamp.
  - message_files (array[string]): File IDs.
    - file_id (string): File ID.
- answer (string): Response message content.
- created_at (timestamp): Creation timestamp.
- feedback (object, optional): Feedback information.
  - rating (string): like / dislike.
- retriever_resources (array[RetrieverResource]): Citation and Attribution List.
has_more (bool): Whether there is a next page.
limit (int): Number of returned items.

'https://api.dify.ai/v1/messages?user=abc-123&conversation_id=
{YOUR_CONVERSATION_ID}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json "Basic Assistant Response"
{
"limit": 20,
"has_more": false,
"data": [
{
    "id": "a076a87f-31e5-48dc-b452-0061adbbc922",
    "conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
    "inputs": {
        "name": "dify"
    },
    "query": "iphone 13 pro",
    "answer": "The iPhone 13 Pro, released on September 24, 2021, features a 6.1-inch display...",
    "message_files": [],
    "feedback": null,
    "retriever_resources": [
        {
            "position": 1,
            "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
            // ... more retriever_resources fields
            "content": "\"Model\",\"Release Date\",\"Display Size\"..."
        }
    ],
    "agent_thoughts": [],
    "created_at": 1705569239
}
]
}

GET /conversations Get Conversations

Retrieve the conversation list for the current user, defaulting to the most recent 20 entries.

Query Parameters

user (string): User identifier.
last_id (string, optional): The ID of the last record on the current page, default is null.
limit (int, optional, default 20, max 100, min 1): How many records to return.
sort_by (string, optional, default -updated_at): Sorting Field. Available: created_at, -created_at, updated_at, -updated_at. - denotes descending.

Response

data (array[object]): List of conversations.
- id (string): Conversation ID.
- name (string): Conversation name.
- inputs (object): User input parameters.
- status (string): Conversation status.
- introduction (string): Introduction.
- created_at (timestamp): Creation timestamp.
- updated_at (timestamp): Update timestamp.
has_more (bool): Whether there is a next page.
limit (int): Number of entries returned.

'https://api.dify.ai/v1/conversations?user=abc-123&last_id=&limit=20' \
--header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"limit": 20,
"has_more": false,
"data": [
{
  "id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54",
  "name": "New chat",
  "inputs": {
      "book": "book",
      "myName": "Lucy"
  },
  "status": "normal",
  "created_at": 1679667915,
  "updated_at": 1679667915
},
{
  "id": "hSIhXBhNe8X1d8Et"
  // ...
}
]
}

DELETE /conversations/:conversation_id Delete Conversation

Delete a conversation.

Path Parameters

conversation_id (string): Conversation ID.

Request Body

user (string): The user identifier.

Response

204 No Content

curl -X DELETE 'https://api.dify.ai/v1/conversations/{conversation_id}' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user": "abc-123"
}'

text Response 204 No Content

POST /conversations/:conversation_id/name Conversation Rename

Rename the session. The session name is used for display on clients that support multiple sessions.

Path Parameters

conversation_id (string): Conversation ID.

Request Body

name (string, optional): The name of the conversation. Can be omitted if auto_generate is true.
auto_generate (bool, optional, default false): Automatically generate the title.
user (string): The user identifier.

Response

id (string): Conversation ID.
name (string): Conversation name.
inputs (object): User input parameters.
status (string): Conversation status.
introduction (string): Introduction.
created_at (timestamp): Creation timestamp.
updated_at (timestamp): Update timestamp.

curl -X POST 'https://api.dify.ai/v1/conversations/{conversation_id}/name' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "",
    "auto_generate": true,
    "user": "abc-123"
}'

{
    "id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
    "name": "Chat vs AI",
    "inputs": {},
    "status": "normal",
    "introduction": "",
    "created_at": 1705569238,
    "updated_at": 1705569238
}

GET /conversations/:conversation_id/variables Get Conversation Variables

Retrieve variables from a specific conversation. Useful for extracting structured data captured during the conversation.

Path Parameters

conversation_id (string): The ID of the conversation.

Query Parameters

user (string): The user identifier.
last_id (string, optional): The ID of the last record on the current page, default is null.
limit (int, optional, default 20, max 100, min 1): Number of records to return.
variable_name (string, optional): Filter by a specific variable name.

Response

limit (int): Number of items per page.
has_more (bool): Whether there is a next page.
data (array[object]): List of variables.
- id (string): Variable ID.
- name (string): Variable name.
- value_type (string): Variable type (e.g., string, number, object).
- value (string): Variable value.
- description (string): Variable description.
- created_at (int): Creation timestamp.
- updated_at (int): Last update timestamp.

Errors

404, conversation_not_exists, Conversation not found.

'https://api.dify.ai/v1/conversations/{conversation_id}
/variables?user=abc-123' \ --header 'Authorization: Bearer {YOUR_API_KEY}' ```
```bash "Filter by variable name" curl -X GET 'https://api.dify.ai/v1/conversations/
{conversation_id}
/variables?user=abc-123&variable_name=customer_name' \ --header
'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"limit": 100,
"has_more": false,
"data": [
{
  "id": "variable-uuid-1",
  "name": "customer_name",
  "value_type": "string",
  "value": "John Doe",
  "description": "Customer name extracted from the conversation",
  "created_at": 1650000000000,
  "updated_at": 1650000000000
},
{
  "id": "variable-uuid-2",
  "name": "order_details",
  "value_type": "json",
  "value": "{\"product\":\"Widget\",\"quantity\":5,\"price\":19.99}",
  "description": "Order details from the customer",
  "created_at": 1650000000000,
  "updated_at": 1650000000000
}
]
}

POST /audio-to-text Speech to Text

This endpoint requires a multipart/form-data request.

Request Body

file (file): Audio file. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. File size limit: 15MB.
user (string): User identifier.

Response

text (string): Output text.

'Authorization: Bearer {YOUR_API_KEY}' \ --form
'file=@"/path/to/your/audiofile.mp3";type=audio/mp3' \ --form
'user="abc-123"' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"text": "Transcribed text from audio."
}

POST /text-to-audio Text to Audio

Text to speech.

Request Body

message_id (string, optional): For text messages generated by Dify, pass the message_id. Backend uses it to find content for synthesis. Priority over text if both provided.
text (string, optional): Speech content to generate. Required if message_id is not provided.
user (string): The user identifier.

Response

The response is an audio file stream. Headers:

Content-Type: audio/wav (or other audio format depending on system configuration)

curl --location --request POST 'https://api.dify.ai/v1/text-to-audio' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "text": "Hello Dify",
    "user": "abc-123"
}' \
--output 'output.wav'

``` ```text "Response Body" (Binary audio data) ```
</CodeGroup>

---

## GET /info Get Application Basic Information

Used to get basic information about this application.

### Response

-   `name` (string): Application name.
-   `description` (string): Application description.
-   `tags` (array[string]): Application tags.

<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/info' \ -H 'Authorization:
Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}

GET /parameters Get Application Parameters Information

Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.

Query Parameters

user (string): User identifier.

Response

opening_statement (string): Opening statement.
suggested_questions (array[string]): List of suggested questions for the opening.
suggested_questions_after_answer (object): Suggest questions after enabling the answer.
- enabled (bool): Whether it is enabled.
speech_to_text (object): Speech to text.
- enabled (bool): Whether it is enabled.
retriever_resource (object): Citation and Attribution.
- enabled (bool): Whether it is enabled.
annotation_reply (object): Annotation reply.
- enabled (bool): Whether it is enabled.
user_input_form (array[object]): User input form configuration.
- text-input (object): Text input control.
  - label (string): Variable display label name.
  - variable (string): Variable ID.
  - required (bool): Whether it is required.
  - default (string): Default value.
- paragraph (object): Paragraph text input control.
  - label (string): Variable display label name.
  - variable (string): Variable ID.
  - required (bool): Whether it is required.
  - default (string): Default value.
- select (object): Dropdown control.
  - label (string): Variable display label name.
  - variable (string): Variable ID.
  - required (bool): Whether it is required.
  - default (string): Default value.
  - options (array[string]): Option values.
file_upload (object): File upload configuration.
- image (object): Image settings. Currently supports png, jpg, jpeg, webp, gif.
  - enabled (bool): Whether it is enabled.
  - number_limits (int): Image number limit (default 3).
  - transfer_methods (array[string]): List of transfer methods (remote_url, local_file).
system_parameters (object): System parameters.
- file_size_limit (int): Document upload size limit (MB).
- image_file_size_limit (int): Image file upload size limit (MB).
- audio_file_size_limit (int): Audio file upload size limit (MB).
- video_file_size_limit (int): Video file upload size limit (MB).

--header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"opening_statement": "Hello!",
"suggested_questions_after_answer": {
  "enabled": true
},
"speech_to_text": {
  "enabled": true
},
"retriever_resource": {
  "enabled": true
},
"annotation_reply": {
  "enabled": true
},
"user_input_form": [
  {
      "paragraph": {
          "label": "Query",
          "variable": "query",
          "required": true,
          "default": ""
      }
  }
],
"file_upload": {
  "image": {
      "enabled": false,
      "number_limits": 3,
      "detail": "high",
      "transfer_methods": [
          "remote_url",
          "local_file"
      ]
  }
},
"system_parameters": {
  "file_size_limit": 15,
  "image_file_size_limit": 10,
  "audio_file_size_limit": 50,
  "video_file_size_limit": 100
}
}

GET /meta Get Application Meta Information

Used to get icons of tools in this application.

Response

tool_icons (object): Tool icons.
- tool_name (string): Key is the tool name.
  - icon (object|string): Icon can be an object or a URL string.
    - (object) background (string): Background color in hex.
    - (object) content (string): Emoji or icon character.
    - (string) URL of the icon.

Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"tool_icons": {
"dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon",
"api_tool": {
  "background": "#252525",
  "content": "\ud83d\ude01"
}
}
}

GET /apps/annotations Get Annotation List

Query Parameters

page (int, optional, default 1): Page number.
limit (int, optional, default 20, range 1-100): Number of items returned.

'https://api.dify.ai/v1/apps/annotations?page=1&limit=20' \ --header
'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"data": [
{
  "id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
  "question": "What is your name?",
  "answer": "I am Dify.",
  "hit_count": 0,
  "created_at": 1735625869
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}

POST /apps/annotations Create Annotation

Request Body

question (string): Question.
answer (string): Answer.

curl --location --request POST 'https://api.dify.ai/v1/apps/annotations' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "question": "What is your name?",
    "answer": "I am Dify."
}'

{
  "id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
  "question": "What is your name?",
  "answer": "I am Dify.",
  "hit_count": 0,
  "created_at": 1735625869
}

PUT /apps/annotations/:annotation_id Update Annotation

Path Parameters

annotation_id (string): Annotation ID.

Request Body

question (string, optional): Question.
answer (string, optional): Answer.

curl --location --request PUT 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "question": "What is your full name?",
    "answer": "I am Dify, your AI assistant."
}'

{
  "id": "{annotation_id}",
  "question": "What is your full name?",
  "answer": "I am Dify, your AI assistant.",
  "hit_count": 0, 
  "created_at": 1735625869 
}

DELETE /apps/annotations/:annotation_id Delete Annotation

Path Parameters

annotation_id (string): Annotation ID.

Response

204 No Content

'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \ --header
'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>```text Response 204 No Content ```</CodeGroup>

---

## POST /apps/annotation-reply/:action Initial Annotation Reply Settings

### Path Parameters

-   `action` (string): Action, can only be `enable` or `disable`.

### Request Body

-   `embedding_model_provider` (string, optional): Specified embedding model provider. Must be set up in the system.
-   `embedding_model` (string, optional): Specified embedding model.
-   `score_threshold` (number, optional): Similarity threshold for matching annotated replies. Only annotations with scores above this threshold will be recalled. (Required if enabling)

**Note:** The provider and model name of the embedding model can be obtained through `v1/workspaces/current/models/model-types/text-embedding`. (Requires Dataset API Token for that endpoint).

<CodeGroup>
```bash "Enable with specific model"
curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/enable' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"score_threshold": 0.9,
"embedding_model_provider": "zhipu",
"embedding_model": "embedding_3"
}'

{
  "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
  "job_status": "waiting" 
}

GET /apps/annotation-reply/:action/status/:job_id Query Initial Annotation Reply Settings Task Status

Path Parameters

action (string): Action, enable or disable. Must match the action in the initial settings call.
job_id (string): Job ID from the initial settings call.

'https://api.dify.ai/v1/apps/annotation-reply/enable/status/{job_id}' \
--header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>

<CodeGroup>
```json Response
{
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
"job_status": "succeeded", // or "waiting", "processing", "failed"
"error_msg": "" // Contains error message if job_status is "failed"
}

Edit this page

Help improve our documentation by contributing directly

Report an issue

Found an error or have suggestions? Let us know

​Base URL

​Authentication

​POST /chat-messages Send Chat Message

​Request Body

​Response

​ChatCompletionResponse

​ChunkChatCompletionResponse

​Errors

​POST /files/upload File Upload

​Request Body

​Response

​Errors

​POST /chat-messages/:task_id/stop Stop Generate

​Path Parameters

​Request Body

​Response

​POST /messages/:message_id/feedbacks Message Feedback

​Path Parameters

​Request Body

​Response

​GET /messages/:message_id/suggested Next Suggested Questions

​Path Parameters

​Query Parameters

​GET /messages Get Conversation History Messages

​Query Parameters

​Response

​GET /conversations Get Conversations

​Query Parameters

​Response

​DELETE /conversations/:conversation_id Delete Conversation

​Path Parameters

​Request Body

​Response

​POST /conversations/:conversation_id/name Conversation Rename

​Path Parameters

​Request Body

​Response

​GET /conversations/:conversation_id/variables Get Conversation Variables

​Path Parameters

​Query Parameters

​Response

​Errors

​POST /audio-to-text Speech to Text

​Request Body

​Response

​POST /text-to-audio Text to Audio

​Request Body

​Response

​GET /parameters Get Application Parameters Information

​Query Parameters

​Response

​GET /meta Get Application Meta Information

​Response

​GET /apps/annotations Get Annotation List

​Query Parameters

​POST /apps/annotations Create Annotation

​Request Body

​PUT /apps/annotations/:annotation_id Update Annotation

​Path Parameters

​Request Body

​DELETE /apps/annotations/:annotation_id Delete Annotation

​Path Parameters

​Response

​GET /apps/annotation-reply/:action/status/:job_id Query Initial Annotation Reply Settings Task Status

​Path Parameters

Edit this page

Report an issue

Base URL

Authentication

POST /chat-messages Send Chat Message

Request Body

Response

ChatCompletionResponse

ChunkChatCompletionResponse

Errors

POST /files/upload File Upload

Request Body

Response

Errors

POST /chat-messages/:task_id/stop Stop Generate

Path Parameters

Request Body

Response

POST /messages/:message_id/feedbacks Message Feedback

Path Parameters

Request Body

Response

GET /messages/:message_id/suggested Next Suggested Questions

Path Parameters

Query Parameters

GET /messages Get Conversation History Messages

Query Parameters

Response

GET /conversations Get Conversations

Query Parameters

Response

DELETE /conversations/:conversation_id Delete Conversation

Path Parameters

Request Body

Response

POST /conversations/:conversation_id/name Conversation Rename

Path Parameters

Request Body

Response

GET /conversations/:conversation_id/variables Get Conversation Variables

Path Parameters

Query Parameters

Response

Errors

POST /audio-to-text Speech to Text

Request Body

Response

POST /text-to-audio Text to Audio

Request Body

Response

GET /parameters Get Application Parameters Information

Query Parameters

Response

GET /meta Get Application Meta Information

Response

GET /apps/annotations Get Annotation List

Query Parameters

POST /apps/annotations Create Annotation

Request Body

PUT /apps/annotations/:annotation_id Update Annotation

Path Parameters

Request Body

DELETE /apps/annotations/:annotation_id Delete Annotation

Path Parameters

Response

GET /apps/annotation-reply/:action/status/:job_id Query Initial Annotation Reply Settings Task Status

Path Parameters