API

QueryWinを自社のパイプラインに組み込む

QueryWinは、サイトがすでに検索結果に表示されているのに対応するページがない検索キーワードを見つけ、足りない記事の下書きを作成します。あわせて、ディレクトリ、ローンチプラットフォーム、コミュニティ、AIの回答がすでに引用しているサイトへの掲載申請に向けて、プロダクトの準備を整えます。このAPIは、その両方のパイプラインをスクリプトやAIアシスタントに渡します。公開と申請は、これまでどおりご自身の認証情報とアカウントで行います。QueryWinがCMSに接続することも、自らどこかへ申請することもありません。

Base URLhttps://www.querywin.com/apiAPIキーを作成 OpenAPI仕様（JSON） →

クイックスタート

3ステップで始められます。以下はすべて、ヘッダーを1つ付けるだけの通常のREST呼び出しです。

APIキーを作成

QueryWinのダッシュボードの「API」から作成します。平文のキーが表示されるのは作成時の1回だけです。スコープは必要なものだけを付与してください。チェックをひとつも入れないキーは読み取り専用になります。

Bearerトークンとして送信

すべてのリクエストに、ヘッダー「Authorization: Bearer qw_live_…」を付けます。ヘッダーを1つしか設定できないツールでは、X-API-Keyも使えます。

書くべきテーマを確認し、下書きを取得

テーマ一覧の取得は無料で、クレジットを消費しません。アウトラインや下書きの生成ではクレジットが差し引かれ、spendスコープが必要です。

bash

# 1. このキーで操作できるサイト
curl "https://www.querywin.com/api/v1/sites" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

# 2. 今週書くべきテーマ（無料・クレジット消費なし）
curl "https://www.querywin.com/api/v1/topics?siteId=YOUR_SITE_ID" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

bash

# 3. 下書きを取得（Markdown + データ入力済みのJSON-LD）
curl "https://www.querywin.com/api/v1/topics/article?siteId=YOUR_SITE_ID&key=standard%20wardrobe%20depth" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

# 4. スクリプトが自社ブログに公開し、そのURLを報告
curl -X POST https://www.querywin.com/api/v1/topics/published \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "YOUR_SITE_ID",
    "key": "standard wardrobe depth",
    "url": "https://example.com/blog/standard-wardrobe-depth"
  }'

レスポンスはすべて{"success": true, "data": …}の形式でラップされます。エラーは文章ではなく、機械で読み取れるコードで返します。QueryWinは多言語に対応しているため、英語の文章をハードコードすると、日本語のページにもそのまま表示されてしまうからです。

コンテンツパイプライン

全5ステップのうち、費用がかかるのは2つだけです。ステップ4はご自身の担当です。QueryWinがMarkdownと構造化データを渡し、公開はご自身で行います。

ステップ	エンドポイント	費用
表示回数はあるがページのないキーワードを探す	`GET /v1/topics`	無料
根拠のあるアウトラインを生成する	`POST /v1/topics/outline`	クレジット
公開できる下書きに仕上げる	`POST /v1/topics/article`	クレジット
自社ブログで公開する	自社のCMS	—
URLを報告する	`POST /v1/topics/published`	無料

QueryWinがCMSに接続することも、サイトの認証情報を預かることも、代わりに公開ボタンを押すこともありません。このAPIが渡すのはコンテンツだけで、書き込みはご自身の環境で、ご自身の認証情報を使って行われます。これは境界線そのものであり、境界の抜け道ではありません。

掲載パイプライン

全7ステップのうち、費用がかかるのは1つだけです。ステップ6はご自身の担当です。QueryWinが掲載先ごとの掲載素材を渡し、ご自身（またはご自身のアカウントを使うエージェント）が申請します。掲載された各ページは、その後QueryWinが自ら再確認します。

ステップ	エンドポイント	費用
プロダクトの一覧と、各プロダクト情報の入力状況を取得する	`GET /v1/products`	無料
相性順に並んだ掲載先の一覧を取得する（AIの回答が引用しているサイトも含む）	`GET /v1/channels?productId=`	無料
選んだ掲載先からキャンペーンを作成する	`POST /v1/campaigns`	無料
タスクごとに用意された掲載素材を取得する	`GET /v1/tasks/{id}`	無料
その掲載先向けに書き換える	`POST /v1/tasks/{id}/materials`	クレジット
申請する	ご自身のアカウント	—
申請済み、続いて掲載済み（掲載ページのURL付き）を報告する	`POST /v1/tasks/{id}/status`	無料

publishedはご自身が報告した内容、verifiedはQueryWinが約72時間後に掲載ページを再確認したときに確認できた内容です。ディレクトリとAIツール紹介サイトではプロダクトへのリンク、それ以外では言及の有無を確認します。両者は別々のフィールドです。また、AIの回答が引用しているサイト（citedByAi）は申請する価値のあるサイトですが、掲載を約束するものではありません。

スコープ

各キーには、作成時に付与された権限が設定されています。GET /v1/usageで確認できるため、403エラーに遭遇して初めて気づくことはありません。

read

常に有効

すべてのGETエンドポイント：サイト、コンテンツギャップ、アウトライン、下書き、プロダクト、掲載先、キャンペーン、タスクとその掲載素材、利用状況。

publish

デフォルトで無効

プロダクト情報の作成と更新、画像のインポート、実際に起きたことの記録：公開した記事のURL（Bing、Yandex、Seznam、Naverにも送信。Googleは対象外）、新しいキャンペーン、申請済みまたは掲載済みにしたタスク。無料ですが、どれも影響を伴う記録です。キャンペーンはプランの上限にカウントされ、掲載済みのページは再確認の対象になります。

spend

デフォルトで無効

アウトラインと下書きの生成、掲載先向けの掲載素材の書き換え。これらはクレジットを消費します。呼び出し元（スクリプトやAIアシスタント）に自らの判断で支出させたい場合にのみ付与してください。

スコープに上下関係はありません。publishがspendを含むことも、spendがpublishを含むこともありません。それぞれ異なる種類のリスクだからです。キーに必要なスコープがない呼び出しは、missing_scope_<name>と、そのキーが持つスコープを添えて403を返します。

クレジットの消費

クレジットを消費するエンドポイントは、POST /v1/topics/outlineとPOST /v1/topics/articleの2つです。その手前に3つの安全装置があります。

安全装置	防ぐもの
`confirmSpend`	価格が上がった後も、スクリプトが課金を続けること。
1日の上限	暴走したループが一晩で残高を使い切ること。上限に達すると、リセット時刻とともに429を返します。
入力フィンガープリント	同じテーマへの二重課金。入力が同じならキャッシュ済みの結果を無料で返すため、タイムアウトしたリクエストも安全に再試行できます。

confirmSpendは承認する上限額であり、正確な金額ではありません。現在の価格以上の値を送れば、実際にかかった分だけが差し引かれます。キャッシュに当たった場合は0になることもよくあります。価格が上限を超えた場合は、黙って多く差し引くのではなく、confirm_spend_too_lowで呼び出しが失敗します。

共通仕様

すべてのエンドポイントに共通する3つの仕様です。

レスポンスの共通形式

json

{ "success": true,  "data": { "...": "..." } }
{ "success": false, "error": "missing_scope_spend" }

エラーは文章ではなくコードで返します。そのまま表示せず、読み取ってから独自の文言に置き換えてください。

業務上の結果はエラーとして返しません

生成の呼び出しで有効な結果が得られなかった場合は、HTTP 200で、data.ok = falseとdata.failureコードを返します。そのため、認証エラーや接続の切断と区別できます。この場合、料金はかかりません。

json

{
  "success": true,
  "data": { "ok": false, "failure": "no_outline", "creditsSpent": 0 }
}

レート制限

キーごとに毎分120リクエストまでです。超えるとリセット時刻とともに429を返します。これは前述の1日あたりの生成上限とは別の制限です。

AIエージェント向けMCP

両方のパイプラインは、Model Context Protocolでも利用できます。認証には同じキーと同じヘッダーを使います。Claude Code、Cursor、n8nなど、HTTP経由のMCPに対応するツールに追加できます。

MCPhttps://www.querywin.com/api/mcp

bash

claude mcp add --transport http querywin https://www.querywin.com/api/mcp \
  --header "Authorization: Bearer $QUERYWIN_API_KEY"

ツールは全19種類です。プロダクト情報：create_product、get_product、update_product、import_product_image。コンテンツ：list_sites、get_usage、list_content_gaps、get_outline、get_article_draft、generate_outline、generate_article_draft、mark_published。掲載：list_products、list_channels、create_campaign、list_tasks、get_task、write_task_materials、report_task_status。「今週は何を書くべきか」「次にどこへ申請すべきか」をアシスタントに尋ねると、アシスタントが自ら調べます。

プロンプト

QueryWinのMCPサーバーを使って、自社サイトで最も大きいコンテンツギャップを3つ見つけ、
それぞれの根拠となる検索キーワードを示したうえで、1位のギャップの下書きにかかる費用を教えてください。

ツールはスコープで絞り込まれます。読み取り専用のキーでは、生成系のツールはアシスタントのツール一覧に表示すらされません。見えないツールは、エージェントも呼び出せません。エージェントには専用のキーを発行しておくと、ほかの連携に影響を与えずに失効させられます。

認証にはBearerトークンを使います。MCPの仕様ではこれが認められています（仕様上、認可は任意です）。Claude Code、Cursor、n8nのようにヘッダーを設定できるクライアントは、そのまま接続できます。OAuthの同意画面を必須とするホストでは、接続できない場合があります。

Account

GET/v1/sites

このキーで操作できるサイトの一覧

