docs: Api getting started

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 <a href="https://app.factory.ai" target="_blank" rel="noreferrer" className="url-plain">app.factory.ai</a>.
+2. Open <a href="https://app.factory.ai/settings/api-keys" target="_blank" rel="noreferrer" className="url-plain">app.factory.ai/settings/api-keys</a>.
+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"
+```
+
+![Factory API keys settings page](/images/web/api-keys-page.png)
+
+### 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
+
+<CardGroup cols={2}>
+  <Card title="List Computers" href="/api-reference/computers/list-computers" icon="server">
+    See existing Droid computer environments in your organization
+  </Card>
+  <Card title="Create a Session" href="/api-reference/sessions/create-a-session" icon="play">
+    Drive a Droid programmatically from your own systems
+  </Card>
+  <Card title="Manage Organization Users" href="/api-reference/organization/list-organization-users" icon="users-gear">
+    Invite, remove, and configure org members for admin workflows
+  </Card>
+</CardGroup>

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"
+                }
+              }
+            ]
           }
         ]
       }

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に <a href="https://app.factory.ai" target="_blank" rel="noreferrer" className="url-plain">app.factory.ai</a> でサインインします。
+2. <a href="https://app.factory.ai/settings/api-keys" target="_blank" rel="noreferrer" className="url-plain">app.factory.ai/settings/api-keys</a> を開きます。
+3. **Create API key** をクリックし、わかりやすい名前を付けて、値（`fk-` で始まる文字列）をコピーします。
+
+キーは一度だけ表示されます。シークレットマネージャーまたは環境変数に保存してください。パスワードと同様に扱い、ソース管理にコミットしたり、共有ログに貼り付けたりしないでください。
+
+```bash
+export FACTORY_API_KEY="fk-your-api-key"
+```
+
+![Factory APIキー設定画面](/images/web/api-keys-page.png)
+
+### 権限
+
+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` | 組織ユーザー、使用量上限、エンタープライズコントロール履歴の管理      |
+
+各グループのエンドポイントリファレンスは、左サイドバーから参照できます。
+
+---
+
+## 次のステップ
+
+<CardGroup cols={2}>
+  <Card title="コンピューター一覧" href="/jp/api-reference/computers/list-computers" icon="server">
+    組織内の既存のDroidコンピューター環境を確認します
+  </Card>
+  <Card title="セッションの作成" href="/jp/api-reference/sessions/create-a-session" icon="play">
+    ご自身のシステムからDroidをプログラム制御します
+  </Card>
+  <Card title="組織ユーザーの管理" href="/jp/api-reference/organization/list-organization-users" icon="users-gear">
+    管理者ワークフロー向けに組織メンバーを招待、削除、設定します
+  </Card>
+</CardGroup>

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;
+}