> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL. Source: https://domscan.net/ja/docs/response-format # レスポンス形式 DomScan APIですべてのレスポンスは JSON です。各ドメイン結果には次の共通フィールドが含まれます。 すべてのレスポンスは JSON です。各ドメイン結果には次の共通フィールドが含まれます。 - `domain` - 完全なドメイン名 - `available` - 可用性を示す真偽値 - `source` - "rdap" または "cache" - `checked_at` - ISO 8601 タイムスタンプ - `error` - エラーが発生した場合に含まれます ### レスポンスメタデータ 各 API レスポンスには、リクエスト ID と鮮度の値が含まれます。利用可能な場合、レスポンスヘッダーには要求・請求・返金済み・残りのクレジットに加え、レート制限プラン、上限、残り容量、ポリシーも示されます。鮮度の値が `unknown` の場合、そのレスポンスの鮮度を確認できなかったことを意味します。データが最新であるという意味ではありません。 ### フィールド選択とコンパクトレスポンス GET または POST リクエストのクエリ文字列に `fields` または `compact` を追加すると、より小さな JSON レスポンスを受け取れます。どちらも省略可能です。POST リクエストでは、ボディではなくクエリ文字列に指定します。どちらもクレジット消費は変わりません。 #### フィールドを選択する `fields` にはカンマ区切りのドットパスを指定します(例: `fields=domain,classification.status,records.data`)。パスがリストをまたぐ場合は、すべての要素に適用されます。要素の位置は維持され、選択されたフィールドを持たない要素は `{}` になります。パスの途中にある null 値は null のまま保持されます。 パスは最大 50 個まで指定でき、各パスは 1〜64 文字の英字、数字、アンダースコアからなるセグメントを最大 6 個まで含められます。これ以外の値は、リクエストの実行前に 400 INVALID_PARAMETER を返すため、課金されません。 レスポンス内のどこにも一致しなかったパスは除外され、`X-Fields-Ignored` レスポンスヘッダーに最大 20 個まで一覧表示されます。 #### コンパクトレスポンス `compact=true` が削除するのは次の項目のみで、レスポンスの最上位にあるものに限られます。 - `meta` オブジェクト内の `served_by` と、時間関連のキー `duration_ms`、`query_time_ms`、`total_ms`、`total_time_ms`、`latency_ms`、`generation_ms`、`check_duration_ms`。他に何も残らない場合は `meta` オブジェクト自体も削除されます。 - 空のリストである `warnings`、`caveats`、`notes`、`errors`。 - `X-Request-Id` ヘッダーと同じ値の `request_id`。 データフィールド、`classification`、ネストされたオブジェクト、リストの要素は削除されません。両方のパラメータを指定した場合は、compact が先に、fields が後に適用されます。 整形されるのは成功した JSON レスポンスのみです。エラーレスポンス、CSV、テキスト、ストリーミングのレスポンス、および `dry_run` の見積もりは変更されずに返されます。整形後のレスポンスはインデントなしで送信されます。 `Idempotency-Key` を使用する場合、`fields` と `compact` はリクエストの一部として扱われます。同じ値での再試行では、保存済みの整形後レスポンスが返されます。異なる値で同じキーを再利用すると 422 IDEMPOTENCY_KEY_REUSED が返されます。 MCP ツールでも、同じ省略可能な `fields` 引数と `compact` 引数を使用できます。一致しなかったパスは、ツール結果の `_meta.fields_ignored` に一覧表示されます。 #### 例 ```bash curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/dns?domain=google.com&type=TXT&fields=domain,status,records.data,records.ttl,owner&compact=true" X-Fields-Ignored: owner { "domain": "google.com", "records": [ { "data": "v=spf1 include:_spf.google.com ~all", "ttl": 300 }, { "data": "google-site-verification=abc123", "ttl": 300 } ], "status": "success" } ``` ### snake_case キー (naming) レスポンスキーのほとんどはすでに snake_case ですが、一部のエンドポイントでは camelCase のキーも返されます。たとえば、料金結果の `registrarName`、評価要因の `tldTier`、RDAP イベントの `eventDate` などです。クエリ文字列に `naming=snake` を追加するか、`DomScan-Naming: snake` ヘッダーを送信すると、これらすべてのキーが snake_case で返されます。指定しない場合、レスポンスのキーは現在のままです。 キーが変換されるのは、小文字で始まり、英字と数字のみで構成され、大文字を1つ以上含む場合に限られます。新しい単語の前にアンダースコアが入り、キー全体が小文字になります。`IPv4` のような略語や `IPs` のような複数形は、ひとまとまりのまま扱われます。`registrarName` は `registrar_name`、`secureDNS` は `secure_dns`、`ipv4Address` は `ipv4_address`、`nameserverIPs` は `nameserver_ips` になります。 フィールド名ではなくデータであるキーは、表記がそのまま保持されます。たとえば、`A` や `MX` などの DNS レコードタイプ、`A+` などのグレード、ドメイン名、ヘッダー名、テクノロジー名です。値は一切変更されず、ネストされたオブジェクトやリストはすべての階層で変換されます。 オブジェクトにすでに snake_case の名前が存在する場合、たとえば `fooBar` と `foo_bar` の両方がある場合は、`foo_bar` が元の値を保持し、`fooBar` は元の名前のまま残るため、データが失われることはありません。キーの順序も変わりません。 クエリパラメータはヘッダーより優先されるため、`naming=default` を指定すると、ヘッダーによるオプトインを1回のリクエストだけ無効にできます。指定できる値は `snake` と `default` です。それ以外の値は、リクエストの実行前に 400 INVALID_PARAMETER を返すため、課金されません。レスポンスには `Vary: DomScan-Naming` が含まれます。 `naming` は `compact` と `fields` より前に適用されるため、`fields` のパスは `fields=factors.tld_tier` のように snake_case で記述してください。エラーレスポンスはもともと snake_case で、変更されることはありません。クレジットのコストも変わりません。 `Idempotency-Key` を使用する場合、naming の指定はパラメータ経由でもヘッダー経由でもリクエストの一部として扱われるため、再試行しても同じキーが返されます。 MCP ツールも、同じ任意の `naming` 引数を受け付けます。MCP 呼び出しではヘッダーは読み取られません。 ```bash curl -H "X-API-Key: $DOMSCAN_API_KEY" -H "DomScan-Naming: snake" "https://domscan.net/v1/value?domain=example.com&fields=domain,factors.tld_tier,factors.has_hyphens" { "domain": "example.com", "factors": { "tld_tier": "premium", "has_hyphens": false } } ``` ### 鮮度の制御 (max_age) 最近確認したデータから応答できるエンドポイントは、`max_age` を受け付けます。0 から 2592000 (30日) までの整数で、単位は秒です。`max_age` より古いデータは、返す前に再確認されます。`max_age=0` を指定すると、常に最新の状態を確認します。`max_age` を指定しない場合、各エンドポイントはこれまでどおりに動作します。 これらのエンドポイントの成功レスポンスには、トップレベルに `cache_age_s` が含まれます。使用したデータの経過時間（秒）で、最新の状態を確認した場合は 0 です。同じ値が `X-Cache-Age` レスポンスヘッダーでも返されます。複数ドメインの利用可否チェックなど、レスポンスに複数の項目が含まれる場合は最も古い項目の経過時間となり、すでに `cache_age_s` を持っていた項目はそれぞれの値を保持します。 `max_age` は結果の分類を変更しません。確認できなかった結果は、どれほど新しくても `unknown` のままです。また、元のチェックで確認されていない限り、最近のデータが存在または不在として表示されることはありません。 `max_age` はリクエストの料金に影響しません。最新の確認でも、最近のデータからの回答でも、消費するクレジットは同じです。 `/v1/status` と `/v1/status/bulk` では、レジストリを保護するため、強制的な最新チェック (`max_age=0`) にクライアントごとの上限があります。上限を超えたリクエストは `max_age` が送信されなかったものとして処理され、`cache_age_s` には受け取ったデータの経過時間が示されます。0 から 2592000 までの整数ではない `max_age` は、リクエストの実行前に 400 INVALID_PARAMETER を返すため、料金は発生しません。 `max_age` を受け付けるエンドポイント: `GET /v1/status`, `POST /v1/status/bulk`, `GET /v1/subdomains`, `GET /v1/certificates`, `GET /v1/tech`, `GET /v1/categorize`, `GET /v1/identity-assets`, `GET /v1/identity-resolution`, `GET /v1/url-intelligence`, `GET /v1/agent-readiness`, `GET /v1/robots`, `GET /v1/ssl/deep-scan` #### 従来のキャッシュパラメーター これらのパラメーターは引き続き使用できますが、`max_age` の非推奨エイリアスになりました。`max_age` も同時に送信した場合は、`max_age` が優先されます。 | パラメータ | エンドポイント | 同等の指定 | | --- | --- | --- | | `prefer_cache` | `/v1/status`, `/v1/subdomains` | `max_age=2592000` | | `skip_cache` | `/v1/status`, `/v1/tech`, `/v1/categorize`, `/v1/identity-assets`, `/v1/identity-resolution`, `/v1/url-intelligence`, `/v1/agent-readiness`, `/v1/robots` | `max_age=0` | | `cache_skip` | `/v1/status` | `max_age=0` | | `cache-skip` | `/v1/status` | `max_age=0` | | `options.prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` | | `prefer_cache (body)` | `/v1/status/bulk` | `max_age=2592000` | | `options.skip_cache (body)` | `/v1/status/bulk` | `max_age=0` | | `options.cache_skip (body)` | `/v1/status/bulk` | `max_age=0` | | `options.cache-skip (body)` | `/v1/status/bulk` | `max_age=0` | | `refresh` | `/v1/ssl/deep-scan` | `max_age=0` | `/v1/subdomains` では、`prefer_cache` はキャッシュのみの動作も維持します。まだ何も保存されていない場合、リクエストは課金せずに 202 を返し、バックグラウンドで検索を開始します。 これらのエンドポイントに対応する MCP ツールも、同じ任意の引数 `max_age` を受け付け、結果に `cache_age_s` が含まれます。 ### ページネーション (limit と cursor) 長いリストを返すエンドポイントは `limit` と `cursor` を受け付け、すべてのレスポンスに `has_more` と `next_cursor` が含まれます。次のページを取得するには、`cursor` に `next_cursor` の値を設定して同じリクエストを繰り返します。最後のページでは `has_more` が false、`next_cursor` が null になります。 `limit` を指定しない場合、各エンドポイントはこれまでと同じ件数を返すため、既存のリクエストは変わりません。`limit` はページごとに変更できます。 カーソルは不透明で署名されています。カーソルは、それを受け取ったアカウントと、同じクエリ（同じドメインやフィルターなど）でのみ使用できます。編集されたカーソル、別のアカウントのカーソル、異なるフィルターと一緒に送信されたカーソルは、400 INVALID_CURSOR を返します。 ページは安定した順序に従うため、リクエストの間に項目が追加または削除されても、重複や欠落は発生しません。履歴エンドポイントでは、サマリーのフィールドは現在のページの項目について説明します。 各ページは通常のリクエストであり、`limit` を指定した従来のリクエストと同様に、そのエンドポイントの通常のクレジットがかかります。無料のエンドポイントは引き続き無料です。 従来のパラメーターも引き続き使用できます。`/v1/email/blacklist` の `offset` と、`/v1/certificates` の数値の `pagination.next_cursor` です。 | エンドポイント | デフォルトのページサイズ | limit の上限 | | --- | --- | --- | | `GET /v1/whois/history` | 50 | 100 | | `GET /v1/dns/history` | 100 | 1000 | | `GET /v1/subdomains` | 500 | 2000 | | `GET /v1/certificates` | 100 | 1000 | | `GET /v1/watchlist` | リスト全体 | 100 | | `GET /v1/watchlist/expiring` | リスト全体 | 100 | | `GET /v1/watchlist/available` | リスト全体 | 100 | | `GET /v1/brand-monitor` | リスト全体 | 100 | | `GET /v1/email/blacklist` | 1000 | 10000 | #### 例 ```bash curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20" { "domain": "example.com", "snapshots": [ "..." ], "has_more": true, "next_cursor": "eyJvIjoi..." } curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/whois/history?domain=example.com&limit=20&cursor=eyJvIjoi..." ``` ### 分類ステータス 何かが存在するかどうかを返すエンドポイント（ドメイン登録、SNS ハンドル、DNS およびメール認証レコード、security.txt、robots.txt、サイトマップ、セキュリティヘッダー、パーキング、タイポスクワット登録、SSL 証明書）は、既存のフィールドに加えて `classification` オブジェクトを返します。既存のフィールドの名前と意味は変わりません。 - `status` - `present`（存在）、`absent`（不在）、`unknown`（不明）のいずれかです。present と absent は、チェックで正確かつ信頼できる証拠が得られた場合にのみ返されます。 - `reason` - ステータスが `unknown` の場合にのみ返されます。明確な答えを出せなかった理由を示します。 - `evidence` - 回答の根拠となった情報です。`source`、`method`、`observed_at`、および `http_404` や `nxdomain` などの任意の `detail` が含まれます。 - `checked_at` - DomScan が分類を生成した日時です。キャッシュされた結果では、`evidence.observed_at` のほうが以前の日時になります。 #### unknown になる理由 - `blocked` - 対象がアクセスを拒否しました。たとえば HTTP 401、403、またはボット対策のチャレンジが返された場合です。 - `rate_limited` - 対象またはレジストリからリクエストの頻度を下げるよう求められました。たとえば HTTP 429 が返された場合です。 - `timeout` - チェックが制限時間内に完了しませんでした。 - `ambiguous` - 応答は届きましたが、存在も不在も証明できませんでした。たとえば想定外のステータスコードや不正な形式のレコードです。 - `upstream_error` - データソースで障害が発生しました。たとえば DNS サーバーの障害や HTTP 5xx 応答です。 - `unsupported` - この入力ではチェックを利用できません。たとえばサポート対象外の TLD や、信頼できる確認手段のないプラットフォームです。 ```json { "classification": { "status": "unknown", "reason": "rate_limited", "evidence": { "source": "rdap", "method": "rdap_lookup", "observed_at": "2026-10-10T09:30:00.000Z", "detail": "http_429" }, "checked_at": "2026-10-10T09:30:00.000Z" } } ``` ブロックされた、レート制限された、タイムアウトした、または失敗したチェックが absent として報告されることはありません。`unknown` は「存在しない」ではなく「後でもう一度試す」という意味で扱い、不在をその名前を取得できる証拠と見なさないでください。 #### 不明なチェックを含むスコアとグレード スコアは、不明なチェックを未設定として数えません。DNS セキュリティスコアとメール認証グレードは不明なチェックを除外し、それらを `checks_unknown` で報告して、`score_confidence` を `partial` に設定します。すべてのチェックが不明な場合、スコアとグレードは `null` になります。証明書を読み取れなかった場合、SSL グレードとスコアは `null` となり、`grade_reason` は `certificate_not_retrieved` に設定されます。評判スコアは、パーキングが不明な場合に非パーキングではなく `null` を報告します。