最初にここを呼び出してください。ほかのすべてのエンドポイントは、ここで返るsiteIdを受け取ります。siteIdを省略した場合は、最初に接続したサイトが使われます。サイトが1つだけのアカウントなら問題ありませんが、それ以外では、いずれ不具合の原因になります。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	SiteList
└sites	array<Site>
└siteId	string
└domain	string
└gscProperty	string	Search Consoleのプロパティをそのまま返します。`sc-domain:example.com`または`https://example.com/`の形式です。
└syncStatus	enum	指定できる値：`pendingsyncingdonefailed`
└syncedThroughnull許容	string	Search Consoleのデータは2〜3日遅れます。このサイトの指標はすべて、この日付時点のものです。数値をどこかに表示する場合は、この日付時点の数値であることを明記してください。

発生しうるエラー

401キーが未指定、形式不正、無効化済み、または期限切れ

例

bash

curl "https://www.querywin.com/api/v1/sites" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "sites": [
      {
        "siteId": "string",
        "domain": "example.com",
        "gscProperty": "string",
        "syncStatus": "pending",
        "syncedThrough": "2026-09-01T00:00:00.000Z"
      }
    ]
  }
}

GET/v1/usage

現在の価格、無料枠、クレジット残高、1日の上限

生成を行う前に、まずこれを読んでください。Web画面がボタンに何を表示するかを決めるのにも、これと同じ情報を使っています。利用できるかどうかはサーバー側で判定されます。試しに呼び出して、失敗したかどうかで判断するものではありません。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	Usage
└scopes	array<enum>	このキーで許可されている操作です。403エラーにぶつかってから権限に気づくのではなく、起動時に一度読み取ってください。指定できる値：`readpublishspend`
└credits	object
└balance	integer
└outline	StepUsage
└available	boolean	生成エンジンが設定されていない場合はfalseです。その場合は、対応するPOSTエンドポイントを呼び出さないでください。
└pricePerOutline	integer	アウトライン1件あたりのクレジット（`outline`にのみ含まれます）。
└pricePerArticle	integer	下書き1件あたりのクレジット（`article`にのみ含まれます）。
└pricePerTask	integer	掲載先向けの書き直し1回あたりのクレジット（`materials`にのみ含まれます）。
└freeRemaining	integer	このアカウントで無料で生成できる残り回数です。ボタンを押した回数ではなく、異なるトピックごと（アウトライン、下書き）または異なるタスクごと（掲載素材）に数えます。無料で生成する場合も`confirmSpend`が必要です。
└daily	DailyLimit	暴走したスクリプトへの歯止めです。データベース上で、すべての利用経路をまとめて数えます（Web画面での操作も含みます）。スライディングウィンドウではなく、現地時間の午前0時にリセットされます。
└used	integer
└limit	integer
└remaining	integer
└resetAt	string
└article	StepUsage
└available	boolean	生成エンジンが設定されていない場合はfalseです。その場合は、対応するPOSTエンドポイントを呼び出さないでください。
└pricePerOutline	integer	アウトライン1件あたりのクレジット（`outline`にのみ含まれます）。
└pricePerArticle	integer	下書き1件あたりのクレジット（`article`にのみ含まれます）。
└pricePerTask	integer	掲載先向けの書き直し1回あたりのクレジット（`materials`にのみ含まれます）。
└freeRemaining	integer	このアカウントで無料で生成できる残り回数です。ボタンを押した回数ではなく、異なるトピックごと（アウトライン、下書き）または異なるタスクごと（掲載素材）に数えます。無料で生成する場合も`confirmSpend`が必要です。
└daily	DailyLimit	暴走したスクリプトへの歯止めです。データベース上で、すべての利用経路をまとめて数えます（Web画面での操作も含みます）。スライディングウィンドウではなく、現地時間の午前0時にリセットされます。
└used	integer
└limit	integer
└remaining	integer
└resetAt	string
└materials	StepUsage
└available	boolean	生成エンジンが設定されていない場合はfalseです。その場合は、対応するPOSTエンドポイントを呼び出さないでください。
└pricePerOutline	integer	アウトライン1件あたりのクレジット（`outline`にのみ含まれます）。
└pricePerArticle	integer	下書き1件あたりのクレジット（`article`にのみ含まれます）。
└pricePerTask	integer	掲載先向けの書き直し1回あたりのクレジット（`materials`にのみ含まれます）。
└freeRemaining	integer	このアカウントで無料で生成できる残り回数です。ボタンを押した回数ではなく、異なるトピックごと（アウトライン、下書き）または異なるタスクごと（掲載素材）に数えます。無料で生成する場合も`confirmSpend`が必要です。
└daily	DailyLimit	暴走したスクリプトへの歯止めです。データベース上で、すべての利用経路をまとめて数えます（Web画面での操作も含みます）。スライディングウィンドウではなく、現地時間の午前0時にリセットされます。
└used	integer
└limit	integer
└remaining	integer
└resetAt	string
└distribution	DistributionQuota	プランの掲載申請の上限と、現在の使用量です。上限がnullの場合は無制限です。
└plan	string
└limits	object
└channelsnull許容	integer	1つのプロダクトがタスクを持てる、異なる掲載先の数。`channelsPeriod`の期間で数えます。
└channelsPeriod	enum	`month`（有料プラン）：暦月（UTC）ごとに数えるため、毎月新たな掲載先をまとめて追加できます。`total`（無料プラン）：プロダクトの全期間を通じて数えます。指定できる値：`monthtotal`
└tasksPerMonthnull許容	integer	暦月（UTC）ごとに作成できるタスクの数（全プロダクトの合計）。
└activeCampaignsnull許容	integer	同時に進行できるキャンペーンの数。
└usage	object
└activeCampaigns	integer
└tasksThisMonth	integer
└channelsnull許容	integer	リクエストでプロダクトを指定した場合のみ。

発生しうるエラー

401認証エラー

例

bash

curl "https://www.querywin.com/api/v1/usage" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "scopes": [
      "read"
    ],
    "credits": {
      "balance": 0
    },
    "outline": {
      "available": true,
      "pricePerOutline": 0,
      "pricePerArticle": 0,
      "pricePerTask": 0,
      "freeRemaining": 0,
      "daily": {
        "used": 0,
        "limit": 0,
        "remaining": 0,
        "resetAt": "2026-09-01T00:00:00.000Z"
      }
    },
    "article": {
      "available": true,
      "pricePerOutline": 0,
      "pricePerArticle": 0,
      "pricePerTask": 0,
      "freeRemaining": 0,
      "daily": {
        "used": 0,
        "limit": 0,
        "remaining": 0,
        "resetAt": "2026-09-01T00:00:00.000Z"
      }
    },
    "materials": {
      "available": true,
      "pricePerOutline": 0,
      "pricePerArticle": 0,
      "pricePerTask": 0,
      "freeRemaining": 0,
      "daily": {
        "used": 0,
        "limit": 0,
        "remaining": 0,
        "resetAt": "2026-09-01T00:00:00.000Z"
      }
    },
    "distribution": {
      "plan": "string",
      "limits": {
        "channels": 0,
        "channelsPeriod": "month",
        "tasksPerMonth": 0,
        "activeCampaigns": 0
      },
      "usage": {
        "activeCampaigns": 0,
        "tasksThisMonth": 0,
        "channels": 0
      }
    }
  }
}

Topics

GET/v1/topics

表示回数はあるのに、対応するページがない検索キーワード

無料で、外部サービスへの課金も発生しません（API自体の利用には有料プランが必要です）。呼び出しのたびに、ご自身のSearch Consoleのデータから計算し直します。外部のキーワードデータベースは使いません。そこが肝心な点で、「すでに表示回数があるのに、対応するページがない」ことは、キーワードツールでは分かりません。

結果は機会の大きい順に並びます。ユーザーが画面上で非表示にしたトピックは除外されます。

クエリパラメータ

フィールド	型	説明
siteId	string	`GET /v1/sites`で取得した値。省略すると、最初に接続したサイトが使われます。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	TopicList
└siteIdnull許容	string
└topics	array<Topic>
└key	string	クラスタキーです。ほかのトピック系エンドポイントには、これをそのまま`key`として渡してください。クラスタを代表する検索キーワードを正規化したテキストなので、空白、スラッシュ、ラテン文字以外の文字を含むことがあります。必ずクエリ文字列かリクエスト本文で送り、URLのパスには入れないでください。
└title	string	クラスタ内で表示回数が最も多い検索キーワードを、そのまま返します。生成されたタイトルではありません。タイトルはアウトラインに含まれます。
└shape	enum	`comparison`は、このクラスタが競合リストに該当したことを示します。記事は競合の説明ではなく、比較でなければなりません。そうしないと、競合のためにコンテンツを書くことになります。指定できる値：`comparisonroundupguide`
└intent	string
└members	array<TopicMember>
└text	string	入力されたままの検索キーワード。
└impressions	integer
└clicks	integer
└positionnull許容	number
└landingUrlnull許容	string	この検索キーワードについて、Search Consoleが現在記録しているページ（ある場合）。
└impressions	integer	Search Consoleの実測値です。
└clicks	integer	Search Consoleの実測値です。
└positionnull許容	number	実測値です。クラスタ全体の平均掲載順位を、表示回数で重み付けして算出しています。
└competitor	boolean
└score	number
└rank	integer
└upsideClicks	integer	推定値です。実測値ではありません。専用ページが掲載順位3位に達した場合に増える、月間クリック数の見込みです。このフィールドは意図的に`clicks`や`impressions`と分けています。表示する場所を問わず、見た目でもはっきり区別してください。見込みを実測データのように見せるのは、この分野のプロダクトにありがちな失敗です。
└status	enum	指定できる値：`newdismissedplannedpublished`
└outlineAtnull許容	string
└articleAtnull許容	string	`outlineAt`から推測しないでください。アウトラインがあっても、下書きがあるとは限りません。両者は別々の有料ステップです。
└totalQueries	integer	これらのトピック全体でカバーしている、異なる検索キーワードの総数。

発生しうるエラー

401認証エラー

404site_not_found（このsiteIdはこのアカウントに属していません）

例

bash

