diff --git a/docs/api-reference/getting-started.mdx b/docs/api-reference/getting-started.mdx
new file mode 100644
index 000000000..995592389
--- /dev/null
+++ b/docs/api-reference/getting-started.mdx
@@ -0,0 +1,75 @@
+---
+title: Getting Started
+description: Authenticate with the Factory Public API and make your first request.
+keywords:
+ [
+ "api",
+ "getting started",
+ "authentication",
+ "api key",
+ "rest api",
+ "factory api",
+ ]
+---
+
+The Factory Public API exposes the same primitives that power the Droid CLI and Factory App: computers, sessions, and organization configuration. Use it to provision Droid environments, drive sessions programmatically, and manage org-level resources from your own systems.
+
+---
+
+## Authentication
+
+All requests require a Factory API key in the `Authorization` header:
+
+```bash
+Authorization: Bearer fk-your-api-key
+```
+
+### Generate an API key
+
+1. Sign in to the Factory App at app.factory.ai.
+2. Open app.factory.ai/settings/api-keys.
+3. Click **Create API key**, give it a descriptive name, and copy the value (it begins with `fk-`).
+
+The key is shown once. Store it in a secrets manager or environment variable. Treat it like a password: do not commit it to source control or paste it into shared logs.
+
+```bash
+export FACTORY_API_KEY="fk-your-api-key"
+```
+
+
+
+### Permissions
+
+Only users with **Manager** or **Owner** roles can create API keys and call the Public API. Members and guests will receive a `403 Forbidden` response.
+
+API keys inherit the role of the user who created them. Revoke keys from [app.factory.ai/settings/api-keys](https://app.factory.ai/settings/api-keys) when team members change roles or leave the organization.
+
+---
+
+## Available Endpoints
+
+The Public API is grouped into three resource families:
+
+| Group | Description |
+| :------------- | :-------------------------------------------------------------------------- |
+| `Computers` | Provision, list, restart, and delete persistent Droid computer environments |
+| `Sessions` | Create sessions, post messages, and inspect session history |
+| `Organization` | Manage org users, usage limits, and enterprise control history |
+
+Browse the endpoint reference under each group in the left sidebar.
+
+---
+
+## Next Steps
+
+
+
+ See existing Droid computer environments in your organization
+
+
+ Drive a Droid programmatically from your own systems
+
+
+ Invite, remove, and configure org members for admin workflows
+
+
diff --git a/docs/docs.json b/docs/docs.json
index 1288c6359..1d184a87b 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -295,7 +295,16 @@
},
{
"tab": "API Reference",
- "openapi": "https://api.factory.ai/api/v0/openapi.json"
+ "pages": [
+ "api-reference/getting-started",
+ {
+ "group": "Endpoints",
+ "openapi": {
+ "source": "https://api.factory.ai/api/v0/openapi.json",
+ "directory": "api-reference"
+ }
+ }
+ ]
}
]
},
@@ -559,10 +568,16 @@
},
{
"tab": "APIリファレンス",
- "openapi": {
- "source": "https://api.factory.ai/api/v0/openapi.json",
- "directory": "jp/api-reference"
- }
+ "pages": [
+ "jp/api-reference/getting-started",
+ {
+ "group": "Endpoints",
+ "openapi": {
+ "source": "https://api.factory.ai/api/v0/openapi.json",
+ "directory": "jp/api-reference"
+ }
+ }
+ ]
}
]
}
diff --git a/docs/images/web/api-keys-page.png b/docs/images/web/api-keys-page.png
new file mode 100644
index 000000000..d9a376a0d
Binary files /dev/null and b/docs/images/web/api-keys-page.png differ
diff --git a/docs/jp/api-reference/getting-started.mdx b/docs/jp/api-reference/getting-started.mdx
new file mode 100644
index 000000000..6ebed6f61
--- /dev/null
+++ b/docs/jp/api-reference/getting-started.mdx
@@ -0,0 +1,75 @@
+---
+title: はじめに
+description: Factory Public APIで認証して、最初のリクエストを送信します。
+keywords:
+ [
+ "api",
+ "getting started",
+ "authentication",
+ "api key",
+ "rest api",
+ "factory api",
+ ]
+---
+
+Factory Public APIは、Droid CLIとFactory Appを動かしているのと同じプリミティブ（コンピューター、セッション、組織設定）を公開しています。Droid環境のプロビジョニング、セッションのプログラム制御、組織レベルのリソース管理を、ご自身のシステムから実行できます。
+
+---
+
+## 認証
+
+すべてのリクエストには、`Authorization`ヘッダーにFactory APIキーが必要です：
+
+```bash
+Authorization: Bearer fk-your-api-key
+```
+
+### APIキーの生成
+
+1. Factory Appに app.factory.ai でサインインします。
+2. app.factory.ai/settings/api-keys を開きます。
+3. **Create API key** をクリックし、わかりやすい名前を付けて、値（`fk-` で始まる文字列）をコピーします。
+
+キーは一度だけ表示されます。シークレットマネージャーまたは環境変数に保存してください。パスワードと同様に扱い、ソース管理にコミットしたり、共有ログに貼り付けたりしないでください。
+
+```bash
+export FACTORY_API_KEY="fk-your-api-key"
+```
+
+
+
+### 権限
+
+APIキーの作成とPublic APIの呼び出しが可能なのは、**Manager** または **Owner** ロールのユーザーのみです。メンバーとゲストは `403 Forbidden` レスポンスを受け取ります。
+
+APIキーは作成したユーザーのロールを継承します。チームメンバーのロールが変更されたり組織を離れたりした場合は、[app.factory.ai/settings/api-keys](https://app.factory.ai/settings/api-keys) からキーを失効させてください。
+
+---
+
+## 利用可能なエンドポイント
+
+Public APIは3つのリソースグループに分かれています：
+
+| グループ | 説明 |
+| :------------- | :-------------------------------------------------------------------- |
+| `Computers` | 永続的なDroidコンピューター環境のプロビジョニング、一覧、再起動、削除 |
+| `Sessions` | セッションの作成、メッセージの投稿、セッション履歴の取得 |
+| `Organization` | 組織ユーザー、使用量上限、エンタープライズコントロール履歴の管理 |
+
+各グループのエンドポイントリファレンスは、左サイドバーから参照できます。
+
+---
+
+## 次のステップ
+
+
+
+ 組織内の既存のDroidコンピューター環境を確認します
+
+
+ ご自身のシステムからDroidをプログラム制御します
+
+
+ 管理者ワークフロー向けに組織メンバーを招待、削除、設定します
+
+
diff --git a/docs/style.css b/docs/style.css
index 42ed46005..468d7b8dc 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -260,3 +260,30 @@ a.text-primary.border-primary {
color: #ff9c6e !important;
text-decoration-color: #ff9c6e !important;
}
+
+/* Plain prose links - inherit text color instead of brand orange */
+.dark .prose p a.url-plain:not(.card a),
+.dark .prose li a.url-plain:not(.card a),
+.dark .prose td a.url-plain:not(.card a),
+.dark .prose dd a.url-plain:not(.card a) {
+ color: inherit !important;
+ text-decoration: underline !important;
+ text-decoration-color: currentColor !important;
+}
+
+.dark .prose p a.url-plain:not(.card a):hover,
+.dark .prose li a.url-plain:not(.card a):hover,
+.dark .prose td a.url-plain:not(.card a):hover,
+.dark .prose dd a.url-plain:not(.card a):hover {
+ color: #ffffff !important;
+ text-decoration-color: #ffffff !important;
+}
+
+.prose p a.url-plain:not(.card a),
+.prose li a.url-plain:not(.card a),
+.prose td a.url-plain:not(.card a),
+.prose dd a.url-plain:not(.card a) {
+ color: inherit !important;
+ text-decoration: underline !important;
+ text-decoration-color: currentColor !important;
+}