dify-docs/en-us/user-guide/knowledge-base/api-documentation/external-knowledge-api.mdx

---
title: Chatbot
version: 'English'
---

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

## Base URL 
```
https://api.dify.ai/v1
```

## Authentication 
The Service API uses API-Key authentication. 

> **Important**: Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.  

For all API requests, include your API Key in the Authorization HTTP Header:
```
Authorization: Bearer {API_KEY}
```

## API Endpoints

### Send Chat Message
`POST /chat-messages`

Send a request to the chat application.

#### Request Body

- **query** (string) Required
  - User Input / Question Content

- **inputs** (object) Required
  - Allows the entry of various variable values defined by the App
  - Contains multiple key/value pairs, each key corresponding to a specific variable
  - At least one key/value pair required

- **response_mode** (string) Required
  - Modes supported:
    - `streaming`: Streaming mode (recommended), implements typewriter-like output through SSE
    - `blocking`: Blocking mode, returns result after execution completes
      - Note: Due to Cloudflare restrictions, requests will timeout after 100 seconds
      - Note: blocking mode is not supported in Agent Assistant mode

- **user** (string) Required
  - User identifier for retrieval and statistics
  - Should be uniquely defined within the application

- **conversation_id** (string) Optional
  - Conversation ID to continue based on previous chat records

- **files** (array[object]) Optional
  - File list for image input with text understanding
  - Available only when model supports Vision capability
  - Properties:
    - `type` (string): Supported type: image
    - `transfer_method` (string): 'remote_url' or 'local_file'
    - `url` (string): Image URL (for remote_url)
    - `upload_file_id` (string): Uploaded file ID (for local_file)

- **auto_generate_name** (bool) Optional
  - Auto-generate title, default is false
  - Can achieve async title generation via conversation rename API

#### Response Types

**Blocking Mode Response (ChatCompletionResponse)**
Returns complete App result with Content-Type: application/json

```typescript
interface ChatCompletionResponse {
  message_id: string;
  conversation_id: string;
  mode: string;
  answer: string;
  metadata: {
    usage: Usage;
    retriever_resources: RetrieverResource[];
  };
  created_at: number;
}
```

**Streaming Mode Response (ChunkChatCompletionResponse)**
Returns stream chunks with Content-Type: text/event-stream

Events:
- `message`: LLM text chunk event
- `agent_message`: LLM text chunk event (Agent Assistant mode)
- `agent_thought`: Agent reasoning process 
- `message_file`: New file created by tool
- `message_end`: Stream end event
- `message_replace`: Content replacement event
- `workflow_started`: Workflow execution start
- `node_started`: Node execution start
- `node_finished`: Node execution completion
- `workflow_finished`: Workflow execution completion
- `parallel_branch_started`: Parallel branch start
- `parallel_branch_finished`: Parallel branch completion
- `iteration_started`: Iteration start
- `iteration_next`: Next iteration
- `iteration_completed`: Iteration completion
- `error`: Exception event
- `ping`: Keep-alive event (every 10s)

### File Upload
`POST /files/upload`

Upload files (currently only images) for multimodal understanding.

#### Supported Formats
- png
- jpg
- jpeg
- webp
- gif

#### Request Body
Requires multipart/form-data:
- `file` (File) Required
- `user` (string) Required

#### Response
```typescript
interface FileUploadResponse {
  id: string;
  name: string;
  size: number;
  extension: string;
  mime_type: string;
  created_by: string;
  created_at: number;
}
```

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

Stop ongoing generation (streaming mode only).

#### Request Body
- `user` (string) Required

#### Response
```json
{
    "result": "success"
}
```

### Message Feedback
`POST /messages/:message_id/feedbacks`

Submit user feedback on messages.

#### Request Body
- `rating` (string) Required: "like" | "dislike" | null
- `user` (string) Required

#### Response
```json
{
    "result": "success"
}
```

### Get Conversation History
`GET /messages`

Returns historical chat records in reverse chronological order.

#### Query Parameters
- `conversation_id` (string) Required
- `user` (string) Required
- `first_id` (string) Optional: First chat record ID
- `limit` (int) Optional: Default 20

