チャートアノテーション API

顧客が作成するアノテーション（デプロイ、リリース、キャンペーン、インシデント、カスタム）は、Zenovay ダッシュボードのすべての時系列チャート上に重ねて表示されます。また、コンバージョンインシデント分析でも、インシデント発生時点の±2 時間以内にあるアノテーションは「疑わしい変更」として参照されます。

認証: このエンドポイントはダッシュボードのセッションクッキーを受け付けます。CI 連携や自動化には、アカウントログイン経由で認証を扱う Zenovay CLI を使用してください。外部の zv_* API キーは現時点でこのエンドポイントでは受け付けていません。デプロイパイプラインからアノテーションを作成する推奨手段は CLI です。

プラン上限: Free = 月 10 件のアノテーション。Pro 以上 = 無制限。

重複防止: 既存のアノテーションから 5 分以内に同じ type のアノテーションを作成しようとすると 409 Conflict で拒否されます。設定ミスのある CI によるタイムラインのスパムを防ぎます。

アノテーションを作成

POST /api/annotations
Content-Type: application/json
Cookie: zenovay-session=<your-session-cookie>

{
  "websiteId": "11111111-2222-3333-4444-555555555555",
  "type": "deploy",
  "message": "Ship checkout v2.5",
  "occurredAt": "2026-04-30T14:00:00Z",
  "metadata": { "sha": "a1b2c3d", "branch": "main" }
}

フィールド

レスポンス

{
  "success": true,
  "data": {
    "annotation": {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "website_id": "11111111-2222-3333-4444-555555555555",
      "team_id": "...",
      "type": "deploy",
      "message": "Ship checkout v2.5",
      "occurred_at": "2026-04-30T14:00:00Z",
      "created_by": "...",
      "metadata_json": { "sha": "a1b2c3d", "branch": "main" },
      "created_at": "2026-04-30T14:00:01Z"
    }
  }
}

アノテーションを一覧表示

GET /api/annotations?websiteId=<uuid>&from=<iso>&to=<iso>
Cookie: zenovay-session=<your-session-cookie>

from と to は省略可能です。指定した期間内で最大 500 件のアノテーションを新しい順に返します。

アノテーションを削除

DELETE /api/annotations/<annotation-id>
Cookie: zenovay-session=<your-session-cookie>

成功時は { deleted: true } を返します。v1 ではソフト削除は未対応で、削除は永続的です。

よくあるパターン

CI パイプラインからデプロイマーカーを作成

CI パイプラインには Zenovay CLI を使用してください。セッションクッキーを使用した curl のアプローチは、自動化された環境では実用的ではありません。以下の CLI の例を参照してください。

有効なセッションクッキーを既に持っているサーバーから生の HTTP 呼び出しが必要な場合、リクエストは次のようになります。

curl -X POST https://api.zenovay.com/api/annotations \
  -H "Cookie: zenovay-session=$ZENOVAY_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d "{
    \"websiteId\": \"$WEBSITE_ID\",
    \"type\": \"deploy\",
    \"message\": \"Deploy $GIT_BRANCH @ $GIT_SHA\",
    \"metadata\": { \"sha\": \"$GIT_SHA\", \"branch\": \"$GIT_BRANCH\" }
  }"

Zenovay CLI から

Zenovay CLI は CI パイプラインからアノテーションを作成するための推奨手段です。OAuth デバイスフロー ログイン経由で認証を自動的に処理します。

zenovay annotation create --type=deploy --message="release v2.5"

フラグの完全なセット：

完全なコマンドリファレンスとサンプル GitHub Actions ステップについては、CLI 統合ページ をご覧ください。

アノテーションが表示される場所

• ダッシュボードのすべての時系列チャート（垂直リファレンスライン + 浮動レジェンドの色付きチップ）。
• コンバージョンインシデント分析 — インシデント発生時点の±2 時間以内に存在するアノテーションは自動的に「疑わしい変更」として一覧されます。
• 公開ダッシュボード — アノテーションは公開ダッシュボードには表示されません。デプロイおよびリリースのメッセージはサイトを運営するチーム向けの情報であり、訪問者向けではありません。

エラー