CoreDash Agency API: プロジェクトを管理し、アカウントを横断してデータを取得する

アカウント内のすべてのプロジェクトに1つのキーを

Agency APIは、多数のプロジェクトを管理するアカウント向けに提供されている。代理店、多数のブランドを運営する社内チーム、または新しいクライアントが加わるたびにダッシュボードにログインしたくないユーザーに最適である。一度マスターキーを発行すれば、その1つの認証情報でプロジェクトの作成、更新、削除を行い、すべてのプロジェクトのCore Web Vitalsデータを読み取ることができる。

プロジェクトごとのAPIをお探しの場合は、CoreDash APIページが、プロジェクトスコープのキーを持つ単一プロジェクトについて解説している。同じデータツールを使用しつつ、スコープが狭く、セットアップがよりシンプルである。

Agency APIは以下の2つの機能を提供する:

1. プロジェクトのCRUD: プロジェクトの作成、一覧表示、更新、削除を行うための、/api/agency/projectsにおける小規模なRESTサーフェス。
2. プロジェクトを横断したデータ読み取り: プロジェクト単位のAPIと同じJSON-RPCツール (get_metrics、get_timeseries、get_histogram) を/api/mcpで提供する。マスターキーを使用し、引数に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日間のトライアルとして開始される。トライアルの代わりに有料プラン（請求期間33日）で開始するには、agencyplanを渡すこと。

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: 1つのプロジェクトの取得

単一のプロジェクトドキュメントを返す。ユーザーがプロジェクトを所有していない場合は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: プロジェクトの物理削除 (hard-delete)

プロジェクトと、それに紐付くすべてのデータ（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) に変更はない。プロジェクト単位のフローとの唯一の違いは、API呼び出しでどのプロジェクトを参照するかを指定するために、arguments内にproject_idを渡す点である。各プロジェクトキーはすでに単一のプロジェクトにスコープされているため、プロジェクトキーではこの指定は不要である。マスターキーは多数のプロジェクトをカバーするため、リクエストでプロジェクトを1つ指定する必要がある。

例: 特定のプロジェクトの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ラッパーであり、解析されたペイロードは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. クライアントの名前とURLを含めてPOST /api/agency/projectsを実行する。レスポンスには新しい_idが含まれる。
3. その_idを含めたトラッキングスニペットをクライアントのサイトに埋め込む。
4. 同じマスターキーを使用し、引数に"project_id": "<the _id>"を指定してPOST /api/mcpを実行することで、いつでもそのプロジェクトのRUMデータを読み取る。個別のプロジェクトキーは必要ない。

これがオンボーディングループのすべてである。1つのキー、1回のPOST、1回のスニペット埋め込みだけで、新しいプロジェクトのデータをすぐにクエリできるようになる。

エラー

プロジェクトのCRUDエンドポイントは、プレーンなRESTステータスコードを返す:

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

レート制限

データを読み取る際、プロジェクトごとの1日の制限は引き続き適用される。マスターキーを使用してプロジェクトAのget_metricsを呼び出すと、プロジェクトAの1日のクォータとしてカウントされ、プロジェクトBへの呼び出しはプロジェクトBのクォータとしてカウントされる。CoreDash APIページのレート制限の表を参照してほしい。プロジェクトのCRUD呼び出しは、同じようにはレート制限されない。