Skip to main content
Welcome to the Dify API Documentation Center! This guide is designed to help you quickly get started, understand how to effectively use the interactive features provided in this documentation to test and comprehend the Dify API, and master the key elements of API access. Important Notes:
  • This Page: Primarily introduces how to interact with the API documentation, global access configurations (such as Base URL, API keys), and the documentation contribution process.
  • API Endpoint Details: All specific API endpoint content (including parameters, request/response structures, functional descriptions, and examples) is auto-generated based on our OpenAPI specification and includes the latest feature annotations. Please be sure to consult these auto-generated pages for the most accurate and detailed endpoint information.

API Access

Or click the API Access tab on the top navigation bar to view full API documentation.

​
Interactive API Testing

To help you quickly validate and understand the API, most API endpoint pages in this documentation include an embedded “Try It” interactive testing feature.
1

Locate the 'Try It' Feature

On the API endpoint documentation page you wish to test, usually at the top or right side of the page, you will find a prominent “Try It” button or a directly interactive parameter input area.
2

Configure Request Parameters

The system may attempt to pre-fill this, but please ensure you select or enter the correct Base URL based on your Dify deployment environment (Cloud or Self-hosted/On-premise). See the Server Address (Base URL) section below for details.
In the authentication section, you need to enter a valid API key obtained from your Dify application. See the API Key section for details.
If the API endpoint’s URL includes path parameters (e.g., /users/{user_id}) or requires query parameters (e.g., ?limit=10), please fill them in accurately according to the endpoint description.
For HTTP methods like POST, PUT, PATCH that require a request body, please refer to the request body schema and examples provided in the endpoint documentation to construct the correct JSON content.
3

Send Request and View Results

Once all parameters are configured, click the “Send” (or “Execute”) button to make the API call. Shortly after, you will see the complete API response in the same area, including the HTTP status code, response headers, and response body.

​
🔑 API Access Configuration

​
Server Address (Base URL)

The base URL for API requests varies depending on your Dify deployment environment: 
https://api.dify.ai/v1
When making API calls or using the “Try It” feature, ensure your configured Base URL is correct.

​
API Key

Each Dify application (App) has its own unique API key, used for authentication and authorization of API calls.
  • How to Obtain: You can manage or generate your API key on the Overview, API Access, or Monitoring page of your Dify application by clicking on API Key.
  • How to Use: After obtaining the API key, add it to the Authorization header of your HTTP request in the format Bearer YOUR_API_KEY.
  • Important Security Note:
    API keys are credentials for accessing your application data and have high privileges. Please treat them as sensitive information and keep them secure. Strictly prohibit hardcoding or directly exposing them in any client-side code (e.g., browser, mobile app frontend). It is recommended to store the API key in a secure server-side environment and proxy Dify API calls through your backend service.
  • Access Control: In the Monitoring -> Backend Service API settings of your Dify application, you can manage the API access status, for example, temporarily disabling all API calls.

​
📚 About Accessing the API and This Document

​
Document Structure and Source

  • This Guide Page (api-access-readme.mdx): Provides general information on how to use the API documentation, conduct interactive testing, and configure API access.
  • API Endpoint Detail Pages: All pages under the “API Endpoints” group in the sidebar are auto-generated from our OpenAPI specification (View OpenAPI specification source file template). These pages contain detailed descriptions, parameters, request/response examples, and the latest feature annotations for each endpoint.

​
How to Contribute to This Document

We greatly welcome and appreciate contributions from community members to the Dify documentation!
  • Editing This Page (This Guide)
  • Modifying API Endpoint Descriptions (OpenAPI Specification)
  • Reporting Issues or Suggestions
If you wish to modify this API Access and Interaction Guide page that you are currently reading, you can:
  1. Scroll to the bottom of this page.
  2. Click the “Edit this page” button.
  3. This will direct you to the editing interface for this api-access-readme.mdx file on GitHub.
Please note: The “Edit this page” button at the bottom of this page only applies to this guide page (api-access-readme.mdx) itself. It does not apply to the individual API endpoint detail pages.

Sync

API documentation is synchronized from the Dify main repository. You can click this card to view the original code on GitHub. If you find any discrepancies or errors, feel free to submit a PR to contribute code.
 All contributions (whether direct edits or issue reports) require a GitHub account. We look forward to your participation in building even better Dify documentation!
Edit this page | Report an issue
⌘I