Svarsformat

Svarsformat

Alla svar är JSON. Varje domänresultat innehåller följande gemensamma fält:

• domain - Fullständigt domännamn
• available - Boolesk tillgänglighetsstatus
• source - "rdap" or "cache"
• checked_at - ISO 8601 timestamp
• error - Finns om ett fel inträffade

Svarsmetadata

Varje API-svar innehåller ett request-ID och ett aktualitetsvärde. När de är tillgängliga visar svarshuvuden även begärda, debiterade, återbetalda och återstående krediter samt din plan, gräns, återstående kapacitet och policy för hastighetsbegränsning. Ett aktualitetsvärde på unknown betyder att aktualiteten inte kunde fastställas för svaret. Det betyder inte att data är aktuell.

Fältval och kompakta svar

Lägg till fields eller compact i frågesträngen för valfri GET- eller POST-förfrågan för att få ett mindre JSON-svar. Båda är valfria. Vid POST-förfrågningar anges de i frågesträngen, inte i bodyn. Ingen av dem ändrar kreditkostnaden.

Välj fält

fields tar kommaseparerade punktsökvägar, till exempel fields=domain,classification.status,records.data. När en sökväg går genom en lista gäller den för varje objekt. Objekten behåller sin position, och ett objekt utan något valt fält blir {}. Ett null-värde längs en sökväg behålls som null.

Skicka upp till 50 sökvägar, var och en med högst 6 segment på 1 till 64 bokstäver, siffror eller understreck. Alla andra värden ger 400 INVALID_PARAMETER innan förfrågan körs, så ingenting debiteras.

Sökvägar som inte matchar något i svaret utelämnas och listas i svarsheadern X-Fields-Ignored, upp till 20 sökvägar.

Kompakta svar

compact=true tar bara bort följande, och enbart på svarets översta nivå:

• I objektet meta: served_by och tidsnycklarna duration_ms, query_time_ms, total_ms, total_time_ms, latency_ms, generation_ms och check_duration_ms. Själva objektet meta tas bort när inget annat finns kvar i det.
• warnings, caveats, notes och errors när de är tomma listor.
• request_id när det upprepar headern X-Request-Id.

Datafält, classification, nästlade objekt och listobjekt tas aldrig bort. När båda parametrarna skickas körs compact först och fields sedan.

Bara lyckade JSON-svar omformas. Felsvar, CSV-, text- och strömmade svar samt uppskattningar med dry_run returneras oförändrade. Omformade svar skickas utan indrag.

Med en Idempotency-Key ingår fields och compact i förfrågan. Ett nytt försök med samma värden returnerar det sparade, omformade svaret. Om nyckeln återanvänds med andra värden returneras 422 IDEMPOTENCY_KEY_REUSED.

MCP-verktyg accepterar samma valfria argument fields och compact. Sökvägar som inte matchar något listas i _meta.fields_ignored i verktygets resultat.

Exempel

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-nycklar (naming)

De flesta nycklar i svaren är redan snake_case, men några endpoints returnerar vissa camelCase-nycklar, till exempel registrarName i prisresultat, tldTier i värderingsfaktorer och eventDate i RDAP-händelser. Lägg till naming=snake i frågesträngen, eller skicka headern DomScan-Naming: snake, för att få alla dessa nycklar som snake_case. Utan detta behåller svaren sina nuvarande nycklar.

En nyckel ändras endast om den börjar med en liten bokstav, enbart innehåller bokstäver och siffror och har minst en versal. Varje nytt ord får ett understreck och nyckeln skrivs med små bokstäver. Akronymer hålls ihop, inklusive IPv4 och pluralformer som IPs: registrarName blir registrar_name, secureDNS blir secure_dns, ipv4Address blir ipv4_address och nameserverIPs blir nameserver_ips.

Nycklar som är data snarare än fältnamn behåller sin exakta stavning, till exempel DNS-posttyper som A och MX, betyg som A+, domännamn, headernamn och teknikernas namn. Värden ändras aldrig, och nästlade objekt och listor konverteras på alla nivåer.

Om ett objekt redan har snake_case-namnet, till exempel både fooBar och foo_bar, behåller foo_bar sitt värde och fooBar behåller sitt ursprungliga namn, så ingenting går förlorat. Nycklarnas ordning ändras inte.

Frågeparametern har företräde framför headern, så naming=default stänger av ett val via headern för en enskild förfrågan. Godkända värden är snake och default. Alla andra värden returnerar 400 INVALID_PARAMETER innan förfrågan körs, så ingenting debiteras. Svaren innehåller Vary: DomScan-Naming.

naming körs före compact och fields, så skriv sökvägarna i fields som snake_case, till exempel fields=factors.tld_tier. Felsvar är redan snake_case och ändras aldrig, och kreditkostnaden är densamma.

Med en Idempotency-Key är valet av namngivning en del av förfrågan, oavsett om det kommer från parametern eller headern, så ett nytt försök returnerar samma nycklar.

MCP-verktyg accepterar samma valfria argument naming. MCP-anrop läser inte headern.

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

Färskhetskontroll (max_age)

