CoreDash Agency API：プロジェクトの管理とアカウント間でのデータ取得

アカウント内の全プロジェクトに対応する1つのキー

Agency APIは、多数のプロジェクトを管理するアカウント向けです。代理店、複数のブランドを運営するインハウスチーム、新しいクライアントが増えるたびにダッシュボードへログインしたくないユーザーなどに適しています。マスターキーを一度発行すれば、その1つの認証情報だけで、プロジェクトの作成、更新、削除、およびすべてのプロジェクトを横断したCore Web Vitalsデータの取得が可能です。

プロジェクトごとのAPIをお探しですか？CoreDash APIページでは、プロジェクトスコープのキーを使用した単一プロジェクト向けの機能について解説しています。データツールは同じですが、スコープが限定されており、よりシンプルな設定で利用できます。

Agency APIは、次の2つの機能を提供します。

1. プロジェクトのCRUD：/api/agency/projectsにある小さなRESTインターフェースで、プロジェクトの作成、一覧表示、更新、削除を行います。
2. プロジェクトを横断したデータの取得：/api/mcpにある、プロジェクトごとのAPIと共通 of JSON-RPCツール（get_metrics、get_timeseries、get_histogram）を使用します。マスターキーを使用する場合は、引数にproject_idを渡して対象のプロジェクトを指定します。

2種類のAPIキー

CoreDashは2つの階層のキーを発行します。それぞれ役割が異なります。

マスターキーは、代理店（agency）フラグが設定されたアカウントでのみ利用可能です。以下で説明する「Agency API」タブが表示されない場合は、サポートにお問い合わせください。

マスターキーの取得

マスターキーはAPI経由ではなく、Web UIから発行します。

1. app.coredash.appにログインします。
2. 「My Account」を開き、「Agency API」タブをクリックします。
3. 「Generate master key」をクリックして名前を設定し、値をコピーします。値は一度しか表示されません。

キーはcdk_master_で始まります。このキーの保持者は、ユーザーアカウントに属するすべてのプロジェクトの管理、およびそれらのプロジェクトのデータの読み取りが可能になります。パスワードと同様に扱ってください。不要になったマスターキーは、同じタブからいつでも無効化できます。

認証

Agency APIへのリクエストには、Authorizationヘッダーにマスターキーを含める必要があります。

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

REST形式のプロジェクトCRUDエンドポイントと、JSON-RPC形式のデータエンドポイントの両方で同じヘッダーを使用できます。その他の変更点はありません。

プロジェクトCRUD：RESTインターフェース

プロジェクト管理のベースURL：

https://app.coredash.app/api/agency/projects

これらは通常のRESTコールです。JSON-RPCではありません。

POST /api/agency/projects：プロジェクトの作成

マスターキーの所有ユーザーに紐づく新規プロジェクトを作成します。デフォルトでは10日間のトライアルとして開始されますが、agencyplanを渡すことで、33日間の請求周期を持つ有料プランでプロジェクトを開始することも可能です。

curl -X POST https://app.coredash.app/api/agency/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY" \
  -d '{
    "name": "Acme client",
    "url": "https://acme.example",
    "agencyplan": "starter"
  }'

成功時のレスポンスは201です。

{
  "status": 201,
  "project": {
    "_id": "655f1f77bcf86cd799439011",
    "name": "Acme client",
    "url": "https://acme.example",
    "status": "paid",
    "users": ["644..."],
    "expires": "2026-06-28T12:00:00.000Z",
    "alerts": { "ai": true },
    "created": { "date": "2026-05-26T12:00:00.000Z" }
  }
}

この_idは、クライアントのサイトに埋め込む追跡スニペットに設定する値です。また、後述のデータツールに渡すproject_idとしても使用します。

GET /api/agency/projects：プロジェクトの一覧表示

ユーザーが所有するプロジェクトを、作成日時が新しい順に返します。limit（最大500、デフォルト100）とoffsetによるページネーションに対応しています。

curl "https://app.coredash.app/api/agency/projects?limit=50" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"

{
  "status": 200,
  "projects": [
    { "_id": "...", "name": "Acme client", "url": "https://acme.example", "status": "paid" },
    { "_id": "...", "name": "Beta client", "url": "https://beta.example", "status": "trial" }
  ]
}

GET /api/agency/projects/:id：単一プロジェクトの取得

単一のプロジェクトドキュメントを返します。ユーザーがそのプロジェクトを所有していない場合は404を返します。アカウント間でプロジェクトIDが推測・列挙されるのを防ぐため、「存在しない」と「所有していない」を意図的に区別していません。