curl "https://www.querywin.com/api/v1/topics" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "siteId": "string",
    "topics": [
      {
        "key": "string",
        "title": "string",
        "shape": "comparison",
        "intent": "string",
        "members": [
          {
            "text": null,
            "impressions": null,
            "clicks": null,
            "position": null,
            "landingUrl": null
          }
        ],
        "impressions": 0,
        "clicks": 0,
        "position": 0,
        "competitor": true,
        "score": 0,
        "rank": 0,
        "upsideClicks": 0,
        "status": "new",
        "outlineAt": "2026-09-01T00:00:00.000Z",
        "articleAt": "2026-09-01T00:00:00.000Z"
      }
    ],
    "totalQueries": 0
  }
}

GET/v1/topics/article

生成済みの下書きを取得

生成は一切行わず、費用もかかりません。下書きがまだない場合、articleはnullです。

クエリパラメータ

フィールド	型	説明
key必須	string	`GET /v1/topics`で取得したクラスタキー。
siteId	string	`GET /v1/sites`で取得した値。省略すると、最初に接続したサイトが使われます。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	ArticleResult
└articlenull許容	Article
└title	string
└description	string	メタディスクリプション。
└markdown	string	公開する本文。
└jsonLd	string	この記事の構造化データで、内容はすでに埋め込まれています。有効なJSONなので、公開ページで`application/ld+json`タイプのscriptタグに入れてください。
└wordCount	integer
└warnings	array<ArticleWarning>	AIが書いたように読める表現です。下書きはそのまま使えます。これらは黙って書き換えるのではなく、報告する形にしています。ログに記録してください。自動化されたパイプラインでは、誰かが気づける機会はここしかありません。
└kind	enum	指定できる値：`banned_phrasebanned_wordem_dash_overuseno_short_sentence`
└hit	string	問題のある箇所のテキスト。
└articleAtnull許容	string
└modelnull許容	string

発生しうるエラー

400key_required

401認証エラー

例

bash

curl "https://www.querywin.com/api/v1/topics/article?key=..." \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "article": {
      "title": "string",
      "description": "string",
      "markdown": "string",
      "jsonLd": "string",
      "wordCount": 0,
      "warnings": [
        {
          "kind": "banned_phrase",
          "hit": "string"
        }
      ]
    },
    "articleAt": "2026-09-01T00:00:00.000Z",
    "model": "string"
  }
}

POST/v1/topics/article

アウトラインから公開できる下書きを作成（クレジット消費）

QueryWinで最も高額な呼び出しです。同期処理で、1〜2分かかることがあります。

事前にアウトラインが必要です。アウトラインがないとfailure: "no_outline"が返ります。根拠を担っているのはアウトラインです（クラスタの背後にある実際の検索キーワード、現在AIが引用しているページ、既存ページとの重複排除）。アウトラインを省けば、この呼び出しは裏付けのないAIライティングツールと変わらなくなります。

article.markdownは公開する本文です。article.jsonLdは、この記事の内容をすでに埋め込んだ構造化データです。article.warningsは、破棄せずログに記録してください。警告はそれぞれ、AIが書いたように読める具体的な表現を指しています。自動化されたパイプラインでは、公開前に下書きを読み直す人はいません。

構造の検証に通らなかった下書き（セクションの欠落、必須の質問への未回答、実在しないリンク、壊れたJSON-LD）は破棄され、クレジットは消費されません。

リクエストボディ

フィールド	型	説明
key必須	string	`GET /v1/topics`で取得したクラスタキー。
siteId	string	省略すると、最初に接続したサイトが使われます。
confirmSpend必須	integer	クレジットで指定する承認の上限で、正確な金額ではありません。`GET /v1/usage`で確認した現在の価格以上の値を送ってください。消費されるのは実際にかかった分だけで、キャッシュが使われた場合は0になることもよくあります。価格が上限を超えた場合は、黙って多く消費するのではなく、呼び出しを拒否します。無料枠が残っていても必須です。無料枠はいずれなくなります。そのときに初めて、このエンドポイントが有料だとスクリプトが知る、という事態を避けるためです。 (min 0)

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	ArticleOutcome
└ok	boolean
└failure	enum	`ok`がfalseの場合にのみ含まれます。HTTPステータスは200のままです。指定できる値：`topic_not_foundno_outlineengine_unavailableengine_failedno_valid_article`
└articlenull許容	Article
└title	string
└description	string	メタディスクリプション。
└markdown	string	公開する本文。
└jsonLd	string	この記事の構造化データで、内容はすでに埋め込まれています。有効なJSONなので、公開ページで`application/ld+json`タイプのscriptタグに入れてください。
└wordCount	integer
└warnings	array<ArticleWarning>	AIが書いたように読める表現です。下書きはそのまま使えます。これらは黙って書き換えるのではなく、報告する形にしています。ログに記録してください。自動化されたパイプラインでは、誰かが気づける機会はここしかありません。
└kind	enum	指定できる値：`banned_phrasebanned_wordem_dash_overuseno_short_sentence`
└hit	string	問題のある箇所のテキスト。
└generated	boolean	キャッシュ済みの結果が返された場合はfalseです。クレジットは消費されていません。
└creditsSpent	integer
└freeUsed	boolean
└rejected	array<string>	下書きが破棄された原因となる構造上の不備です（この場合、クレジットは消費されません）：`missing_sections`、`missing_faq`、`invented_link`、`invalid_json_ld`、`comparison_without_contrast`、`body_too_short`。

発生しうるエラー

400key_required、confirm_spend_required、またはconfirm_spend_too_low（レスポンス本文に現在のpriceを含む）

401認証エラー

402insufficient_credits（レスポンス本文にrequiredCredits、currentBalance、shortfallを含む）

403missing_scope_spend（このキーにはspendスコープが付与されていません）

429rate_limitedまたはdaily_limit_reached（レスポンス本文にresetAtを含む）

例

bash

curl -X POST https://www.querywin.com/api/v1/topics/article \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "clx1site000",
    "key": "standard wardrobe depth",
    "confirmSpend": 80
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "ok": true,
    "failure": "topic_not_found",
    "article": {
      "title": "string",
      "description": "string",
      "markdown": "string",
      "jsonLd": "string",
      "wordCount": 0,
      "warnings": [
        {
          "kind": "banned_phrase",
          "hit": "string"
        }
      ]
    },
    "generated": true,
    "creditsSpent": 0,
    "freeUsed": true,
    "rejected": [
      "string"
    ]
  }
}

GET/v1/topics/outline

生成済みのアウトラインを取得

生成は一切行わず、費用もかかりません。アウトラインがまだない場合、outlineはnullです。

クエリパラメータ

フィールド	型	説明
key必須	string	`GET /v1/topics`で取得したクラスタキー。
siteId	string	`GET /v1/sites`で取得した値。省略すると、最初に接続したサイトが使われます。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	OutlineResult
└outlinenull許容	Outline
└title	string
└slug	string
└angle	string	このページが打ち出すべき主張です。
└sections	array<object>
└heading	string
└points	array<string>
└faq	array<object>	ページで答えるべき質問です。AIの回答に引用されるのは、こうした箇所です。
└question	string
└answer	string
└schemaType	string	このページに適したJSON-LDのタイプです。
└internalLinks	array<string>	自社サイト内で、リンクする価値のあるページです。実在するURLから選んでおり、架空のURLは含みません。
└outlineAtnull許容	string
└modelnull許容	string

発生しうるエラー

400key_required

401認証エラー

例

bash

curl "https://www.querywin.com/api/v1/topics/outline?key=..." \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "outline": {
      "title": "string",
      "slug": "string",
      "angle": "string",
      "sections": [
        {
          "heading": "string",
          "points": []
        }
      ],
      "faq": [
        {
          "question": "string",
          "answer": "string"
        }
      ],
      "schemaType": "string",
      "internalLinks": [
        "string"
      ]
    },
    "outlineAt": "2026-09-01T00:00:00.000Z",
    "model": "string"
  }
}

POST/v1/topics/outline

アウトラインを生成（クレジット消費）

同期処理です。10〜20秒ほどかかります。

入力が同じであれば、キャッシュ済みのアウトラインが返り、クレジットは再度消費されません。フィンガープリントはトピッククラスタとその競合分類から算出されるため、失敗したHTTPリクエストは安全に再試行できます。

処理結果としての失敗（エンジンが利用できない、出力が検証を通らない）では、HTTP 200でok: falseとfailureのコードを返します。クレジット不足は、処理結果ではなく402エラーとして返ります。

リクエストボディ

フィールド	型	説明
key必須	string	`GET /v1/topics`で取得したクラスタキー。
siteId	string	省略すると、最初に接続したサイトが使われます。
confirmSpend必須	integer	クレジットで指定する承認の上限で、正確な金額ではありません。`GET /v1/usage`で確認した現在の価格以上の値を送ってください。消費されるのは実際にかかった分だけで、キャッシュが使われた場合は0になることもよくあります。価格が上限を超えた場合は、黙って多く消費するのではなく、呼び出しを拒否します。無料枠が残っていても必須です。無料枠はいずれなくなります。そのときに初めて、このエンドポイントが有料だとスクリプトが知る、という事態を避けるためです。 (min 0)

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	OutlineOutcome
└ok	boolean
└failure	enum	`ok`がfalseの場合にのみ含まれます。HTTPステータスは200のままです。これはエラーではなく処理結果です。指定できる値：`topic_not_foundengine_unavailableengine_failedno_valid_outline`
└outlinenull許容	Outline
└title	string
└slug	string
└angle	string	このページが打ち出すべき主張です。
└sections	array<object>
└heading	string
└points	array<string>
└faq	array<object>	ページで答えるべき質問です。AIの回答に引用されるのは、こうした箇所です。
└question	string
└answer	string
└schemaType	string	このページに適したJSON-LDのタイプです。
└internalLinks	array<string>	自社サイト内で、リンクする価値のあるページです。実在するURLから選んでおり、架空のURLは含みません。
└generated	boolean	キャッシュ済みの結果が返された場合はfalseです。クレジットは消費されていません。
└creditsSpent	integer
└freeUsed	boolean
└rejected	array<string>	モデルの出力が引っかかった検証ルールです。品質のシグナルとして、ログに残しておくと役立ちます。