#### Response
```typescript
interface ConversationHistory {
  data: Array<{
    id: string;
    conversation_id: string;
    inputs: Record<string, any>;
    query: string;
    message_files: Array<{
      id: string;
      type: string;
      url: string;
      belongs_to: 'user' | 'assistant';
    }>;
    agent_thoughts: Array<{
      id: string;
      message_id: string;
      position: number;
      thought: string;
      observation: string;
      tool: string;
      tool_input: string;
      created_at: number;
      message_files: string[];
    }>;
    answer: string;
    created_at: number;
    feedback?: {
      rating: 'like' | 'dislike';
    };
    retriever_resources: RetrieverResource[];
  }>;
  has_more: boolean;
  limit: number;
}
```

### Get Conversations
`GET /conversations`

Retrieve conversation list for current user.

#### Query Parameters
- `user` (string) Required
- `last_id` (string) Optional
- `limit` (int) Optional: Default 20
- `pinned` (boolean) Optional

#### Response
```typescript
interface ConversationList {
  data: Array<{
    id: string;
    name: string;
    inputs: Record<string, any>;
    introduction: string;
    created_at: number;
  }>;
  has_more: boolean;
  limit: number;
}
```

### Delete Conversation
`DELETE /conversations/:conversation_id`

Delete a conversation.

#### Request Body
- `user` (string) Required

#### Response
```json
{
    "result": "success"
}
```

### Rename Conversation
`POST /conversations/{conversation_id}/name`

#### Request Body
- `name` (string) Optional
- `auto_generate` (boolean) Optional: Default false
- `user` (string) Required

#### Response
```typescript
interface RenamedConversation {
  id: string;
  name: string;
  inputs: Record<string, any>;
  introduction: string;
  created_at: number;
}
```

### Speech to Text
`POST /audio-to-text`

Convert audio to text.

#### Request Body (multipart/form-data)
- `file` (File) Required
  - Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm
  - Size limit: 15MB
- `user` (string) Required

#### Response
```typescript
interface AudioToTextResponse {
  text: string;
}
```

### Get Application Parameters
`GET /parameters`

Retrieve application configuration and settings.

#### Query Parameters
- `user` (string) Required

#### Response
```typescript
interface ApplicationParameters {
  opening_statement: string;
  suggested_questions_after_answer: {
    enabled: boolean;
  };
  speech_to_text: {
    enabled: boolean;
  };
  retriever_resource: {
    enabled: boolean;
  };
  annotation_reply: {
    enabled: boolean;
  };
  user_input_form: Array<{
    'text-input' | 'paragraph' | 'select': {
      label: string;
      variable: string;
      required: boolean;
      default: string;
      options?: string[];
    };
  }>;
  file_upload: {
    image: {
      enabled: boolean;
      number_limits: number;
      transfer_methods: string[];
    };
  };
  system_parameters: {
    image_file_size_limit: string;
  };
}
```

### Get Application Meta Information
`GET /meta`

Retrieve tool icons and metadata.

#### Query Parameters
- `user` (string) Required

#### Response
```typescript
interface ApplicationMeta {
  tool_icons: Record<string, string | {
    background: string;
    content: string;
  }>;
}
```

## Type Definitions

### Usage
```typescript
interface Usage {
  prompt_tokens: number;
  prompt_unit_price: string;
  prompt_price_unit: string;
  prompt_price: string;
  completion_tokens: number;
  completion_unit_price: string;
  completion_price_unit: string;
  completion_price: string;
  total_tokens: number;
  total_price: string;
  currency: string;
  latency: number;
}
```

### RetrieverResource
```typescript
interface RetrieverResource {
  position: number;
  content: string;
  score: string;
  dataset_id: string;
  dataset_name: string;
  document_id: string;
  document_name: string;
  segment_id: string;
}
```

## Error Codes

Common error codes you may encounter:
- 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

For file uploads:
- 400: no_file_uploaded - File must be provided
- 400: too_many_files - Only one file accepted
- 400: unsupported_preview - File does not support preview
- 400: unsupported_estimate - File does not support estimation
- 413: file_too_large - File is too large
- 415: unsupported_file_type - Unsupported extension
- 503: s3_connection_failed - Unable to connect to S3
- 503: s3_permission_denied - No permission for S3
- 503: s3_file_too_large - Exceeds S3 size limit