メインコンテンツまでスキップ

GET /wp-json/qa-platform/guide

ディスカバリエンドポイント。新しいクライアントセッションのたびに 最初に 呼んでください。このサーバーに対して QAL クエリを組み立てるのに必要なものをすべて返します: バージョンと update メタデータ、(since タグ付き) 機能フラグ、認証ユーザーがクエリ可能な tracking_id 一覧、サイトごとのゴール定義、現在有効な機械可読仕様書。

リクエスト​

GET /wp-json/qa-platform/guide?version=2026-05-11
Authorization: Basic <base64 user:app_password>

クエリパラメータ​

パラメータ型必須説明
versionstringいいえAPI バージョン。サーバー上の最新をデフォルトに。latest または YYYY-MM-DD。

レスポンスの形​

{
  "version": "2026-05-11",
  "api_update": "2026-05-11",
  "timestamp": "2026-05-11T08:30:00Z",
  "plugin_version": "3.0.0.0",

  "features": {
    "filter":                true,
    "join":                  true,
    "calc":                  true,
    "view_chaining":         true,
    "sort":                  true,
    "allpv_prev_next_page":  true,
    "materials_supports_all": true,
    "calc_join_symmetric":   true,
    "sample":                false,
    "include_count":         false,
    "return_file":           false,
    "return_csv":            false,
    "return_parquet":        false
  },

  "features_detail": {
    "filter":                { "enabled": true,  "since": "2025-10-20" },
    "join":                  { "enabled": true,  "since": "2025-10-20" },
    "calc":                  { "enabled": true,  "since": "2025-10-20" },
    "view_chaining":         { "enabled": true,  "since": "2025-10-20" },
    "sort":                  { "enabled": true,  "since": "2025-10-20" },
    "allpv_prev_next_page":  { "enabled": true,  "since": "2026-04-17" },
    "materials_supports_all":{ "enabled": true,  "since": "2026-04-29" },
    "calc_join_symmetric":   { "enabled": true,  "since": "2026-05-11" },
    "sample":                { "enabled": false },
    "include_count":         { "enabled": false },
    "return_file":           { "enabled": false },
    "return_csv":            { "enabled": false },
    "return_parquet":        { "enabled": false }
  },

  "sites": [
    {
      "tracking_id": "abc123",
      "domain": "example.com",
      "name": "コーポレートサイト",
      "default": true,
      "data_available_from": "2024-01-01",
      "timezone": "Asia/Tokyo",
      "goals": [
        {
          "id": 1,
          "name": "お問い合わせ送信",
          "type": "gtype_page",
          "condition": { "url": "/thanks/", "match": "exact" }
        }
      ]
    }
  ],

  "documentation": {
    "source": "https://github.com/quarka-org/docs.qazero.com/tree/main/docs/developer-manual/api/2026-05-11/ai",
    "format": "mixed",
    "sections": [
      {
        "category": "instructions",
        "format":   "markdown",
        "file":     "README.md",
        "title":    "AI Instructions (how to build a QAL query)",
        "content":  "..."
      },
      {
        "category": "spec",
        "format":   "yaml",
        "file":     "materials.yaml",
        "title":    "Materials Manifest (machine-readable)",
        "content":  "..."
      },
      {
        "category": "spec",
        "format":   "yaml",
        "file":     "qal-validation.yaml",
        "title":    "QAL Validation Manifest (machine-readable)",
        "content":  "..."
      }
    ]
  }
}

フィールド一覧​

フィールド意味
versionAPI バージョン (URL に現れる、破壊的変更時計)
api_updateUpdate 日付 (非破壊追加時計)。since と比較する
timestampレスポンスが生成されたサーバー時刻
plugin_versionサーバーの QA ZERO プラグインバージョン
featuresフラット {name: bool} マップ。後方互換形式
features_detailリッチ {name: {enabled, since?}} マップ。since チェックにはこちらを使う
sites[]認証ユーザーがアクセスできる tracking_id ごとのエントリ
sites[].goals[]サイトごとのゴール定義 — goal_N マテリアルがどのゴールを意味するかのマッピング
documentation.sectionsAI クライアントに配信される現行仕様。README.md は markdown、2本の .yaml は正式なスキーマ

各マテリアルの supports_all フラグ​

materials.yaml 内の各マテリアルには、そのマテリアルが tracking_id: "all"（全サイト集約）でクエリできるかどうかを宣言する supports_all: true | false フラグが付いています。ユーザーに「全サイト」スコープを選ばせる場面で、どのマテリアルを提示するか判断するときは、documentation.sections 内の materials.yaml ブロックからこのフラグを読み取ってください。Since: 2026-04-29

materials:
  allpv:
    dataset_id: 1
    supports_all: true     # 全サイト集約は夜間バッチで生成される
    decoders: ...
  click_event:
    dataset_id: 2
    supports_all: true
    decoders: ...
  gsc:
    dataset_id: 4
    supports_all: false    # サイト別専用 — 実在の tracking_id が必須
    decoders: ...

features.materials_supports_all = true を返すサーバー（つまり api_update >= 2026-04-29）は、すべてのマテリアルに supports_all を設定することが保証されます。旧バージョンのサーバーはフラグを完全に省略する可能性があります。フラグ非存在時は「不明 — クエリを投げてエラーで判定する」扱いにしてください。

キャッシュ​

サーバーはあるバージョンについて /guide が最初に呼ばれたときに、GitHub から ai/ サブディレクトリをローカルキャッシュします。以降の呼び出しはローカルキャッシュから読まれます。ドキュメントソースを変更してキャッシュを無効化したい場合は、サーバー上のキャッシュディレクトリを削除してください (wp-content/qa-zero-data/restapi/ 以下にあります)。

典型的なクライアントフロー​

  1. 起動時、pin した version で /guide を呼ぶ。
  2. api_update と features_detail を記録。
  3. documentation.sections をパース — file 名で2本の YAML ブロックを拾って、パースしてメモリにキャッシュ。
  4. YAML 仕様書を使って以降の /query 呼び出しを組み立てる。
  5. /query が E_UNKNOWN_* で失敗したら、/guide をもう一度呼ぶ — 最後にキャッシュした時から仕様が動いている可能性があるため。

次に読むページ​