発生しうるエラー

400key_required、confirm_spend_required、またはconfirm_spend_too_low（レスポンス本文に現在のpriceを含む）

401認証エラー

402insufficient_credits（レスポンス本文にrequiredCredits、currentBalance、shortfallを含む）

403missing_scope_spend（このキーにはspendスコープが付与されていません）

429rate_limitedまたはdaily_limit_reached（レスポンス本文にresetAtを含む）

例

bash

curl -X POST https://www.querywin.com/api/v1/topics/outline \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "clx1site000",
    "key": "standard wardrobe depth",
    "confirmSpend": 80
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "ok": true,
    "failure": "topic_not_found",
    "outline": {
      "title": "string",
      "slug": "string",
      "angle": "string",
      "sections": [
        {
          "heading": "string",
          "points": []
        }
      ],
      "faq": [
        {
          "question": "string",
          "answer": "string"
        }
      ],
      "schemaType": "string",
      "internalLinks": [
        "string"
      ]
    },
    "generated": true,
    "creditsSpent": 0,
    "freeUsed": true,
    "rejected": [
      "string"
    ]
  }
}

POST/v1/topics/published

公開先のURLを報告

一連の流れを締めくくる呼び出しです。トピックを公開済みにしてURLを保存し、代わりにIndexNowへ送信します。

IndexNowの対象はBing、Yandex、Seznam、Naverで、Googleは含まれません。Googleには同等の即時インデックス用エンドポイントがなく、sitemapを通じてページを見つけます。

IndexNowへの送信が原因で、このリクエストが失敗することはありません。記事はすでに公開されており、この呼び出しが記録するのはその事実だからです。実際にどうなったかは、indexnowフィールドで確認してください。送信には、そのサイトでIndexNowのキーファイルが確認済みである必要があります（ダッシュボードで一度だけ設定します）。

URLを記録しておくと、記事が効果を発揮するだけの期間を置いてから、その記事が狙う検索キーワードをQueryWinが測定し直せるようになります。

リクエストボディ

フィールド	型	説明
key必須	string
siteId	string
url必須	string	公開先のURLです。http/httpsのみ受け付けます。この時点ではページを取得しません。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	PublishedResult
└clusterKey	string
└status	enum	指定できる値：`published`
└publishedUrl	string
└publishedAt	string
└indexnow	object	Bing、Yandex、Seznam、Naverが対象です。Googleは含まれません。
└pushed	boolean
└outcome	string	`skipped`は通常、キーファイルがまだ確認されていないことを意味します。
└engines	string

発生しうるエラー

400key_required、url_required、またはinvalid_url（http/httpsのみ）

401認証エラー

403missing_scope_publish（このキーにはpublishスコープが付与されていません）

404site_not_found

例

bash

curl -X POST https://www.querywin.com/api/v1/topics/published \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "clx1site000",
    "key": "standard wardrobe depth",
    "url": "https://example.com/blog/standard-wardrobe-depth"
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "clusterKey": "string",
    "status": "published",
    "publishedUrl": "string",
    "publishedAt": "2026-09-01T00:00:00.000Z",
    "indexnow": {
      "pushed": true,
      "outcome": "string",
      "engines": "string"
    }
  }
}

Distribution

GET/v1/campaigns

キャンペーンと掲載申請の上限

キャンペーンの一覧（includeArchived=trueを指定しない限り、アーカイブ済みは除外）と、プランの掲載申請の上限および現在の使用量を返します。無料です。

クエリパラメータ

フィールド	型	説明
productId	string	このプロダクトのキャンペーンのみ。
includeArchived	boolean

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	CampaignList
└campaigns	array<Campaign>
└campaignId	string
└productId	string
└name	string
└status	enum	`completed`は算出値で、すべてのタスクが掲載中、確認済み、失敗、スキップのいずれかになった状態です。指定できる値：`activecompletedarchived`
└quota	integer	キャンペーン作成時に選んだ掲載先の数。
└startsAt	string
└endsAtnull許容	string
└counts	object
└total	integer
└submitted	integer	submitted + published + verifiedの合計です。
└live	integer	published + verifiedの合計です。
└blocked	integer
└done	integer
└byStatus	object
└createdAt	string
└quota	DistributionQuota	プランの掲載申請の上限と、現在の使用量です。上限がnullの場合は無制限です。
└plan	string
└limits	object
└channelsnull許容	integer	1つのプロダクトがタスクを持てる、異なる掲載先の数。`channelsPeriod`の期間で数えます。
└channelsPeriod	enum	`month`（有料プラン）：暦月（UTC）ごとに数えるため、毎月新たな掲載先をまとめて追加できます。`total`（無料プラン）：プロダクトの全期間を通じて数えます。指定できる値：`monthtotal`
└tasksPerMonthnull許容	integer	暦月（UTC）ごとに作成できるタスクの数（全プロダクトの合計）。
└activeCampaignsnull許容	integer	同時に進行できるキャンペーンの数。
└usage	object
└activeCampaigns	integer
└tasksThisMonth	integer
└channelsnull許容	integer	リクエストでプロダクトを指定した場合のみ。

発生しうるエラー

401認証エラー

例

bash

curl "https://www.querywin.com/api/v1/campaigns" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "campaignId": "string",
        "productId": "string",
        "name": "string",
        "status": "active",
        "quota": 0,
        "startsAt": "2026-09-01T00:00:00.000Z",
        "endsAt": "2026-09-01T00:00:00.000Z",
        "counts": {
          "total": 0,
          "submitted": 0,
          "live": 0,
          "blocked": 0,
          "done": 0,
          "byStatus": null
        },
        "createdAt": "2026-09-01T00:00:00.000Z"
      }
    ],
    "quota": {
      "plan": "string",
      "limits": {
        "channels": 0,
        "channelsPeriod": "month",
        "tasksPerMonth": 0,
        "activeCampaigns": 0
      },
      "usage": {
        "activeCampaigns": 0,
        "tasksThisMonth": 0,
        "channels": 0
      }
    }
  }
}

POST/v1/campaigns

明示した掲載先のリストからキャンペーンを作成

掲載先IDごとに1件のタスクを作成し、プロダクト情報から掲載素材をその場で無料で用意します。実際に選んだ掲載先だけを渡してください。キャンペーンは申請先として決めた場所の記録であり、サーバー側で対象を広げるフィルターではありません。

そのプロダクトで進行中または申請済みのタスクがある掲載先はスキップされ、理由（already_open、already_submitted、not_found、broken、inactive、other_product、locked）とともにskippedに列挙されます。何も残らない場合は、HTTP 200でok: falseとfailure: "no_valid_targets"を返します。プランの掲載申請の上限を超える場合は、409で拒否されます（quota_exceeded。dimension、limit、used、requestedを含みます）。何も作成されず、上限内に収まったはずの分も作成されません。

リクエストボディ

フィールド	型	説明
productId必須	string
name必須	string
targetIds必須	array<string>	`GET /v1/channels`で取得した掲載先ID。選んだ掲載先だけを指定します。
endsAt	string	任意の期限。ダッシュボードに表示されますが、自動で終了することはありません。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	CreateCampaignOutcome
└ok	boolean
└failure	enum	`ok`がfalseの場合に含まれます。指定できる値：`no_valid_targets`
└campaign	Campaign
└campaignId	string
└productId	string
└name	string
└status	enum	`completed`は算出値で、すべてのタスクが掲載中、確認済み、失敗、スキップのいずれかになった状態です。指定できる値：`activecompletedarchived`
└quota	integer	キャンペーン作成時に選んだ掲載先の数。
└startsAt	string
└endsAtnull許容	string
└counts	object
└total	integer
└submitted	integer	submitted + published + verifiedの合計です。
└live	integer	published + verifiedの合計です。
└blocked	integer
└done	integer
└byStatus	object
└createdAt	string
└tasks	array<Task>
└taskId	string
└campaignId	string
└productId	string
└status	enum	`published`はご自身が報告した状態、`verified`はQueryWinが掲載ページで確認した状態です（ディレクトリとAIツールのディレクトリではリンク、それ以外では言及）。報告の際は両者を区別してください。指定できる値：`plannedpreparedin_progressblockedsubmittedpublishedverifiedfailedskipped`
└blockedReasonnull許容	enum	指定できる値：`logincaptchapaymentmissing_materialothernull`
└missing	array<string>	プロダクト情報に欠けている必須の掲載素材。ダッシュボードでプロダクト情報を補うと、タスクは自動的に準備し直されます。
└listingUrlnull許容	string
└markedBy	enum	最後にステータスを変更した主体：人（またはこのAPI）、ブラウザ拡張機能、QueryWin自身のいずれか。指定できる値：`userdevicesystem`
└hasGenerated	boolean	この掲載先向けに書き直したバージョンがあります。
└reviewDueAtnull許容	string	申請後に結果を確認する日時（submittedAtに掲載先の審査日数を足したもの）。
└submittedAtnull許容	string
└publishedAtnull許容	string
└verifiedAtnull許容	string
└next	array<string>	現在のステータスから、`POST /v1/tasks/{id}/status`で設定できるステータス。
└target	object
└targetId	string
└name	string
└url	string
└submitUrl	string
└kind	string
└source	enum	指定できる値：`seeduserrivals`
└language	string
└requiresBacklink	boolean
└checknull許容	object	掲載後に、QueryWinが掲載ページに対して行う再確認。タスクが掲載中になるまではnullです。
└kind	enum	確認する対象：プロダクトへのリンク（ディレクトリ、AIツールのディレクトリ）またはブランドへの言及（それ以外）。指定できる値：`link_livemention_seen`
└statenull許容	enum	`confirmed`：確認できた。`unconfirmed`：1回の確認で見つからなかった（ステータスは変わりません。URLを確認してください）。`lost`：以前はあったが、なくなった（タスクは失敗になります）。指定できる値：`confirmedunconfirmedlostnull`
└checkedAtnull許容	string
└dueAtnull許容	string
└updatedAt	string
└skipped	array<object>
└targetId	string
└reason	enum	`other_product`：別のプロダクトに属する、AIに引用されている候補サイト。`inactive`：無効化された、または無視された掲載先。`locked`：無料プランで閲覧できる掲載先ライブラリの範囲外（`GET /v1/channels`が返す、相性順の上位`window`件。ご自身で追加した掲載先、お気に入り、AIに引用されているサイトは制限されません）。指定できる値：`not_foundbrokeninactiveother_productalready_openalready_submittedlocked`

