ドキュメント／スタンダードプランの機能

APIリファレンス（v1）

自社のシステムやスクリプトから、カルテと処方を読み書きするためのREST APIです。AIツールから使う場合は MCP連携の方が簡単です。

基本

項目	内容
ベースURL	`https://kensakukarte.kotoformlabs.com/api/v1`
形式	リクエスト・レスポンスともJSON（UTF-8）。本文を送るときは `Content-Type: application/json`
日付	週は月曜日の `YYYY-MM-DD`。日時は UTC の ISO 8601 か `YYYY-MM-DD HH:MM:SS`（UTC）
数値	クリック・表示回数は整数。順位は小数1桁。CTR は `ctr_percent`（%）
データの期間	カルテの数値は対象週（月〜日）。処方と「あと少しで1ページ目」は直近28日
ブラウザから	利用できません（CORSに対応していません）。サーバー側から呼んでください

認証

すべてのリクエストに、設定で発行したAPIキーを付けます。

curl -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  https://kensakukarte.kotoformlabs.com/api/v1/sites

キーは環境変数やシークレット管理に入れ、コードに直接書かないでください。
権限：読み取りのみ はGETだけ。読み取りと対応状況の変更 はPATCH・POSTも使えます。
有効期限が切れたキーは 401 key_expired になります。
使えるIPアドレスを限定できます（キーを発行したあと、設定のキーごとに、IPまたはCIDRを10件まで追加）。限定したキーを他のIPから使うと 403 ip_not_allowed になります。サーバーから呼ぶなら、そのサーバーのIPに限定してください。
AIアプリ用の接続（Googleログインで許可したもの）の鍵はMCP専用で、REST APIでは使えません。

エラー

エラーは次の形で返します。message は日本語の説明です。

{
  "error": {
    "code": "not_found",
    "message": "処方が見つかりません。"
  }
}

HTTP	code	意味
400	bad_request	パラメータや本文の誤り
400	cannot_check	ページを点検できない（ページを読めない、点検の対象外の処方）
401	unauthorized	キーがない・誤り・削除済み
401	key_expired	キーの有効期限切れ
403	plan_required	スタンダードプラン以外のアカウント
403	insufficient_scope	読み取り専用キーで変更しようとした
403	forbidden_origin	ブラウザの別サイトからの呼び出し
403	ip_not_allowed	キーに許可していないIPアドレスからの呼び出し
404	not_found	サイト・カルテ・処方がない（他の人のものも、存在しないものとして扱います）
413	too_large	本文が64KBを超えた
429	rate_limited	回数制限を超えた
500	internal	サーバーのエラー

回数制限

1キーあたり1分120回
ページの点検し直し（recheck）は、1アカウントあたり10分30回
超えると 429。少し待ってからやり直してください

サイト

GET /sites　権限：読み取り

連携しているサイトの一覧。

リクエスト例

curl -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  https://kensakukarte.kotoformlabs.com/api/v1/sites

レスポンス例

{
  "sites": [
    {
      "id": 3,
      "property": "https://example.com/",
      "latest_week": "2026-11-02"
    }
  ]
}

カルテ

GET /sites/{id}/karte　権限：読み取り

週次カルテ。週を省くと最新。

パラメータ	内容
`week`	任意。対象週の月曜日 YYYY-MM-DD

リクエスト例

curl -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  "https://kensakukarte.kotoformlabs.com/api/v1/sites/3/karte?week=2026-11-02"

レスポンス例

