API Access
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.
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.
Configure Request Parameters
Server Address (Base URL)
Server Address (Base URL)
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.
Authentication (API Key)
Authentication (API Key)
In the authentication section, you need to enter a valid API key obtained from your Dify application. See the API Key section for details.
Path and Query Parameters
Path and Query Parameters
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.
Request Body
Request Body
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.
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:
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, orMonitoringpage of your Dify application by clicking onAPI Key. -
How to Use: After obtaining the API key, add it to the
Authorizationheader of your HTTP request in the formatBearer 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!
If you wish to modify this API Access and Interaction Guide page that you are currently reading, you can:
- Scroll to the bottom of this page.
- Click the “Edit this page” button.
- This will direct you to the editing interface for this
api-access-readme.mdxfile 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.
If you wish to modify this API Access and Interaction Guide page that you are currently reading, you can:
- Scroll to the bottom of this page.
- Click the “Edit this page” button.
- This will direct you to the editing interface for this
api-access-readme.mdxfile 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.
If you find that the description, parameter details, or examples for a specific API endpoint on an Accessing the API detail page need updating, this content originates from the OpenAPI specification files.
- Go to Dify’s documentation code repository.
- Locate the relevant OpenAPI JSON file (organized by language in subdirectories, e.g.,
en/openapi_chatflow.json,zh-hans/openapi_workflow.json). - Modify the content of the corresponding OpenAPI file.
- Submit a Pull Request to the Dify main repository.
To maintain consistency across multilingual documentation, if you modify an OpenAPI file for one language, it’s advisable to check and update the corresponding OpenAPI files in other language versions as well.
If you find any issues in the documentation (whether on this guide page or a specific API endpoint page), or have suggestions for improvement:
- You can use the “Report an issue” link at the bottom of the page (or in the sidebar).
- This will typically direct you to the GitHub Issues page for this documentation project (dify-docs).
- Please provide a detailed description of the issue, a link to the page where the issue occurs, and your suggestions for improvement.
Accurate issue reports and constructive suggestions are also important contributions to the community and the project!
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!