発生しうるエラー

400product_id_required、name_required／name_too_long（80文字）、target_ids_required／too_many_targets（100件）、またはinvalid_date

401認証エラー

403missing_scope_publish（このキーにはpublishスコープが付与されていません）

404product_not_found（このproductIdはこのアカウントに属していません）

409quota_exceeded。レスポンス本文にdimension（active_campaigns／tasks_per_month／channels）、limit、used、requestedを含みます。channelsの場合は、period（month／total。DistributionQuota.limits.channelsPeriodと同じ）も含みます

例

bash

curl -X POST https://www.querywin.com/api/v1/campaigns \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "clx1prod000",
    "name": "Directories, September",
    "targetIds": [
      "clx1tgt001",
      "clx1tgt002"
    ]
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "ok": true,
    "failure": "no_valid_targets",
    "campaign": {
      "campaignId": "string",
      "productId": "string",
      "name": "string",
      "status": "active",
      "quota": 0,
      "startsAt": "2026-09-01T00:00:00.000Z",
      "endsAt": "2026-09-01T00:00:00.000Z",
      "counts": {
        "total": 0,
        "submitted": 0,
        "live": 0,
        "blocked": 0,
        "done": 0,
        "byStatus": null
      },
      "createdAt": "2026-09-01T00:00:00.000Z"
    },
    "tasks": [
      {
        "taskId": "string",
        "campaignId": "string",
        "productId": "string",
        "status": "planned",
        "blockedReason": "login",
        "missing": [
          "string"
        ],
        "listingUrl": "string",
        "markedBy": "user",
        "hasGenerated": true,
        "reviewDueAt": "2026-09-01T00:00:00.000Z",
        "submittedAt": "2026-09-01T00:00:00.000Z",
        "publishedAt": "2026-09-01T00:00:00.000Z",
        "verifiedAt": "2026-09-01T00:00:00.000Z",
        "next": [
          "string"
        ],
        "target": {
          "targetId": "string",
          "name": "string",
          "url": "string",
          "submitUrl": "string",
          "kind": "string",
          "source": "seed",
          "language": "string",
          "requiresBacklink": true
        },
        "check": {
          "kind": "link_live",
          "state": "confirmed",
          "checkedAt": "2026-09-01T00:00:00.000Z",
          "dueAt": "2026-09-01T00:00:00.000Z"
        },
        "updatedAt": "2026-09-01T00:00:00.000Z"
      }
    ],
    "skipped": [
      {
        "targetId": "string",
        "reason": "not_found"
      }
    ]
  }
}

GET/v1/campaigns/{id}

キャンペーンとそのタスク

キャンペーンと、そのすべてのタスクを返します。無料です。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	CampaignDetail
└campaign	Campaign
└campaignId	string
└productId	string
└name	string
└status	enum	`completed`は算出値で、すべてのタスクが掲載中、確認済み、失敗、スキップのいずれかになった状態です。指定できる値：`activecompletedarchived`
└quota	integer	キャンペーン作成時に選んだ掲載先の数。
└startsAt	string
└endsAtnull許容	string
└counts	object
└total	integer
└submitted	integer	submitted + published + verifiedの合計です。
└live	integer	published + verifiedの合計です。
└blocked	integer
└done	integer
└byStatus	object
└createdAt	string
└tasks	array<Task>
└taskId	string
└campaignId	string
└productId	string
└status	enum	`published`はご自身が報告した状態、`verified`はQueryWinが掲載ページで確認した状態です（ディレクトリとAIツールのディレクトリではリンク、それ以外では言及）。報告の際は両者を区別してください。指定できる値：`plannedpreparedin_progressblockedsubmittedpublishedverifiedfailedskipped`
└blockedReasonnull許容	enum	指定できる値：`logincaptchapaymentmissing_materialothernull`
└missing	array<string>	プロダクト情報に欠けている必須の掲載素材。ダッシュボードでプロダクト情報を補うと、タスクは自動的に準備し直されます。
└listingUrlnull許容	string
└markedBy	enum	最後にステータスを変更した主体：人（またはこのAPI）、ブラウザ拡張機能、QueryWin自身のいずれか。指定できる値：`userdevicesystem`
└hasGenerated	boolean	この掲載先向けに書き直したバージョンがあります。
└reviewDueAtnull許容	string	申請後に結果を確認する日時（submittedAtに掲載先の審査日数を足したもの）。
└submittedAtnull許容	string
└publishedAtnull許容	string
└verifiedAtnull許容	string
└next	array<string>	現在のステータスから、`POST /v1/tasks/{id}/status`で設定できるステータス。
└target	object
└targetId	string
└name	string
└url	string
└submitUrl	string
└kind	string
└source	enum	指定できる値：`seeduserrivals`
└language	string
└requiresBacklink	boolean
└checknull許容	object	掲載後に、QueryWinが掲載ページに対して行う再確認。タスクが掲載中になるまではnullです。
└kind	enum	確認する対象：プロダクトへのリンク（ディレクトリ、AIツールのディレクトリ）またはブランドへの言及（それ以外）。指定できる値：`link_livemention_seen`
└statenull許容	enum	`confirmed`：確認できた。`unconfirmed`：1回の確認で見つからなかった（ステータスは変わりません。URLを確認してください）。`lost`：以前はあったが、なくなった（タスクは失敗になります）。指定できる値：`confirmedunconfirmedlostnull`
└checkedAtnull許容	string
└dueAtnull許容	string
└updatedAt	string

発生しうるエラー

401認証エラー

404campaign_not_found

例

bash

curl "https://www.querywin.com/api/v1/campaigns/{id}" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "campaign": {
      "campaignId": "string",
      "productId": "string",
      "name": "string",
      "status": "active",
      "quota": 0,
      "startsAt": "2026-09-01T00:00:00.000Z",
      "endsAt": "2026-09-01T00:00:00.000Z",
      "counts": {
        "total": 0,
        "submitted": 0,
        "live": 0,
        "blocked": 0,
        "done": 0,
        "byStatus": null
      },
      "createdAt": "2026-09-01T00:00:00.000Z"
    },
    "tasks": [
      {
        "taskId": "string",
        "campaignId": "string",
        "productId": "string",
        "status": "planned",
        "blockedReason": "login",
        "missing": [
          "string"
        ],
        "listingUrl": "string",
        "markedBy": "user",
        "hasGenerated": true,
        "reviewDueAt": "2026-09-01T00:00:00.000Z",
        "submittedAt": "2026-09-01T00:00:00.000Z",
        "publishedAt": "2026-09-01T00:00:00.000Z",
        "verifiedAt": "2026-09-01T00:00:00.000Z",
        "next": [
          "string"
        ],
        "target": {
          "targetId": "string",
          "name": "string",
          "url": "string",
          "submitUrl": "string",
          "kind": "string",
          "source": "seed",
          "language": "string",
          "requiresBacklink": true
        },
        "check": {
          "kind": "link_live",
          "state": "confirmed",
          "checkedAt": "2026-09-01T00:00:00.000Z",
          "dueAt": "2026-09-01T00:00:00.000Z"
        },
        "updatedAt": "2026-09-01T00:00:00.000Z"
      }
    ]
  }
}

GET/v1/channels

プロダクトの申請先候補（相性の高い順）

掲載先ライブラリ（ディレクトリ、ローンチプラットフォーム、AIツールのディレクトリ、コミュニティ、記事投稿サービス）、ご自身で追加した掲載先、さらにproductIdを指定した場合は、そのプロダクトの検索キーワードに対するAIの回答ですでに引用されているサイト（source: "rivals"）を返します。productIdを指定すると関連度順に並び、各掲載先にtaskStatusが付きます（そのプロダクトに、その掲載先のタスクがすでにある場合はnull以外）。無料です。

citedByAiが示すのは、AIの回答が、自社の検索キーワードでそのサイトを引用したということです。そのサイトがプロダクトを掲載してくれるという意味ではありません。掲載を依頼するのが、タスクの役割です。

クエリパラメータ

