APIエンドポイント

Zenovayは、アナリティクスデータにプログラムからアクセスするための複数のAPIエンドポイントグループを提供しています。

認証

すべてのAPIリクエストには認証が必要です。方法は使用するAPIによって異なります：

詳細はAPIキー管理に関する認証を参照してください。

External API

Base URL： https://api.zenovay.com/api/external/v1

APIキー認証（X-API-Keyヘッダー）でアナリティクスデータにアクセスするためのサーバーサイドAPI。

利用可能なエンドポイント

各エンドポイントには、パラメータ、レスポンススキーマ、TypeScriptインターフェース、およびcURL、JavaScript、Python、TypeScriptのコード例を含む詳細なリファレンスページがあります。

高レベルの導入については、External API概要も参照してください。

埋め込み可能ウィジェット

Base URL： https://api.zenovay.com/widgets

認証不要な利用可能なウィジェット。トラッキングコードを使用してウェブサイトを識別します。

埋め込み例についてはウィジェットを参照してください。

リアルタイムデータ

Base URL： https://api.zenovay.com/e

ライブ統計のためのパブリックJSONエンドポイント。認証は不要です。

統合ガイドについてはリアルタイムデータを参照してください。

レート制限

APIレート制限はプランによって異なります：

レート制限ヘッダーはすべてのレスポンスに含まれます：

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1642771200

X-RateLimit-Limit値はあなたのプランの1分あたりの制限を反映しています（例：Free は10、Pro は30、Scale は60、Enterprise は120）。

レート制限エラーの処理の詳細についてはレート制限を参照してください。

エラーコード

{
"success": true,
"data": { ... },
"timestamp": "2026-02-07T12:00:00.000Z"
}

