---

title: "チャートアノテーションAPI" description: "デプロイ / リリース / キャンペーンのアノテーションを作成し、Zenovayの時系列チャート上に重ね、F8コンバージョンインシデントの分析にも活用します。"

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

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

認証: このエンドポイントはダッシュボードのセッションCookieを受け付けます。 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>xxxxxxxxxxxxxxxxxxxxx

{
  "websiteId": "11111111-2222-3333-4444-555555555555",
  "type": "deploy",
  "message": "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": "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パイプラインからデプロイマーカーを作成

curl -X POST https://api.zenovay.com/api/annotations \
  -H "Authorization: Bearer $ZENOVAY_API_KEY" \
  -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 annotation create --type=deploy --message="release v2.5"

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

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

エラー