フィールド	型	説明
productId	string	このプロダクトとの相性順に並べ、`taskStatus`を付け、AIに引用されている候補サイトも含めます。
kind	string	掲載先の種類。指定できる値：`directorylaunchai_directorycommunitycontentother`
source	string	`seed`：掲載先ライブラリ、`user`：ご自身で追加、`rivals`：このプロダクトについてAIに引用されているサイト。指定できる値：`seeduserrivals`
pricing	string	申請にかかる費用。指定できる値：`freeconditionalpaidunknown`
submitMethod	string	申請方法：フォームに入力する、コミュニティに投稿する、または紹介メールを送る。指定できる値：`formpostemail`
q	string	名前、ドメイン、トピックを検索します。
hideSubmitted	boolean	このプロダクトで、進行中または申請済みのタスクがある掲載先を除外します。`productId`が必要です。
page	integer	デフォルトは1。
pageSize	integer	デフォルトは30。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	ChannelList
└productIdnull許容	string
└items	array<Channel>
└targetId	string	`POST /v1/campaigns`の`targetIds`に渡す値。
└name	string
└url	string
└submitUrl	string	申請フォームまたは投稿ページ。AIに引用されているサイトの場合は、AIの回答で最も多く引用されているページ。
└kind	enum	指定できる値：`directorylaunchai_directorycommunitycontentother`
└submitMethod	enum	`form`：申請フォームに入力する、`post`：ご自身でコミュニティに投稿する、`email`：編集者に紹介メールを送る（アドレスはページを開いた時点でページから読み取り、保存はしません）。指定できる値：`formpostemail`
└source	enum	`seed`：掲載先ライブラリ、`user`：ご自身で追加、`rivals`：このプロダクトの検索キーワードでAIの回答に引用されているサイト。指定できる値：`seeduserrivals`
└pricingType	enum	指定できる値：`freeconditionalpaidunknown`
└priceNotenull許容	string
└language	string	`en`、`zh`、`multi`、またはAIに引用されているサイトの場合は、検索キーワードから判定した言語コード。
└topics	array<string>
└requiresAccount	boolean
└requiresBacklink	boolean
└reviewDaysnull許容	integer	通常の審査期間。この期間が過ぎたら確認するよう、タスクがお知らせします。
└siteRanknull許容	integer	公開されているTrancoリストでの世界順位（小さいほどアクセスが多い）。`null`：上位100万位の圏外。Domain Ratingではありません。
└hasFormSpec	boolean	この掲載先のフォーム項目が登録済みのため、掲載素材はその制限に正確に合わせて切り詰められます。
└relevancenull許容	integer	リクエストで指定したプロダクトとの相性スコア。並べ替えにのみ使います。
└taskStatusnull許容	string	この掲載先における、そのプロダクトの進行中または完了済みのタスク（ある場合）。`null`：まだない。
└citedByAinull許容	object	`source: "rivals"`の場合のみ。AIの回答が、列挙された検索キーワードでこのサイトを引用しました。そのサイトがプロダクトを掲載してくれる保証ではありません。掲載を依頼するのが、タスクの役割です。
└queries	integer	引用された、異なる検索キーワードの数。
└samples	integer	このサイトを引用したAI回答サンプルの数。
└searches	array<string>
└pages	array<string>	引用されたページ（引用の多い順）。ドメインしか記録していなかった古いサンプルでは空です。
└total	integer
└page	integer
└pageSize	integer
└limited	boolean	無料プランでは、デフォルトの並び順（`productId`との相性順）で先頭`window`件の掲載先だけを返し、絞り込み・検索・並べ替えのパラメータは`403 library_locked`で拒否します。`total`は掲載先ライブラリ全体の件数のままです。
└windownull許容	integer	無料プランで閲覧できる範囲の大きさです。基本は20件で、紹介リンクから新規登録した友だち1人につき20件追加されます（ご自身が紹介リンク経由で登録した場合は、さらに20件）。リストに制限がない場合は`null`です。

発生しうるエラー

401認証エラー

例

bash

curl "https://www.querywin.com/api/v1/channels" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "productId": "string",
    "items": [
      {
        "targetId": "string",
        "name": "string",
        "url": "string",
        "submitUrl": "string",
        "kind": "directory",
        "submitMethod": "form",
        "source": "seed",
        "pricingType": "free",
        "priceNote": "string",
        "language": "string",
        "topics": [
          "string"
        ],
        "requiresAccount": true,
        "requiresBacklink": true,
        "reviewDays": 0,
        "siteRank": 0,
        "hasFormSpec": true,
        "relevance": 0,
        "taskStatus": "string",
        "citedByAi": {
          "queries": 0,
          "samples": 0,
          "searches": [],
          "pages": []
        }
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0,
    "limited": true,
    "window": 0
  }
}

GET/v1/products

プロダクト一覧と、各プロダクト情報の完成度

掲載申請のパイプラインはここから始めます。ほかの掲載申請系エンドポイントは、すべてproductIdを受け取ります。completenessとmissingは、保存済みのプロダクト情報から算出します。プロダクト情報で空のフィールドは、すべての申請でも空になります。必須項目が欠けていると、プロダクト情報が埋まるまでタスクはblocked／missing_materialで止まります。プロダクト情報はGET /v1/products/{id}で取得し、PATCH /v1/products/{id}で入力してください。無料です。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	ProductList
└products	array<Product>
└productId	string
└name	string
└url	string
└domain	string
└primaryLanguage	enum	指定できる値：`enzhjakodefresptitrunlpltrarthviid`
└topics	array<string>
└completeness	integer	プロダクト情報の完成度（0〜100）。未入力のフィールドは、ダッシュボードまたはPATCH /v1/products/{id}で入力してください。
└missing	array<string>	プロダクト情報のうち、空のフィールド。それぞれが、すべての申請で空欄になります。
└sites	array<object>
└siteId	string
└domain	string
└syncedThroughnull許容	string

発生しうるエラー

401認証エラー

例

bash

curl "https://www.querywin.com/api/v1/products" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "products": [
      {
        "productId": "string",
        "name": "string",
        "url": "string",
        "domain": "string",
        "primaryLanguage": "en",
        "topics": [
          "string"
        ],
        "completeness": 0,
        "missing": [
          "string"
        ],
        "sites": [
          {
            "siteId": null,
            "domain": null,
            "syncedThrough": null
          }
        ]
      }
    ]
  }
}

POST/v1/products

プロダクトを作成

publishスコープと有料プランが必要です。公開されているホームページのURLと、任意のプロダクト名からプロダクトを作成します。プロダクト数の上限枠を使いますが、クレジットは消費しません。保存されたプロダクト情報をすべて返すので、続けてPATCH /v1/products/{id}で内容を入力してください。サイトのクロールやAIの実行は行いません。登録済みのドメインを指定すると、既存のproductIdとともに409 product_existsが返ります。レスポンスを受け取れなかった場合は、そのproductIdを再利用できます。プロダクトの初期値は編集可能な値であり、サイトについて確認済みの事実ではありません。

リクエストボディ

フィールド	型	説明
url必須	string
name	string

レスポンス201

フィールド	型	説明
success	boolean
data	ProductDetail
└name	string
└url	string
└primaryLanguage	enum	指定できる値：`enzhjakodefresptitrunlpltrarthviid`
└businessType	enum	指定できる値：`saastoolecommercecontentserviceother`
└launchStatus	enum	指定できる値：`livebeta`
└pricingModel	enum	指定できる値：`freefreemiumpaidtrial`
└taglinenull許容	object
└shortDescnull許容	object
└longDescnull許容	object
└firstCommentnull許容	object
└topics	array<string>
└promoCodenull許容	string
└videoUrlnull許容	string
└demoUrlnull許容	string
└linksnull許容	object
└webApp	string
└appStore	string
└playStore	string
└chromeExtension	string
└macos	string
└windows	string
└socialsnull許容	object
└x	string
└linkedin	string
└github	string
└instagram	string
└youtube	string
└facebook	string
└contactNamenull許容	string
└contactEmailnull許容	string
└gallery	array<string>
└productId	string
└domain	string
└thumbnailUrlnull許容	string
└completeness	integer	(0–100)
└missing	array<string>
└createdAt	string
└updatedAt	string
└sites	array<object>
└siteId	string
└domain	string
└syncedThroughnull許容	string

発生しうるエラー

400invalid_product_input、invalid_url、url_not_public

401認証エラー

403plan_required、または書き込み操作でのmissing_scope_publish

409product_exists（既存のproductIdを含む）またはproduct_limit_reached

429rate_limited（キーごとに毎分120リクエストまで）

例

bash

curl -X POST https://www.querywin.com/api/v1/products \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "name": "Example"
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "name": "string",
    "url": "string",
    "primaryLanguage": "en",
    "businessType": "saas",
    "launchStatus": "live",
    "pricingModel": "free",
    "tagline": null,
    "shortDesc": null,
    "longDesc": null,
    "firstComment": null,
    "topics": [
      "string"
    ],
    "promoCode": "string",
    "videoUrl": "string",
    "demoUrl": "string",
    "links": {
      "webApp": "string",
      "appStore": "string",
      "playStore": "string",
      "chromeExtension": "string",
      "macos": "string",
      "windows": "string"
    },
    "socials": {
      "x": "string",
      "linkedin": "string",
      "github": "string",
      "instagram": "string",
      "youtube": "string",
      "facebook": "string"
    },
    "contactName": "string",
    "contactEmail": "string",
    "gallery": [
      "string"
    ],
    "productId": "string",
    "domain": "string",
    "thumbnailUrl": "string",
    "completeness": 0,
    "missing": [
      "string"
    ],
    "createdAt": "2026-09-01T00:00:00.000Z",
    "updatedAt": "2026-09-01T00:00:00.000Z",
    "sites": [
      {
        "siteId": "string",
        "domain": "string",
        "syncedThrough": "string"
      }
    ]
  }
}

PATCH/v1/products/{id}

プロダクト情報を入力・更新

publishスコープが必要です。送信したフィールドだけを即座に保存します。オブジェクト（各言語のテキストを含む）と配列はフィールド全体を置き換えるため、ほかの言語を残すには、先にプロダクト情報を取得してください。クレジットの消費やAIによる生成はありません。申請前の掲載素材は非同期で更新されます。確かな事実だけを使い、不足しているプロダクト情報を推測で補わないでください。

リクエストボディ

フィールド	型	説明
name	string
url	string
primaryLanguage	enum	指定できる値：`enzhjakodefresptitrunlpltrarthviid`
businessType	enum	指定できる値：`saastoolecommercecontentserviceother`
launchStatus	enum	指定できる値：`livebeta`
pricingModel	enum	指定できる値：`freefreemiumpaidtrial`
tagline	object
shortDesc	object
longDesc	object
firstComment	object
topics	array<string>
promoCode	string
videoUrl	string
demoUrl	string
links	object
└webApp	string
└appStore	string
└playStore	string
└chromeExtension	string
└macos	string
└windows	string
socials	object
└x	string
└linkedin	string
└github	string
└instagram	string
└youtube	string
└facebook	string
contactName	string
contactEmail	string
gallery	array<string>

