レスポンス形式

レスポンス形式

すべてのレスポンスは 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 に一覧表示されます。

例

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 呼び出しではヘッダーは読み取られません。

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 が優先されます。

/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 です。

例

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 や、信頼できる確認手段のないプラットフォームです。

{
  "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"
  }
}

不明なチェックを含むスコアとグレード

スコアは、不明なチェックを未設定として数えません。DNS セキュリティスコアとメール認証グレードは不明なチェックを除外し、それらを checks_unknown で報告して、score_confidence を partial に設定します。すべてのチェックが不明な場合、スコアとグレードは null になります。証明書を読み取れなかった場合、SSL グレードとスコアは null となり、grade_reason は certificate_not_retrieved に設定されます。評判スコアは、パーキングが不明な場合に非パーキングではなく null を報告します。