Discover a domain's existing records at its current DNS host

GET

/reseller/v1/domains/{domainId}/records/scan

curl --request GET \
  --url https://api.nsin.cloud/reseller/v1/domains/1/records/scan \
  --header 'Authorization: Bearer <token>'

• Production

Probes the domain’s live DNS and returns what it finds, without writing anything. This is the migration tool: it is what turns “point your NS at us” from a data-entry exercise into one click.

This is the slowest operation in the API, by a wide margin. It makes roughly 1,450 live DNS queries — 290 candidate names against five record types — and how long that takes depends entirely on how fast the domain’s current nameservers answer. Budget seconds, not milliseconds, and give this one call a client timeout far longer than you use for everything else here. A 5-second timeout will fail against a slow DNS host every time, while every other endpoint in this document answers in well under 100 ms of server time.

The scan is bounded server-side (DNS_SCAN_BUDGET_SEC, 20s by default). If the nameservers are slow enough that the budget runs out, you get back whatever was discovered by then rather than an error — a partial list is useful, and the alternative was a request that ran for two and a half minutes into a connection the proxy had already closed.

Nothing is written either way, so re-running it is free and is the right response to a result that looks short.

Authorizations

• bearerAuth

Parameters

Path Parameters

domainId

required

integer

Must belong to a client of the caller, or the response is 403.

Responses

200

The customer API’s response for the equivalent endpoint, unchanged.

These operations mount the SAME Go handlers the customer panel calls, so the body shape is defined there and is deliberately not restated here — a second copy of the DNS record or rule schema is a second thing to keep in step, and the copy is always the one that goes stale. See openapi.yaml.

Media type application/json

object

key

additional properties

any

Example ^generated

{}

401

Missing, malformed, expired, or revoked credential.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object

error

required

string

code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

• credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
• domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
• unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
• rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
• session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.

string

Example

{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

404

No such resource.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object

error

required

string

code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

• credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
• domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
• unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
• rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
• session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.

string

Example

{
  "error": "forbidden",
  "code": "credit_limit_reached"
}

500

Something failed on our side. The body carries a human sentence and never an internal detail — a live sweep of this API once returned dial tcp 127.0.0.1:9000: connect: connection refused, which is our topology rather than an error message. That is now impossible.

Distinguish it from 503. A 503 means a dependency is down and the identical request will succeed later, so retry it. A 500 means the request hit a genuine fault: retrying it unchanged will fail the same way, and it should be reported with the X-Request-Id from the response header.

Declared on every operation because every operation can reach it. It was previously declared on exactly one, which left a generated client with no branch for the answer it is most likely to be surprised by.

Media type application/json

Every error body carries error, a human-readable sentence. Some also carry code, a stable machine-readable reason — branch on that, never on the sentence, which is prose and gets reworded.

object

error

required

string

code

Present only on the failures worth branching on, and deliberately not an exhaustive enum: treat a code you do not recognise as if it were absent and fall back to the status code.

The ones that exist today:

• credit_limit_reached — 402 from POST /services and POST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default 0, i.e. past zero). Top up; do not credit the client.
• domain_disabled — 409 from a configuration write on a disabled domain (records, rules, cache, SSL, members, settings). The domain is read-only until POST /domains/{domainId}/enable.
• unknown_rule_type — 404 from the rules paths when ruleType is not one of the documented values. You get this rather than an empty array, so a typo cannot read as a rule set that happens to be empty.
• rate_limited — 429 from any route. Keyed per credential, so one runaway integration cannot lock its owner out of the dashboard.
• session_check_failed — 503, and only on calls made with a dashboard session JWT. The session could not be verified, which is not the same as knowing it is revoked, so it is retryable and the session survives. Machine tokens never see this.

string

Example

{
  "error": "forbidden",
  "code": "credit_limit_reached"
}