{
  "site_id": 3,
  "property": "https://example.com/",
  "week": {
    "start": "2026-11-02",
    "note": "月曜はじまりの1週間（Search Consoleで確定済みの直近の週）"
  },
  "totals": {
    "clicks": 812,
    "impressions": 38120,
    "ctr_percent": 2.1,
    "position": 7.4
  },
  "previous_week": {
    "clicks": 725,
    "impressions": 31770,
    "ctr_percent": 2.3,
    "position": 7.6
  },
  "new_prescriptions": [
    "（処方の形。下の「データの形」を参照）"
  ],
  "near_first_page": [
    {
      "keyword": "テント 初心者 おすすめ",
      "page_url": "https://example.com/guide/tent-beginner/",
      "position": 9.4,
      "impressions": 320,
      "clicks": 4,
      "page_check": [
        {
          "ok": false,
          "part": "題名",
          "text": "題名に「初心者」を足す（…）"
        }
      ]
    }
  ],
  "checks": {
    "ssl_expiry": {
      "date": "2027-01-20",
      "daysLeft": 71
    },
    "domain_expiry": {
      "date": "2027-08-03",
      "daysLeft": 266
    },
    "domain": "example.com"
  },
  "generated_at": "2026-11-11T22:00:12.000Z"
}

GET /sites/{id}/kartes　権限：読み取り

過去のカルテの一覧（新しい順）。

リクエスト例

curl -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  https://kensakukarte.kotoformlabs.com/api/v1/sites/3/kartes

レスポンス例

{
  "kartes": [
    {
      "week_start": "2026-11-02",
      "clicks": 812,
      "impressions": 38120,
      "position": 7.4,
      "prescriptions": 3,
      "mailed_at": "2026-11-11 22:00:30"
    }
  ]
}

処方

GET /sites/{id}/prescriptions　権限：読み取り

処方の一覧。対応中が先、その中は古い順。

パラメータ	内容
`status`	任意。`active`（既定：対応中＋未対応）・`open`・`doing`・`done`・`dismissed`・`resolved`・`all`

リクエスト例

curl -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  "https://kensakukarte.kotoformlabs.com/api/v1/sites/3/prescriptions?status=active"

レスポンス例

{
  "prescriptions": [
    {
      "id": 12,
      "site_id": 3,
      "status": "open",
      "status_label": "未対応",
      "kind": "ctr",
      "kind_label": "あと一歩",
      "page_url": "https://example.com/guide/tent-beginner/",
      "keyword": "テント 初心者 おすすめ",
      "heading": "/guide/tent-beginner/",
      "facts": "順位 9.4　表示 320回　クリック 4（CTR 1.3%）・28日",
      "instruction": "題名に「初心者」を足す（今の題名：テントの選び方…）",
      "metrics": {
        "position": 9.4,
        "impressions": 320,
        "clicks": 4,
        "period": "直近28日"
      },
      "page_check": {
        "fetched": true,
        "page_title": "テントの選び方と人気モデル｜Example",
        "checked_at": "2026-11-10T08:53:40.809Z",
        "items": [
          {
            "ok": false,
            "part": "題名",
            "text": "題名に「初心者」を足す（今の題名：テントの選び方と人気モデル｜Example）"
          },
          {
            "ok": true,
            "part": "見出し",
            "text": "検索語を含む見出しがある"
          },
          {
            "ok": false,
            "part": "説明文",
            "text": "説明文に「初心者」と答えの要点を入れる"
          }
        ]
      },
      "affected_pages": null,
      "first_week": "2026-11-02",
      "last_seen_week": "2026-11-02",
      "status_changed_at": null,
      "effect_since_done": null
    }
  ]
}

GET /prescriptions/{id}　権限：読み取り

処方1件の詳細。

リクエスト例

curl -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  https://kensakukarte.kotoformlabs.com/api/v1/prescriptions/12

レスポンス例