レスポンス200

フィールド	型	説明
success	boolean
data	ProductDetail
└name	string
└url	string
└primaryLanguage	enum	指定できる値：`enzhjakodefresptitrunlpltrarthviid`
└businessType	enum	指定できる値：`saastoolecommercecontentserviceother`
└launchStatus	enum	指定できる値：`livebeta`
└pricingModel	enum	指定できる値：`freefreemiumpaidtrial`
└taglinenull許容	object
└shortDescnull許容	object
└longDescnull許容	object
└firstCommentnull許容	object
└topics	array<string>
└promoCodenull許容	string
└videoUrlnull許容	string
└demoUrlnull許容	string
└linksnull許容	object
└webApp	string
└appStore	string
└playStore	string
└chromeExtension	string
└macos	string
└windows	string
└socialsnull許容	object
└x	string
└linkedin	string
└github	string
└instagram	string
└youtube	string
└facebook	string
└contactNamenull許容	string
└contactEmailnull許容	string
└gallery	array<string>
└productId	string
└domain	string
└thumbnailUrlnull許容	string
└completeness	integer	(0–100)
└missing	array<string>
└createdAt	string
└updatedAt	string
└sites	array<object>
└siteId	string
└domain	string
└syncedThroughnull許容	string

発生しうるエラー

400invalid_product_input、invalid_url、url_not_public、invalid_email、またはinvalid_gallery

401認証エラー

403plan_required、または書き込み操作でのmissing_scope_publish

404product_not_found

409product_exists（既存のproductIdを含む）

429rate_limited（キーごとに毎分120リクエストまで）

例

bash

curl -X PATCH https://www.querywin.com/api/v1/products/{id} \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tagline": {
      "en": "Your product tagline",
      "zh": "你的产品标语"
    },
    "shortDesc": {
      "en": "A factual description of the product."
    },
    "topics": [
      "productivity",
      "developer-tools"
    ],
    "contactEmail": "hello@example.com"
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "name": "string",
    "url": "string",
    "primaryLanguage": "en",
    "businessType": "saas",
    "launchStatus": "live",
    "pricingModel": "free",
    "tagline": null,
    "shortDesc": null,
    "longDesc": null,
    "firstComment": null,
    "topics": [
      "string"
    ],
    "promoCode": "string",
    "videoUrl": "string",
    "demoUrl": "string",
    "links": {
      "webApp": "string",
      "appStore": "string",
      "playStore": "string",
      "chromeExtension": "string",
      "macos": "string",
      "windows": "string"
    },
    "socials": {
      "x": "string",
      "linkedin": "string",
      "github": "string",
      "instagram": "string",
      "youtube": "string",
      "facebook": "string"
    },
    "contactName": "string",
    "contactEmail": "string",
    "gallery": [
      "string"
    ],
    "productId": "string",
    "domain": "string",
    "thumbnailUrl": "string",
    "completeness": 0,
    "missing": [
      "string"
    ],
    "createdAt": "2026-09-01T00:00:00.000Z",
    "updatedAt": "2026-09-01T00:00:00.000Z",
    "sites": [
      {
        "siteId": "string",
        "domain": "string",
        "syncedThrough": "string"
      }
    ]
  }
}

GET/v1/products/{id}

プロダクト情報をすべて取得

保存済みの各言語のテキスト、リンク、連絡先、画像、完成度、未入力のフィールドを返します。readスコープで利用でき、クレジットは消費しません。このワークスペースに属さないプロダクトを指定した場合も、product_not_foundが返ります。

レスポンス200

フィールド	型	説明
success	boolean
data	ProductDetail
└name	string
└url	string
└primaryLanguage	enum	指定できる値：`enzhjakodefresptitrunlpltrarthviid`
└businessType	enum	指定できる値：`saastoolecommercecontentserviceother`
└launchStatus	enum	指定できる値：`livebeta`
└pricingModel	enum	指定できる値：`freefreemiumpaidtrial`
└taglinenull許容	object
└shortDescnull許容	object
└longDescnull許容	object
└firstCommentnull許容	object
└topics	array<string>
└promoCodenull許容	string
└videoUrlnull許容	string
└demoUrlnull許容	string
└linksnull許容	object
└webApp	string
└appStore	string
└playStore	string
└chromeExtension	string
└macos	string
└windows	string
└socialsnull許容	object
└x	string
└linkedin	string
└github	string
└instagram	string
└youtube	string
└facebook	string
└contactNamenull許容	string
└contactEmailnull許容	string
└gallery	array<string>
└productId	string
└domain	string
└thumbnailUrlnull許容	string
└completeness	integer	(0–100)
└missing	array<string>
└createdAt	string
└updatedAt	string
└sites	array<object>
└siteId	string
└domain	string
└syncedThroughnull許容	string

発生しうるエラー

401認証エラー

403plan_required、または書き込み操作でのmissing_scope_publish

404product_not_found

429rate_limited（キーごとに毎分120リクエストまで）

例

bash

curl "https://www.querywin.com/api/v1/products/{id}" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "name": "string",
    "url": "string",
    "primaryLanguage": "en",
    "businessType": "saas",
    "launchStatus": "live",
    "pricingModel": "free",
    "tagline": null,
    "shortDesc": null,
    "longDesc": null,
    "firstComment": null,
    "topics": [
      "string"
    ],
    "promoCode": "string",
    "videoUrl": "string",
    "demoUrl": "string",
    "links": {
      "webApp": "string",
      "appStore": "string",
      "playStore": "string",
      "chromeExtension": "string",
      "macos": "string",
      "windows": "string"
    },
    "socials": {
      "x": "string",
      "linkedin": "string",
      "github": "string",
      "instagram": "string",
      "youtube": "string",
      "facebook": "string"
    },
    "contactName": "string",
    "contactEmail": "string",
    "gallery": [
      "string"
    ],
    "productId": "string",
    "domain": "string",
    "thumbnailUrl": "string",
    "completeness": 0,
    "missing": [
      "string"
    ],
    "createdAt": "2026-09-01T00:00:00.000Z",
    "updatedAt": "2026-09-01T00:00:00.000Z",
    "sites": [
      {
        "siteId": "string",
        "domain": "string",
        "syncedThrough": "string"
      }
    ]
  }
}

POST/v1/products/{id}/images/from-url

URLからプロダクト画像をインポート

publishスコープが必要です。HTTP(S)で公開されている画像を取得し、そのコピーをサムネイル（現在の画像を置き換え）またはギャラリー（末尾に追加、最大6枚）として保存します。対応形式はJPEG、PNG、WebP、SVGで、サイズは4MBまでです。SVGはPNGに変換されます。プライベートネットワークへのアクセスや安全でないリダイレクトは、既存の画像取得処理がブロックします。クレジットは消費しません。ギャラリーへのインポートを繰り返すと、同じ画像が重複することがあります。レスポンスを受け取れなかった場合は、再試行する前にGETでプロダクトを取得し直してください。

リクエストボディ

フィールド	型	説明
url必須	string
kind	enum	指定できる値：`thumbnailgallery`デフォルト値： `gallery`

レスポンス200

フィールド	型	説明
success	boolean
data	ProductDetail
└name	string
└url	string
└primaryLanguage	enum	指定できる値：`enzhjakodefresptitrunlpltrarthviid`
└businessType	enum	指定できる値：`saastoolecommercecontentserviceother`
└launchStatus	enum	指定できる値：`livebeta`
└pricingModel	enum	指定できる値：`freefreemiumpaidtrial`
└taglinenull許容	object
└shortDescnull許容	object
└longDescnull許容	object
└firstCommentnull許容	object
└topics	array<string>
└promoCodenull許容	string
└videoUrlnull許容	string
└demoUrlnull許容	string
└linksnull許容	object
└webApp	string
└appStore	string
└playStore	string
└chromeExtension	string
└macos	string
└windows	string
└socialsnull許容	object
└x	string
└linkedin	string
└github	string
└instagram	string
└youtube	string
└facebook	string
└contactNamenull許容	string
└contactEmailnull許容	string
└gallery	array<string>
└productId	string
└domain	string
└thumbnailUrlnull許容	string
└completeness	integer	(0–100)
└missing	array<string>
└createdAt	string
└updatedAt	string
└sites	array<object>
└siteId	string
└domain	string
└syncedThroughnull許容	string

発生しうるエラー

400invalid_product_inputまたはinvalid_url

401認証エラー

403plan_required、または書き込み操作でのmissing_scope_publish

404product_not_found

409gallery_full

413image_too_large

415image_type

429rate_limited（キーごとに毎分120リクエストまで）

502image_unreachable

503storage_unavailable

例

bash

curl -X POST https://www.querywin.com/api/v1/products/{id}/images/from-url \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/logo.png",
    "kind": "thumbnail"
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "name": "string",
    "url": "string",
    "primaryLanguage": "en",
    "businessType": "saas",
    "launchStatus": "live",
    "pricingModel": "free",
    "tagline": null,
    "shortDesc": null,
    "longDesc": null,
    "firstComment": null,
    "topics": [
      "string"
    ],
    "promoCode": "string",
    "videoUrl": "string",
    "demoUrl": "string",
    "links": {
      "webApp": "string",
      "appStore": "string",
      "playStore": "string",
      "chromeExtension": "string",
      "macos": "string",
      "windows": "string"
    },
    "socials": {
      "x": "string",
      "linkedin": "string",
      "github": "string",
      "instagram": "string",
      "youtube": "string",
      "facebook": "string"
    },
    "contactName": "string",
    "contactEmail": "string",
    "gallery": [
      "string"
    ],
    "productId": "string",
    "domain": "string",
    "thumbnailUrl": "string",
    "completeness": 0,
    "missing": [
      "string"
    ],
    "createdAt": "2026-09-01T00:00:00.000Z",
    "updatedAt": "2026-09-01T00:00:00.000Z",
    "sites": [
      {
        "siteId": "string",
        "domain": "string",
        "syncedThrough": "string"
      }
    ]
  }
}