{
"success": false,
"error": {
  "message": "The provided API key is missing or invalid",
  "code": "UNAUTHORIZED",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}

ウェブフック

リアルタイム通知を受け取るためにウェブフックを設定します：

利用可能なイベント

• visitor.identified - 訪問者が識別されたとき
• visitor.high_value - 訪問者スコアが80以上に達したとき
• event.tracked - イベントが追跡されたとき
• goal.completed - 目標が達成されたとき
• visitor.converted - 訪問者がコンバージョンしたとき

ウェブフックペイロード

{
"event": "visitor.high_value",
"timestamp": "2025-01-20T15:30:00Z",
"data": {
  "visitor_id": "vis_abc123",
  "score": 92,
  "current_page": "/pricing",
  "time_on_site": 420
}
}

ダッシュボードAPI概要

以下のAPIグループがZenovayダッシュボードを動作させています。すべてのエンドポイントはAuthorizationヘッダーにBearer JWTトークンが必要です。レスポンスは標準的なエンベロープを使用します：

{ "success": true, "data": { ... }, "timestamp": "..." }

ロールベースの権限

ウェブサイト設定エンドポイントはロールベースのアクセス制御を実行します。ロールは権限順にリスト化されています：

会話API

Base URL： https://api.zenovay.com/api/conversations

認証： Bearer JWT が必須。すべてのリクエストでチームメンバーシップを検証。

チーム内のAI駆動型会話用のCRUD操作。team_idクエリパラメータが指定されない場合、認証されたユーザーの組織にデフォルト設定されます。

エンドポイント

GET /conversations

パフォーマンスのためにメッセージコンテンツなしで会話を返します。

クエリパラメータ：

• team_id（オプション）— ユーザーの組織にデフォルト設定

{
"success": true,
"data": [
  {
    "id": "uuid",
    "team_id": "uuid",
    "title": "Analytics Q3 review",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-07T14:30:00Z"
  }
]
}

GET /conversations/:id

メッセージ配列を含む完全な会話を返します。

{
"success": true,
"data": {
  "id": "uuid",
  "team_id": "uuid",
  "title": "Analytics Q3 review",
  "messages": [
    { "role": "user", "content": "Show top pages", "timestamp": "2026-02-07T14:30:00Z" },
    { "role": "assistant", "content": "Here are your top pages...", "timestamp": "2026-02-07T14:30:01Z" }
  ],
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:30:01Z"
}
}

POST /conversations

{
"title": "New conversation",
"team_id": "uuid"
}

• title（必須）— 空でない文字列
• team_id（オプション）— ユーザーの組織にデフォルト設定

レスポンス： 201で作成した会話を返します（空のmessages: []を含む）。

PUT /conversations/:id

{
"title": "Updated title",
"messages": [...]
}

両方のフィールドはオプション。部分更新を受け入れます。

DELETE /conversations/:id

レスポンス： 200で{ "deleted": true }を返す。

POST /conversations/:id/messages

メッセージを会話に追加します。サーバーは各メッセージにtimestampを追加します。

{
"role": "user",
"content": "What were last week's top referrers?"
}

• role（必須）— メッセージロール（例："user"、"assistant"）
• content（必須）— メッセージテキスト

レスポンス： 201で、すべてのメッセージを含む完全に更新された会話を返します。

ウェブサイト設定API

Base URL： https://api.zenovay.com/api/websites

認証： Bearer JWT が必須。各エンドポイントは最小ロールを適用します。

一般設定、通知、トラフィック除外、収益追跡、ドメイン、チームメンバーを含むウェブサイト設定を管理します。すべてのパスは:websiteIdでスコープされます。

エンドポイント

PUT /:websiteId/general

{
"domain": "example.com",
"name": "My Website",
"timezone": "America/New_York",
"primary_color": "#4F46E5",
"kpi_goal": 10000,
"public_dashboard": true,
"allowed_domains": ["example.com", "www.example.com"]
}

{
"success": true,
"data": {
  "id": "uuid",
  "domain": "example.com",
  "name": "My Website",
  "timezone": "America/New_York",
  "primary_color": "#4F46E5",
  "kpi_goal": 10000,
  "public_dashboard": true,
  "allowed_domains": ["example.com", "www.example.com"],
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/notifications

通知設定を返します。何も設定されていない場合、website_idのみを含むデフォルトオブジェクトを返します。

PUT /:websiteId/notifications

任意の通知設定フィールドを受け入れます。upsertパターンを使用します：最初のコールでレコードを作成し、その後のコールで更新します。

GET /:websiteId/exclusions

IPとパス除外の両方を単一レスポンスで返します。

{
"success": true,
"data": {
  "ip_exclusions": [
    { "id": "uuid", "website_id": "uuid", "ip_address": "192.168.1.1", "description": "Office IP", "created_at": "..." }
  ],
  "path_exclusions": [
    { "id": "uuid", "website_id": "uuid", "path_pattern": "/admin/*", "description": "Admin pages", "created_at": "..." }
  ]
}
}

POST /:websiteId/exclusions/ip

{
"ip_address": "192.168.1.1",
"description": "Office IP"
}

• ip_address（必須）
• description（オプション）

レスポンス： 201。IPが既に除外されている場合は409を返します。

POST /:websiteId/exclusions/path

{
"path_pattern": "/admin/*",
"description": "Admin pages"
}

• path_pattern（必須）
• description（オプション）

レスポンス： 201。パスパターンが既に除外されている場合は409を返します。

PUT /:websiteId/revenue

adminロールが必須です。

{
"revenue_provider": "stripe",
"revenue_currency": "USD"
}

{
"success": true,
"data": {
  "id": "uuid",
  "revenue_provider": "stripe",
  "revenue_currency": "USD",
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/domains

{
"success": true,
"data": {
  "primary_domain": "example.com",
  "allowed_domains": ["example.com", "www.example.com"],
  "verification_status": "verified"
}
}

PUT /:websiteId/domains

adminロールが必須です。

{
"domain": "example.com",
"allowed_domains": ["example.com", "www.example.com"]
}

提供される場合、allowed_domainsは配列である必要があります。

GET /:websiteId/team-members

ユーザープロファイルデータで拡張されたチームメンバーを返します。

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "deactivated_at": null,
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "avatar_url": "https://..."
    }
  }
]
}

POST /:websiteId/team-members

メールでユーザーを招待します。adminロールが必須です。

{
"email": "[email protected]",
"role": "editor"
}

• email（必須）— 登録済みのZenovayユーザーである必要があります
• role（オプション）— デフォルトは"viewer"。以下のいずれかである必要があります：owner、admin、editor、viewer

レスポンス： 201。メールが見つからない場合は404、既にメンバーの場合は409を返します。

PUT /:websiteId/team-members/:memberId

メンバーのロールを更新します。adminロールが必須です。

{
"role": "admin"
}

• role（必須）— 以下のいずれかである必要があります：owner、admin、editor、viewer

DELETE /:websiteId/team-members/:memberId

チームメンバーを削除します（ソフト削除）。adminロールが必須です。

レスポンス： 200で{ "deleted": true }を返す。

オンボーディングAPI

Base URL： https://api.zenovay.com/api/onboarding

認証： Bearer JWT が必須。ユーザースコープ（チームやロールチェックなし）。

ユーザーのオンボーディング進捗を追跡します。各ユーザーは、セッション間で永続する単一のオンボーディングレコードを持ちます。

エンドポイント

GET /onboarding/progress

ユーザーのオンボーディング状態を返します。レコードが存在しない場合、デフォルトを返します。

{
"success": true,
"data": {
  "user_id": "uuid",
  "current_step": "add_website",
  "completed": false,
  "data": { "welcomed": true },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:00:00Z"
}
}

POST /onboarding/progress

upsertパターンを使用します：最初のコールでレコードを作成し、その後のコールで更新します。

{
"step": "install_tracking",
"data": { "welcomed": true, "website_added": true },
"completed": false
}

• step — データベースでcurrent_stepとして保存
• data — ステップ固有の状態を保存するための任意のJSONオブジェクト
• completed — デフォルトはfalse

チームAPI

Base URL： https://api.zenovay.com/api/teams

認証： Bearer JWT が必須。チームメンバーシップを検証（任意のアクティブメンバーがアクセス可能）。

権限、使用統計、メンバーリストのための読み取り専用チームコンテキストエンドポイント。チーム管理操作（招待、ロール変更、削除）については、ウェブサイト設定APIのチームメンバーエンドポイントを使用します。

エンドポイント

GET /teams/:id/permissions

認証されたユーザーのロール、チームのプラン、現在の使用数、および計算された権限フラグを返します。

{
"success": true,
"data": {
  "team_id": "uuid",
  "role": "admin",
  "plan": "Pro",
  "plan_limits": {
    "maxWebsites": 5,
    "maxTeamMembers": 5,
    "eventsPerMonth": 10000,
    "dataRetentionDays": 730
  },
  "current_usage": {
    "websites": 3,
    "team_members": 5
  },
  "permissions": {
    "can_manage_billing": false,
    "can_manage_team": true,
    "can_edit_settings": true,
    "can_view": true
  }
}
}

GET /teams/:id/usage

現在の請求期間（月の途中まで）の使用統計を返します。

{
"success": true,
"data": {
  "team_id": "uuid",
  "plan": "Pro",
  "period": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-02-07T12:00:00.000Z"
  },
  "usage": {
    "events": 4521,
    "events_limit": 10000,
    "websites": 3,
    "websites_limit": 10,
    "team_members": 5,
    "team_members_limit": 10
  }
}
}

GET /teams/:id/members

ユーザープロファイルデータで拡張されたチームメンバーを返します。

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "name": "Jane",
      "avatar_url": "https://..."
    }
  }
]
}

ユーザープロフィールAPI

Base URL： https://api.zenovay.com/api/users

認証： Bearer JWT が必須。ユーザースコープ（自分のプロフィールのみ）。

認証されたユーザーのプロフィールとメールアドレスを管理します。

エンドポイント

PUT /users/me/email

SSOプロバイダー検出を伴うメール変更用の専用エンドポイント。ユーザーがOAuthプロバイダー（Google、GitHubなど）経由でサインアップした場合、リクエストは代わりにそのプロバイダーを通じてメールを更新するというメッセージで拒否されます。

{
"email": "[email protected]"
}

• email（必須）— 有効なメール、現在のものと異なるもの

レスポンス： 200で更新されたユーザーレコード。ユーザーがSSOアカウントの場合またはメールが無効/変更なしの場合は400を返します。

次のステップ

• External API - APIキー認証を使用したサーバーサイドアナリティクス
• ウィジェット - 事前構築された埋め込み可能ウィジェット
• リアルタイムデータ - ライブ訪問者データエンドポイント
• 認証 - APIキー管理
• レート制限 - 制限の理解