{
  "id": 12,
  "site_id": 3,
  "status": "open",
  "status_label": "未対応",
  "kind": "ctr",
  "kind_label": "あと一歩",
  "page_url": "https://example.com/guide/tent-beginner/",
  "keyword": "テント 初心者 おすすめ",
  "heading": "/guide/tent-beginner/",
  "facts": "順位 9.4　表示 320回　クリック 4（CTR 1.3%）・28日",
  "instruction": "題名に「初心者」を足す（今の題名：テントの選び方…）",
  "metrics": {
    "position": 9.4,
    "impressions": 320,
    "clicks": 4,
    "period": "直近28日"
  },
  "page_check": {
    "fetched": true,
    "page_title": "テントの選び方と人気モデル｜Example",
    "checked_at": "2026-11-10T08:53:40.809Z",
    "items": [
      {
        "ok": false,
        "part": "題名",
        "text": "題名に「初心者」を足す（今の題名：テントの選び方と人気モデル｜Example）"
      },
      {
        "ok": true,
        "part": "見出し",
        "text": "検索語を含む見出しがある"
      },
      {
        "ok": false,
        "part": "説明文",
        "text": "説明文に「初心者」と答えの要点を入れる"
      }
    ]
  },
  "affected_pages": null,
  "first_week": "2026-11-02",
  "last_seen_week": "2026-11-02",
  "status_changed_at": null,
  "effect_since_done": null
}

PATCH /prescriptions/{id}　権限：変更

対応状況を変える。done にすると、その時点の順位とクリックを記録し、翌週以降の effect_since_done に変化が入ります。

パラメータ	内容
`status`	必須。`open`（未対応）・`doing`（対応中）・`done`（対応済み）・`dismissed`（見送り）

リクエスト例

curl -X PATCH -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}' \
  https://kensakukarte.kotoformlabs.com/api/v1/prescriptions/12

レスポンス例

{
  "id": 12,
  "site_id": 3,
  "status": "done",
  "status_label": "対応済み",
  "kind": "ctr",
  "kind_label": "あと一歩",
  "page_url": "https://example.com/guide/tent-beginner/",
  "keyword": "テント 初心者 おすすめ",
  "heading": "/guide/tent-beginner/",
  "facts": "順位 9.4　表示 320回　クリック 4（CTR 1.3%）・28日",
  "instruction": "題名に「初心者」を足す（今の題名：テントの選び方…）",
  "metrics": {
    "position": 9.4,
    "impressions": 320,
    "clicks": 4,
    "period": "直近28日"
  },
  "page_check": {
    "fetched": true,
    "page_title": "テントの選び方と人気モデル｜Example",
    "checked_at": "2026-11-10T08:53:40.809Z",
    "items": [
      {
        "ok": false,
        "part": "題名",
        "text": "題名に「初心者」を足す（今の題名：テントの選び方と人気モデル｜Example）"
      },
      {
        "ok": true,
        "part": "見出し",
        "text": "検索語を含む見出しがある"
      },
      {
        "ok": false,
        "part": "説明文",
        "text": "説明文に「初心者」と答えの要点を入れる"
      }
    ]
  },
  "affected_pages": null,
  "first_week": "2026-11-02",
  "last_seen_week": "2026-11-02",
  "status_changed_at": "2026-11-12 01:20:00",
  "effect_since_done": null
}

POST /prescriptions/{id}/recheck　権限：変更

公開中のページを読み直し、点検をやり直す。ページとキーワードの組み合わせの処方だけが対象です。

リクエスト例

curl -X POST -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  https://kensakukarte.kotoformlabs.com/api/v1/prescriptions/12/recheck

レスポンス例

{
  "id": 12,
  "site_id": 3,
  "status": "open",
  "status_label": "未対応",
  "kind": "ctr",
  "kind_label": "あと一歩",
  "page_url": "https://example.com/guide/tent-beginner/",
  "keyword": "テント 初心者 おすすめ",
  "heading": "/guide/tent-beginner/",
  "facts": "順位 9.4　表示 320回　クリック 4（CTR 1.3%）・28日",
  "instruction": "題名に「初心者」を足す（今の題名：テントの選び方…）",
  "metrics": {
    "position": 9.4,
    "impressions": 320,
    "clicks": 4,
    "period": "直近28日"
  },
  "page_check": {
    "fetched": true,
    "page_title": "テントの選び方と人気モデル｜Example",
    "checked_at": "2026-11-12T01:19:41.000Z",
    "items": [
      {
        "ok": true,
        "part": "題名",
        "text": "題名に「初心者」を足す（今の題名：テントの選び方と人気モデル｜Example）"
      },
      {
        "ok": true,
        "part": "見出し",
        "text": "検索語を含む見出しがある"
      },
      {
        "ok": true,
        "part": "説明文",
        "text": "説明文に「初心者」と答えの要点を入れる"
      }
    ]
  },
  "affected_pages": null,
  "first_week": "2026-11-02",
  "last_seen_week": "2026-11-02",
  "status_changed_at": null,
  "effect_since_done": null
}