GET/v1/tasks

全キャンペーンのタスク

申請履歴を、最近の動きがあった順に返します。プロダクト、キャンペーン、またはカンマ区切りのステータスで絞り込めます。byStatusは、ステータスで絞り込む前の対象タスクをすべて数えます。無料です。

クエリパラメータ

フィールド	型	説明
productId	string	このプロダクトのタスクのみ。
campaignId	string
status	string	カンマ区切り。例：`prepared,in_progress`。
page	integer	デフォルトは1。
pageSize	integer	デフォルトは30。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	TaskList
└items	array<Task>
└taskId	string
└campaignId	string
└productId	string
└status	enum	`published`はご自身が報告した状態、`verified`はQueryWinが掲載ページで確認した状態です（ディレクトリとAIツールのディレクトリではリンク、それ以外では言及）。報告の際は両者を区別してください。指定できる値：`plannedpreparedin_progressblockedsubmittedpublishedverifiedfailedskipped`
└blockedReasonnull許容	enum	指定できる値：`logincaptchapaymentmissing_materialothernull`
└missing	array<string>	プロダクト情報に欠けている必須の掲載素材。ダッシュボードでプロダクト情報を補うと、タスクは自動的に準備し直されます。
└listingUrlnull許容	string
└markedBy	enum	最後にステータスを変更した主体：人（またはこのAPI）、ブラウザ拡張機能、QueryWin自身のいずれか。指定できる値：`userdevicesystem`
└hasGenerated	boolean	この掲載先向けに書き直したバージョンがあります。
└reviewDueAtnull許容	string	申請後に結果を確認する日時（submittedAtに掲載先の審査日数を足したもの）。
└submittedAtnull許容	string
└publishedAtnull許容	string
└verifiedAtnull許容	string
└next	array<string>	現在のステータスから、`POST /v1/tasks/{id}/status`で設定できるステータス。
└target	object
└targetId	string
└name	string
└url	string
└submitUrl	string
└kind	string
└source	enum	指定できる値：`seeduserrivals`
└language	string
└requiresBacklink	boolean
└checknull許容	object	掲載後に、QueryWinが掲載ページに対して行う再確認。タスクが掲載中になるまではnullです。
└kind	enum	確認する対象：プロダクトへのリンク（ディレクトリ、AIツールのディレクトリ）またはブランドへの言及（それ以外）。指定できる値：`link_livemention_seen`
└statenull許容	enum	`confirmed`：確認できた。`unconfirmed`：1回の確認で見つからなかった（ステータスは変わりません。URLを確認してください）。`lost`：以前はあったが、なくなった（タスクは失敗になります）。指定できる値：`confirmedunconfirmedlostnull`
└checkedAtnull許容	string
└dueAtnull許容	string
└updatedAt	string
└total	integer
└page	integer
└pageSize	integer
└byStatus	object

発生しうるエラー

401認証エラー

例

bash

curl "https://www.querywin.com/api/v1/tasks" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "items": [
      {
        "taskId": "string",
        "campaignId": "string",
        "productId": "string",
        "status": "planned",
        "blockedReason": "login",
        "missing": [
          "string"
        ],
        "listingUrl": "string",
        "markedBy": "user",
        "hasGenerated": true,
        "reviewDueAt": "2026-09-01T00:00:00.000Z",
        "submittedAt": "2026-09-01T00:00:00.000Z",
        "publishedAt": "2026-09-01T00:00:00.000Z",
        "verifiedAt": "2026-09-01T00:00:00.000Z",
        "next": [
          "string"
        ],
        "target": {
          "targetId": "string",
          "name": "string",
          "url": "string",
          "submitUrl": "string",
          "kind": "string",
          "source": "seed",
          "language": "string",
          "requiresBacklink": true
        },
        "check": {
          "kind": "link_live",
          "state": "confirmed",
          "checkedAt": "2026-09-01T00:00:00.000Z",
          "dueAt": "2026-09-01T00:00:00.000Z"
        },
        "updatedAt": "2026-09-01T00:00:00.000Z"
      }
    ],
    "total": 0,
    "page": 0,
    "pageSize": 0,
    "byStatus": null
  }
}

GET/v1/tasks/{id}

タスクと、申請に使う掲載素材

掲載先のフォームが求めるすべてのフィールドを返します。値はプロダクト情報を掲載先の制限に合わせて切り詰めたもの（source: "profile"）で、掲載先向けの書き直しがあればそれ（source: "ai"）、ダッシュボードでの編集内容（source: "override"）も含みます。source: "none"は、そのフィールドに当たる内容がプロダクト情報にないことを示します。推測で埋めないでください。書き直しは一切行わず、費用もかかりません。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	TaskDetailResult
└task	TaskDetail

発生しうるエラー

401認証エラー

404task_not_found

例

bash

curl "https://www.querywin.com/api/v1/tasks/{id}" \
  -H "Authorization: Bearer $QUERYWIN_API_KEY"

json — レスポンス

{
  "success": true,
  "data": {
    "task": null
  }
}

POST/v1/tasks/{id}/materials

掲載先に合わせて掲載素材を書き直す（クレジット消費）

AIが1回の処理で、プロダクト情報をこの掲載先に合わせて書き直します。ディレクトリ向けの引き締まった説明文、メーカーとしての最初のコメント、コミュニティへの投稿、編集者への紹介メール、AIに引用されているサイトの場合は紹介メールとページの管理者が追記できる段落、のいずれかです。同期処理で、数秒で終わります。使うのはプロダクト情報にある事実だけで、プロダクト情報にないリンクを含む部分は破棄され、その分のクレジットは消費されません。

入力が同じであれば前回のバージョンが返り、クレジットは消費されません（cached: true）。force: trueを指定すると強制的に書き直し、クレジットを消費します。ディレクトリなら、GET /v1/tasks/{id}で得られるプロダクト情報ベースの掲載素材でたいてい足ります。掲載先が別の文体を求める場合に書き直してください。

検証を通った部分が何もない場合は、HTTP 200でok: falseとfailure: "engine_failed"を返します。クレジット不足は、処理結果ではなく402エラーとして返ります。

リクエストボディ

フィールド	型	説明
confirmSpend必須	integer	クレジットの承認上限。意味はアウトラインや下書きと同じです。価格は`GET /v1/usage`（`materials.pricePerTask`）で確認してください。無料枠が残っていても必須です。 (min 0)
force	boolean	前回のバージョンから何も変わっていなくても書き直します。クレジットを消費します。

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	WriteMaterialsOutcome
└ok	boolean
└failure	enum	`ok`がfalseの場合に含まれます。クレジットは消費されません。指定できる値：`engine_failedengine_unavailable`
└cached	boolean	入力に変更がなかったため、前回のバージョンを返しました。クレジットは消費されていません。
└freeUsed	boolean
└creditsSpent	integer
└task	TaskDetail

発生しうるエラー

400confirm_spend_requiredまたはconfirm_spend_too_low（レスポンス本文に現在のpriceを含む）

401認証エラー

402insufficient_credits（レスポンス本文にrequiredCredits、currentBalance、shortfallを含む）

403missing_scope_spend（このキーにはspendスコープが付与されていません）

404task_not_found

429rate_limitedまたはdaily_limit_reached（レスポンス本文にresetAtを含む）

例

bash

curl -X POST https://www.querywin.com/api/v1/tasks/{id}/materials \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmSpend": 10
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "ok": true,
    "failure": "engine_failed",
    "cached": true,
    "freeUsed": true,
    "creditsSpent": 0,
    "task": null
  }
}

POST/v1/tasks/{id}/status

申請の結果を報告

ご自身のアカウントで行った申請の結果を記録します。QueryWin自身がどこかへ申請することはありません。フォームを送信したらsubmittedに、掲載されたら掲載ページのURL（サイトのトップページではなく、掲載された項目や投稿そのもの）とともにpublishedにします。QueryWinは約72時間後にそのページを再確認し、プロダクトへのリンク（ディレクトリ、AIツールのディレクトリ）または言及（それ以外）があれば、QueryWin自身がverifiedにします。このステータスは設定できません。

blockedは「人の対応が必要」という意味で、reason（login、captcha、payment、missing_material、other）を渡します。failed／skippedはタスクを終了し、preparedは申請待ちに戻します。状態遷移のルールで許可されていない遷移は409エラー（transition_not_allowed）になります。現在のステータスから設定できるものは、タスクのnextフィールドに列挙されています。

リクエストボディ

フィールド	型	説明
status必須	enum	`verified`は設定できません。QueryWinが掲載ページを再確認したうえで設定します。指定できる値：`preparedin_progressblockedsubmittedpublishedfailedskipped`
listingUrl	string	`published`では必須：サイトのトップページではなく、公開された項目や投稿のURL。http/httpsのみ。すでに分かっている場合は、`submitted`で指定することもできます（任意）。
note	string
reason	enum	`blocked`では必須。指定できる値：`logincaptchapaymentmissing_materialother`

レスポンス200

フィールド	型	説明
success	enum	指定できる値：`true`
data	TaskDetailResult
└task	TaskDetail

発生しうるエラー

400invalid_status、listing_url_required（publishedにはlistingUrlが必要）、invalid_listing_url、またはreason_required（blockedにはreasonが必要）

401認証エラー

403missing_scope_publish（このキーにはpublishスコープが付与されていません）

404task_not_found

409transition_not_allowed（タスクを取得し、nextで許可されたステータスを確認してください）

例

bash

curl -X POST https://www.querywin.com/api/v1/tasks/{id}/status \
  -H "Authorization: Bearer $QUERYWIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "published",
    "listingUrl": "https://example-directory.com/tools/your-product"
  }'

json — レスポンス

{
  "success": true,
  "data": {
    "task": null
  }
}