From 49d53ea25a8f951ef35a1d388debcb13d3bbc078 Mon Sep 17 00:00:00 2001
From: Alter-xyz <88554920+alterxyz@users.noreply.github.com>
Date: Mon, 19 May 2025 16:23:49 +0800
Subject: [PATCH] chore: en ja api-access-readme
---
docs.json | 6 +-
en/openapi-api-access-readme.mdx | 137 ++++++++++++++++++++++++++
ja-jp/openapi-api-access-readme.mdx | 137 ++++++++++++++++++++++++++
zh-hans/openapi-api-access-readme.mdx | 2 +-
4 files changed, 279 insertions(+), 3 deletions(-)
create mode 100644 en/openapi-api-access-readme.mdx
create mode 100644 ja-jp/openapi-api-access-readme.mdx
diff --git a/docs.json b/docs.json
index 4fc282aa..7f041737 100644
--- a/docs.json
+++ b/docs.json
@@ -45,7 +45,8 @@
},
"en/getting-started/cloud",
"en/getting-started/dify-premium",
- "en/getting-started/dify-for-education"
+ "en/getting-started/dify-for-education",
+ "en/openapi-api-access-readme"
]
},
{
@@ -1303,7 +1304,8 @@
]
},
"ja-jp/getting-started/dify-premium",
- "ja-jp/getting-started/dify-for-education"
+ "ja-jp/getting-started/dify-for-education",
+ "ja-jp/openapi-api-access-readme"
]
},
{
diff --git a/en/openapi-api-access-readme.mdx b/en/openapi-api-access-readme.mdx
new file mode 100644
index 00000000..a9da5cf5
--- /dev/null
+++ b/en/openapi-api-access-readme.mdx
@@ -0,0 +1,137 @@
+---
+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.**
+
+
+
+
+---
+
+## 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.
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+ 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.
+
+
+ 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.
+
+
+
+
+ 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:
+
+
+ ```bash Dify Cloud
+https://api.dify.ai/v1
+ ```
+
+ ```bash Self-hosted / On-premise Deployment
+http://localhost/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](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!
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+ 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:
+ 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-mintlify).
+ 3. 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!
+
+
+
+
+
+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!
diff --git a/ja-jp/openapi-api-access-readme.mdx b/ja-jp/openapi-api-access-readme.mdx
new file mode 100644
index 00000000..0dc1a1b4
--- /dev/null
+++ b/ja-jp/openapi-api-access-readme.mdx
@@ -0,0 +1,137 @@
+---
+title: 'APIアクセス'
+summary: '本文書内の「試してみる」機能を使ってDify APIをインタラクティブにテストする方法、ベースURLやAPIキーに関する重要な情報、そしてドキュメントエコシステムへの貢献方法について学びます。'
+---
+
+Dify APIドキュメントセンターへようこそ！このガイドは、Dify APIを効果的にテストし理解するために本文書が提供するインタラクティブ機能を活用する方法、そしてAPIアクセスの主要な要素を習得するためのお手伝いを目的としています。
+
+**重要事項：**
+
+* **このページの内容：** 主にAPIドキュメントのインタラクティブな利用方法、グローバルなアクセス設定（ベースURL、APIキーなど）、およびドキュメントへの貢献プロセスについて説明します。
+* **APIエンドポイント詳細：** 全ての具体的なAPIエンドポイント（パラメータ、リクエスト/レスポンス構造、機能説明、例を含む）の内容は、OpenAPI仕様に基づいて自動生成され、最新の機能に関する注釈が含まれています。**最も正確で詳細なエンドポイント情報については、これらの自動生成されたページを必ず参照してください。**
+
+
+
+
+---
+
+## インタラクティブなAPIテスト
+
+APIを迅速に検証し理解していただくために、本文書のほとんどのAPIエンドポイントページには、「試してみる」(Try It) というインタラクティブなテスト機能が組み込まれています。
+
+
+
+ テストしたいAPIエンドポイントのドキュメントページで、通常はページ上部または右側の領域に、目立つ「試してみる」ボタンまたは直接操作可能なパラメータ入力領域があります。
+
+
+
+
+ システムが自動入力試みる場合がありますが、Difyのデプロイ環境（クラウド版またはセルフホスト/オンプレミス版）に応じて正しいベースURLを選択または入力してください。詳細は下記の [サーバーアドレス (ベースURL)](#サーバーアドレス-base-url) セクションを参照してください。
+
+
+ 認証セクションに、Difyアプリケーションから取得した有効なAPIキーを入力する必要があります。詳細は [APIキー (API Key)](#apiキー-api-key) セクションを参照してください。
+
+
+ APIエンドポイントのURLにパスパラメータ (例: `/users/{user_id}`) が含まれる場合や、クエリパラメータ (例: `?limit=10`) が必要な場合は、エンドポイントの説明に従って正確に入力してください。
+
+
+ `POST`, `PUT`, `PATCH` など、リクエストボディが必要なHTTPメソッドについては、エンドポイントドキュメントに記載されているリクエストボディの構造 (スキーマ) と例を参照して、正しいJSONコンテンツを作成してください。
+
+
+
+
+ すべてのパラメータ設定が完了したら、「送信」(Send) (または「実行」(Execute)) ボタンをクリックしてAPI呼び出しを開始します。しばらくすると、同じ領域にHTTPステータスコード、レスポンスヘッダー、レスポンスボディを含む完全なAPIレスポンスが表示されます。
+
+
+
+---
+
+## 🔑 APIアクセス設定
+
+### サーバーアドレス (ベースURL)
+
+APIリクエストのベースURLは、Difyのデプロイ環境によって異なります。
+
+
+ ```bash Dify クラウド版
+https://api.dify.ai/v1
+ ```
+
+ ```bash セルフホスト / オンプレミス版
+http://localhost/v1
+ ```
+
+
+ API呼び出しを行う際や「試してみる」機能を使用する際は、設定したベースURLが正しいことを必ず確認してください。
+
+
+### APIキー (API Key)
+
+Difyの**各**アプリケーション (App) は、インターフェース呼び出しの認証と認可に使用される、それぞれ専用のAPIキーを所有しています。
+
+* **取得方法：** Difyアプリケーションの概要、`APIアクセス`、または `モニタリング` ページで `APIキー` をクリックして、APIキーを管理または生成できます。
+
+* **使用方法：** APIキーを取得したら、HTTPリクエストの `Authorization` ヘッダーに `Bearer YOUR_API_KEY` の形式で追加してください。
+
+* **重要なセキュリティに関する注意：**
+
+ APIキーはアプリケーションデータへのアクセス資格情報であり、高い権限を持っています。**機密情報として扱い、厳重に保管してください。クライアントサイドのコード（ブラウザ、モバイルアプリのフロントエンドなど）にハードコーディングしたり、直接公開したりすることは絶対に避けてください。** APIキーは安全なサーバーサイド環境に保存し、バックエンドサービスを介してDify APIの呼び出しをプロキシすることを推奨します。
+
+
+* **アクセス制御：** Difyアプリケーションの **モニタリング (Monitoring) -> バックエンドサービスAPI (Backend Service API)** 設定で、APIのアクセス状態を管理できます。例えば、すべてのAPI呼び出しを一時的に無効にすることができます。
+
+---
+
+## 📚 `APIアクセス`と本文書について
+
+### ドキュメントの構成とソース
+
+* **本ガイドページ (`api-access-readme.mdx`)：** APIドキュメントの使用方法、インタラクティブテストの実施方法、APIアクセスの一般的な設定情報を提供します。
+* **APIエンドポイント詳細ページ：** サイドバーの **「APIエンドポイント」** グループ以下のすべてのページは、当社のOpenAPI仕様 ([OpenAPI仕様ソースファイルテンプレートを見る](https://github.com/langgenius/dify/tree/main/web/app/components/develop/template)) から **自動生成** されています。これらのページには、各エンドポイントの詳細な説明、パラメータ、リクエスト/レスポンスの例、最新の機能に関する注釈が含まれています。
+
+### 本文書への貢献方法
+
+Difyドキュメントへのコミュニティメンバーからの貢献を心より歓迎し、感謝いたします！
+
+
+
+ もし **現在ご覧になっているこの `APIアクセスとインタラクションガイド` ページ** を修正したい場合は、以下の手順で行うことができます：
+ 1. このページの下部までスクロールします。
+ 2. **「このページを編集」(Edit this page)** ボタンをクリックします。
+ 3. これにより、GitHub上のこの `api-access-readme.mdx` ファイルの編集インターフェースに直接移動します。
+
+
+ 注意：このページ下部の **「このページを編集」** ボタンは、**現在のこのガイドページ (`api-access-readme.mdx`) 自体にのみ作用します**。
+ 個々の `APIアクセス` 詳細ページには **適用されません**。
+
+
+
+
+ `APIアクセス` 詳細ページ内の特定の **APIエンドポイントの説明、パラメータ、または例の更新が必要** な場合、これらの内容はOpenAPI仕様ファイルから来ています。
+ 1. Difyのドキュメントコードリポジトリにアクセスしてください。
+ 2. 関連するOpenAPI JSONファイルを見つけます（言語ごとにサブディレクトリに分かれています。例：`en/openapi_chatflow.json`, `zh-hans/openapi_workflow.json` など）。
+ 3. 対応するOpenAPIファイルの内容を修正します。
+ 4. Difyのメインリポジトリにプルリクエストを送信します。
+
+
+ 多言語ドキュメントの一貫性を保つため、ある言語のOpenAPIファイルを変更した場合は、他の言語バージョンの対応するOpenAPIファイルも確認し、同期して更新することをお勧めします。
+
+
+
+
+ ドキュメント（本ガイドページまたは特定のAPIエンドポイントページ）に問題を発見した場合、または改善提案がある場合：
+ 1. ページ下部（またはサイドバー）の **「問題を報告」(Report an issue)** リンクを使用できます。
+ 2. これにより、通常、このドキュメントプロジェクト (dify-docs-mintlify) のGitHub Issuesページに移動します。
+ 3. 発見した問題、問題のあるページのリンク、および改善提案を詳細に記述してください。
+
+
+ 正確な問題報告と建設的な提案も、コミュニティとプロジェクトへの重要な貢献です！
+
+
+
+
+
+APIドキュメントはDifyのメインリポジトリから同期されています。このカードをクリックすると、GitHubで元のコードを確認できます。同期のずれや誤りを見つけた場合は、ぜひPRを送信してコードに貢献してください。
+
+
+すべての貢献（直接編集または問題報告）にはGitHubアカウントが必要です。より完全なDify利用ドキュメントを共に作り上げるための皆様のご参加をお待ちしております！
diff --git a/zh-hans/openapi-api-access-readme.mdx b/zh-hans/openapi-api-access-readme.mdx
index a00b0113..651427ac 100644
--- a/zh-hans/openapi-api-access-readme.mdx
+++ b/zh-hans/openapi-api-access-readme.mdx
@@ -10,7 +10,7 @@ summary: '学习如何通过本文档的 "Try It" 功能与 Dify API 进行交
* **本页内容：** 主要介绍 API 文档的交互方式、全局访问配置（如 Base URL、API 密钥）以及文档贡献流程。
* **API 端点详情：** 所有具体的 API 端点（包括其参数、请求/响应结构、功能描述及示例）内容是根据我们的 OpenAPI 规范自动生成的，并包含了最新的功能注释。**请务必查阅这些自动生成的页面以获取最准确和详细的端点信息。**
-
+
---