dify-docs/en/openapi-api-access-readme.mdx

---
title: 'API Access'
summary: 'Learn how to interactively test Dify APIs using the "Try It" feature in this documentation, get important information about Base URL and API keys, and understand how to contribute to our documentation ecosystem.'
---

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.**

<Card title="API Access" icon="code" href="/api-reference/chat/send-chat-message" horizontal>
Or click the `API Access` tab on the top navigation bar to view full API documentation.
</Card>

---

## 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.

<Steps>
  <Step title="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.
  </Step>
  <Step title="Configure Request Parameters">
    <AccordionGroup>
      <Accordion title="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)](#server-address-base-url) section below for details.
      </Accordion>
      <Accordion title="Authentication (API Key)">
        In the authentication section, you need to enter a valid API key obtained from your Dify application. See the [API Key](#api-key) section for details.
      </Accordion>
      <Accordion title="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.
      </Accordion>
      <Accordion title="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.
      </Accordion>
    </AccordionGroup>
  </Step>
  <Step title="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.
  </Step>
</Steps>

---

## 🔑 API Access Configuration

### Server Address (Base URL)

The base URL for API requests varies depending on your Dify deployment environment:

<CodeGroup>
  ```bash Dify Cloud
https://api.dify.ai/v1
  ```

  ```bash Self-hosted / On-premise Deployment
http://localhost/v1
  ```
</CodeGroup>
<Info>
  When making API calls or using the "Try It" feature, ensure your configured Base URL is correct.
</Info>

### 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:**
    <Warning>
      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.
    </Warning>

*   **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](https://github.com/langgenius/dify/tree/main/web/app/components/develop/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!

<Tabs>
  <Tab title="Editing This Page (This Guide)">
    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 <Icon icon="pen-to-square" /> **"Edit this page"** button.
    3.  This will direct you to the editing interface for this `api-access-readme.mdx` file on GitHub.

    <Note>
      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.
    </Note>
  </Tab>

  <Tab title="Modifying API Endpoint Descriptions (OpenAPI Specification)">
    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.
    1.  Go to Dify's documentation code repository.
    2.  Locate the relevant OpenAPI JSON file (organized by language in subdirectories, e.g., `en/openapi_chatflow.json`, `zh-hans/openapi_workflow.json`).
    3.  Modify the content of the corresponding OpenAPI file.
    4.  Submit a Pull Request to the Dify main repository.

    <Tip>
      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.
    </Tip>
  </Tab>

  <Tab title="Reporting Issues or Suggestions">
    If you find any issues in the documentation (whether on this guide page or a specific API endpoint page), or have suggestions for improvement:
    1.  You can use the **"Report an issue"** link at the bottom of the page (or in the sidebar).
    2.  This will typically direct you to the GitHub Issues page for this documentation project (dify-docs).
    3.  Please provide a detailed description of the issue, a link to the page where the issue occurs, and your suggestions for improvement.

    <Check>
      Accurate issue reports and constructive suggestions are also important contributions to the community and the project!
    </Check>
  </Tab>
</Tabs>

<Card title="Sync" icon="rotate" href="https://github.com/langgenius/dify/tree/main/web/app/components/develop/template" horizontal>
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.
</Card>

All contributions (whether direct edits or issue reports) require a GitHub account. We look forward to your participation in building even better Dify documentation!

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/openapi-api-access-readme.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?title=Documentation%20Issue%3A%20pi-api-access-rea&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs%2Fblob%2Fmain%2Fen%2Fopenapi-api-access-readme.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E)