Endpoints som kan svara med nyligen kontrollerade data accepterar max_age, ett heltal i sekunder från 0 till 2592000 (30 dagar). Data som är äldre än max_age kontrolleras på nytt innan de returneras, och max_age=0 kontrollerar alltid på nytt. Utan max_age behåller varje endpoint sitt vanliga beteende.

Varje lyckat svar från dessa endpoints innehåller ett cache_age_s på toppnivå: åldern i sekunder på de data som användes, eller 0 när de kontrollerades på nytt. Samma värde skickas i svarshuvudet X-Cache-Age. När ett svar innehåller flera objekt, till exempel en tillgänglighetskontroll för flera domäner, är det åldern på det äldsta objektet, och objekt behåller sitt eget cache_age_s där de redan hade ett.

max_age ändrar aldrig hur ett resultat klassificeras. Ett resultat som inte kunde bekräftas förblir unknown oavsett hur nytt det är, och nya data visas aldrig som förekommande eller saknade om inte den ursprungliga kontrollen bekräftade det.

max_age ändrar inte vad en förfrågan kostar. En ny kontroll och ett svar från nyliga data kostar lika många krediter.

På /v1/status och /v1/status/bulk är tvingade nya kontroller (max_age=0) begränsade per klient för att skydda registren. Över den gränsen besvaras förfrågan som om max_age inte hade skickats, och cache_age_s visar åldern på det du fick. Ett max_age som inte är ett heltal från 0 till 2592000 returnerar 400 INVALID_PARAMETER innan förfrågan körs, så ingenting debiteras.

Endpoints som accepterar 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

Äldre cacheparametrar

Dessa parametrar fortsätter fungera och är nu föråldrade alias för max_age. Om du även skickar max_age gäller max_age.

På /v1/subdomains behåller prefer_cache också sitt beteende med enbart cache: när inget är lagrat än returnerar förfrågan 202 utan debitering och startar sökningen i bakgrunden.

MCP-verktyg för dessa endpoints accepterar samma valfria argument max_age, och deras resultat innehåller cache_age_s.

Paginering (limit och cursor)

Endpoints som returnerar långa listor accepterar limit och cursor, och varje svar innehåller has_more och next_cursor. För att hämta nästa sida upprepar du förfrågan med cursor satt till next_cursor. På sista sidan är has_more false och next_cursor null.

Utan limit returnerar varje endpoint samma antal objekt som tidigare, så befintliga förfrågningar är oförändrade. Du kan ändra limit från en sida till nästa.

Cursorer är ogenomskinliga och signerade. En cursor fungerar bara för kontot som fick den och för samma fråga, till exempel samma domän och filter. En cursor som har ändrats, tillhör ett annat konto eller skickas med andra filter returnerar 400 INVALID_CURSOR.

Sidorna följer en stabil ordning, så objekt som läggs till eller tas bort mellan förfrågningar upprepas eller hoppas inte över. På historikendpoints beskriver sammanfattningsfälten objekten på den aktuella sidan.

Varje sida är en vanlig förfrågan och kostar endpointens vanliga krediter, precis som en förfrågan med limit gjorde tidigare. Kostnadsfria endpoints förblir kostnadsfria.

Äldre parametrar fortsätter fungera: offset på /v1/email/blacklist och den numeriska pagination.next_cursor på /v1/certificates.

Exempel

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..."

Klassificeringsstatus

Endpoints som anger om något finns (domänregistrering, användarnamn i sociala medier, DNS- och e-postautentiseringsposter, security.txt, robots.txt, sitemaps, säkerhetsheaders, parkering, typosquat-registreringar och SSL-certifikat) lägger till ett classification-objekt vid sidan av sina befintliga fält. Befintliga fält behåller namn och betydelse.

• status - present, absent eller unknown. Present och absent returneras bara när kontrollen gav exakta, tillförlitliga belägg.
• reason - Returneras bara när statusen är unknown. Förklarar varför inget säkert svar var möjligt.
• evidence - Varifrån svaret kommer: source, method, observed_at och en valfri detail som http_404 eller nxdomain.
• checked_at - När DomScan skapade klassificeringen. För cachade resultat är evidence.observed_at tidigare.

Orsaker till unknown

• blocked - Målet nekade åtkomst, till exempel med HTTP 401, 403 eller en botkontroll.
• rate_limited - Målet eller registret bad oss sakta ner, till exempel med HTTP 429.
• timeout - Kontrollen blev inte klar inom sin tidsram.
• ambiguous - Ett svar kom men bevisade varken förekomst eller frånvaro, till exempel en oväntad statuskod eller en felaktigt formaterad post.
• upstream_error - Datakällan misslyckades, till exempel ett fel på DNS-servern eller ett HTTP 5xx-svar.
• unsupported - Kontrollen är inte tillgänglig för indatan, till exempel en TLD som inte stöds eller en plattform utan tillförlitlig kontroll.

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

Poäng och betyg med okända kontroller

Poäng räknar aldrig en okänd kontroll som saknad. DNS-säkerhetspoängen och betyget för e-postautentisering lämnar okända kontroller utanför, rapporterar dem i checks_unknown och sätter score_confidence till partial. När alla kontroller är okända är poängen och betyget null. SSL-betyget och SSL-poängen är null med grade_reason satt till certificate_not_retrieved när inget certifikat kunde läsas, och ryktespoängen rapporterar okänd parkering som null i stället för icke parkerad.