> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# API モジュール

バージョン管理された公開コントラクト、キー配管、OpenAPI サーフェス。

## 始める前に

[ファイル] → [フォルダーを開く] を使用して、Visual Studio Code でダウンロードした supastack プロジェクトを開き、[ターミナル] → [新しいターミナル] を選択します。リポジトリ ルートは、package.json、アプリ、およびパッケージを含むフォルダーです。そこで以下のコマンドを実行し、ターミナルを開いたままにしておきます。コマンドが認識されない場合は、続行する前にツールのインストール ガイドを完了してください。

まずプラットフォームのチュートリアルをお読みください。サーバーは、ブラウザまたは電話のリクエストに応答するアプリ プロセスです。 Web は apps/web/.env.local を読み取り、Expo は apps/mobile/.env.local を読み取り、データベース移行コマンドは root .env を読み取ります。データベースなしの /dashboard デモは、Postgres の移行が必要な実際の /auth アカウントとは別のものです。電話またはデスクトップのみのチェックアウトには、別途実行される Web バックエンドが必要です。

[ツールをインストールしてコードを取得](https://supastack.dev/ja/docs/web/before-you-start.md)

[コマンド、ファイル、設定を学ぶ](https://supastack.dev/ja/docs/web/terminal-basics.md)

[Web の初回実行チュートリアルを完了する](https://supastack.dev/ja/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## インストールとセットアップ

packages/api は公開 REST サーフェスの信頼できる情報源です: リクエスト、レスポンス、エラーエンベロープの zod スキーマ、加えて /api/v1/openapi で配信される OpenAPI ドキュメント(openApiDocument)。ルートハンドラーは形状を再定義するのではなくこれらのスキーマを組み立てます。

API キーはワークスペースごとに sk_<env>_ プレフィックス付きで発行され、定数時間比較のハッシュで保存され、スコープ(デフォルトは読み取り)を持ちます。api-keys.ts が作成・検索・失効を所有します。

```
apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi
```


## 実装ワークフロー

既存バージョン内でエンドポイントを追加します: スキーマを拡張し、エラーエンベロープを維持し、OpenAPI サーフェスを再生成して /api/docs の正確さを保ちます。破壊的変更は静かな形状変更ではなく新バージョンを取得します。

提示されたキーから呼び出し元のワークスペースを解決し、Web アプリと同じエンタイトルメント・検証ルールを適用し、キーごとにレート制限します。


## 検証とトラブルシューティング

各ルート形状をパッケージスキーマに対してコントラクトテストします。不明・失効・スコープ不足のリクエストがすべて文書化されたエラーエンベロープで失敗すること、OpenAPI ドキュメントが有効な JSON のままであることを確認します。


## 次へ

[レート制限](https://supastack.dev/ja/docs/modules/rate-limiting.md)