POST /sites/{id}/prescriptions　権限：変更

最新カルテの「あと少しで1ページ目」のキーワードを、対応中の処方として記録する。同じページとキーワードの処方がすでにあれば、それを返します。

パラメータ	内容
`page_url`	必須。カルテの near_first_page にあるページURL
`keyword`	必須。同じくキーワード

リクエスト例

curl -X POST -H "Authorization: Bearer $KENSAKUKARTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_url":"https://example.com/guide/tent-beginner/","keyword":"テント 初心者 おすすめ"}' \
  https://kensakukarte.kotoformlabs.com/api/v1/sites/3/prescriptions

レスポンス例

{
  "id": 12,
  "site_id": 3,
  "status": "doing",
  "status_label": "対応中",
  "kind": "ctr",
  "kind_label": "あと一歩",
  "page_url": "https://example.com/guide/tent-beginner/",
  "keyword": "テント 初心者 おすすめ",
  "heading": "/guide/tent-beginner/",
  "facts": "順位 9.4　表示 320回　クリック 4（CTR 1.3%）・28日",
  "instruction": "題名に「初心者」を足す（今の題名：テントの選び方…）",
  "metrics": {
    "position": 9.4,
    "impressions": 320,
    "clicks": 4,
    "period": "直近28日"
  },
  "page_check": {
    "fetched": true,
    "page_title": "テントの選び方と人気モデル｜Example",
    "checked_at": "2026-11-10T08:53:40.809Z",
    "items": [
      {
        "ok": false,
        "part": "題名",
        "text": "題名に「初心者」を足す（今の題名：テントの選び方と人気モデル｜Example）"
      },
      {
        "ok": true,
        "part": "見出し",
        "text": "検索語を含む見出しがある"
      },
      {
        "ok": false,
        "part": "説明文",
        "text": "説明文に「初心者」と答えの要点を入れる"
      }
    ]
  },
  "affected_pages": null,
  "first_week": "2026-11-02",
  "last_seen_week": "2026-11-02",
  "status_changed_at": null,
  "effect_since_done": null
}

データの形（処方）

項目	内容
id / site_id	処方とサイトのID
status	`open` 未対応・`doing` 対応中・`done` 対応済み・`dismissed` 見送り・`resolved` 自然に解消（2週続けて条件を満たさなくなった）
kind	`ctr` あと一歩・`zero` クリック0・`new` 伸び始め・`deep` 新記事の種・`drop` 急減・`cannibal` 重複・`sitemap` サイトマップ・`index` 未登録
page_url / keyword	対象のページと検索キーワード（サイト全体の処方では keyword が null）
heading / facts / instruction	見出し、根拠の数値、何をするか（画面とメールと同じ文言）
metrics	直近28日の順位・表示・クリック
page_check	ページ点検の結果。`items[].ok` が false の項目が直す点
affected_pages	重複・未登録のときの対象ページ
effect_since_done	対応済みにした後の変化（翌週以降）

keyword・page_title・page_check の文言には、検索した人や公開ページから来た外部の文字列が含まれます。画面に出すときはHTMLとしてではなく文字として扱い、AIに渡すときは指示として扱わせないでください。

セキュリティ

キーの守り方、権限と有効期限、検索カルテ側の対策はセキュリティと安全な使い方にまとめています。

お問い合わせ：support@kotoformlabs.com

運営：KotoForm Labs　プライバシーポリシー　利用規約　特定商取引法に基づく表記