curl https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"

PATCH /api/agency/projects/:id：名前またはURLの更新

nameまたはurlを更新します。両フィールドともオプションであり、省略されたフィールドは変更されません。リクエストボディに含まれるその他の情報は無視されます。ステータス、請求、有効期限、およびアラートはダッシュボードから管理してください。

curl -X PATCH https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY" \
  -d '{ "name": "Acme client renamed" }'

DELETE /api/agency/projects/:id：プロジェクトの完全削除

プロジェクトと、それに紐づくすべてのデータ（Lighthouseの実行結果、CrUXデータ、アラート、スナップショット、およびスナップショットの設定）を削除します。

バックエンドのデータストアにあるRUMデータは、このコールでは削除されません。古いプロジェクトIDに紐づいたまま残りますが、孤立したデータとなります。復旧方法はなく、そのプロジェクトIDは廃止されます。

curl -X DELETE https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"

{ "status": 200, "deleted": true }

マスターキーを使用したデータの読み取り

プロジェクトのCore Web Vitalsデータを取得するには、プロジェクトごとのAPIで使用するものと同じJSON-RPCエンドポイントを呼び出します。

https://app.coredash.app/api/mcp

利用する3つのツール（get_metrics、get_timeseries、get_histogram）に変更はありません。プロジェクトごとのフローとの唯一の違いは、対象のプロジェクトを特定するために、argumentsの中にproject_idを渡す必要がある点です。プロジェクトキーはすでに特定のプロジェクトにスコープされているためこの指定は不要ですが、マスターキーは複数のプロジェクトをカバーするため、リクエストごとにプロジェクトを指定する必要があります。

例：特定プロジェクトのget_metrics実行

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {
        "project_id": "655f1f77bcf86cd799439011",
        "metrics": "LCP,INP,CLS",
        "date": "-7d"
      }
    }
  }'

レスポンスはプロジェクトごとのAPIと同じJSON-RPCラッパーであり、パースされたpayloadはresult.content[0].textに含まれます。内部JSONの構造、distributionオブジェクト、時系列データのsummaryフィールド、ヒストグラムのバケット構造などはすべて、プロジェクトキーを使用した場合とまったく同じ挙動になります。唯一追加で必要となるのは、project_id引数だけです。

get_timeseriesとget_histogramについても同様です。project_idを渡してから、通常の引数を指定してください。

その他のパラメータ（filters、group、percentile、date、granularityなど）もすべて同様に機能します。ディメンションのリファレンス（d、cc、ff、lcpel、inpelなどすべて）、メトリクスのしきい値、パーセンタイルの仕様については、CoreDash APIページに記載されています。パラメータとディメンションの全仕様については、そちらを参照してください。このページでは、マスターキーで認証する場合の相違点のみを説明しています。

新規クライアントプロジェクトのオンボーディング

代理店が新規クライアントを追加する際の大まかな流れは以下の通りです。

1. My Account → Agency APIタブでマスターキーを一度だけ発行し、安全に保管します。
2. POST /api/agency/projectsをクライアントの名前とURLを指定して呼び出します。レスポンスに新しい_idが含まれています。
3. その_idを使用して、クライアントのサイトに追跡スニペットを埋め込みます。
4. 同じマスターキーを使用し、引数に"project_id": "<取得した_id>"を指定してPOST /api/mcpを呼び出すことで、いつでもプロジェクトのRUMデータを読み取ることができます。個別のプロジェクトキーは不要です。

オンボーディングの流れは以上です。1つのキー、1つのPOSTリクエスト、1つのスニペット埋め込みだけで、新しいプロジェクトのデータをすぐにクエリできます。

エラー

プロジェクトCRUDのエンドポイントは、通常のRESTステータスコードを返します。

/api/mcpでのデータの読み取りでは、プロジェクトキーを使用する場合と同様に、JSON-RPCエラーオブジェクトが返されます。エラーコードの対応表はCoreDash APIページに記載されています。もし-32001が発生した場合は、キーがcdk_master_で始まっていること、および引数にproject_idが含まれていることを再確認してください。

レート制限

データを読み取る際、プロジェクトごとの日次上限は引き続き適用されます。マスターキーを使用してプロジェクトAのget_metricsを呼び出すとプロジェクトAの1日の割り当て量が消費され、プロジェクトBの呼び出しはプロジェクトBの割り当て量としてカウントされます。詳細はCoreDash APIページのレート制限表を参照してください。プロジェクトCRUDの呼び出しには、このようなレート制限は適用されません。