Preview the Markdown-for-Agents conversion for one domain
const url = 'https://api.nsin.cloud/reseller/v1/domains/1/analytics/markdown-tester?path=%2F';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.nsin.cloud/reseller/v1/domains/1/analytics/markdown-tester?path=%2F' \ --header 'Authorization: Bearer <token>'Fetches one page on the domain twice — once as a browser
(Accept: text/html) and once as an agent (Accept: text/markdown) —
through the public edge, and returns both responses so the panel can
show a before/after diff and the token saving.
This is the reseller’s answer to “will turning this on break my
customer’s site”. Without it the only way to find out is to enable
markdown_for_agents on a live domain and look, which is a change to
someone else’s production site made in order to ask a question.
There is no plan gate, matching the customer surface: previewing the conversion must be possible before the feature is bought.
The fetch target is pinned to the authorized domain — hostname must be
the domain itself or one of its subdomains, path must be a path and not
a URL, redirects may not leave the domain, and bodies are capped at
256 KiB. That containment is what keeps a preview endpoint from being an
SSRF hole pointed at our own network.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Must belong to a client of the caller, or the response is 403.
Query Parameters
Section titled “Query Parameters ”Which host to fetch. Defaults to the domain apex. Must be the domain or one of its subdomains; anything else is a 400 rather than a fetch.
Path to fetch, starting with /. A full URL is rejected.
Responses
Section titled “ Responses ”Both fetches, side by side
object
The URL that was fetched
The domain’s markdown_for_agents setting at test time. With it off,
markdown.converted will be false — that is the feature not being
on, not the page failing to convert, and the two must not be reported
as the same thing.
object
The origin/edge status. 0 when the fetch itself failed — see error.
Body length as returned, after the 256 KiB cap is applied.
The body was longer than the cap and has been cut.
The body was not valid UTF-8, so body is omitted rather than mangled.
The edge’s Nsn-Cache-Status
From X-Markdown-Tokens. Absent when the edge did not count.
From X-Original-Tokens. Absent when the edge did not count.
The response came back as text/markdown.
Why the fetch failed, when it did. Present with a zero status means
nothing was reached at all — do not render that as a 0 response code.
object
The origin/edge status. 0 when the fetch itself failed — see error.
Body length as returned, after the 256 KiB cap is applied.
The body was longer than the cap and has been cut.
The body was not valid UTF-8, so body is omitted rather than mangled.
The edge’s Nsn-Cache-Status
From X-Markdown-Tokens. Absent when the edge did not count.
From X-Original-Tokens. Absent when the edge did not count.
The response came back as text/markdown.
Why the fetch failed, when it did. Present with a zero status means
nothing was reached at all — do not render that as a 0 response code.
Example generated
{ "url": "example", "feature_enabled": true, "html": { "status": 1, "content_type": "example", "content_length": 1, "body": "example", "truncated": true, "binary": true, "cache_status": "example", "markdown_tokens": 1, "original_tokens": 1, "converted": true, "error": "example" }, "markdown": { "status": 1, "content_type": "example", "content_length": 1, "body": "example", "truncated": true, "binary": true, "cache_status": "example", "markdown_tokens": 1, "original_tokens": 1, "converted": true, "error": "example" }}Malformed or invalid input.
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
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 fromPOST /servicesandPOST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default0, 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 untilPOST /domains/{domainId}/enable.unknown_rule_type— 404 from the rules paths whenruleTypeis 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.
Example
{ "error": "forbidden", "code": "credit_limit_reached"}Missing, malformed, expired, or revoked credential.
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
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 fromPOST /servicesandPOST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default0, 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 untilPOST /domains/{domainId}/enable.unknown_rule_type— 404 from the rules paths whenruleTypeis 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.
Example
{ "error": "forbidden", "code": "credit_limit_reached"}No such resource.
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
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 fromPOST /servicesandPOST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default0, 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 untilPOST /domains/{domainId}/enable.unknown_rule_type— 404 from the rules paths whenruleTypeis 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.
Example
{ "error": "forbidden", "code": "credit_limit_reached"}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.
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
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 fromPOST /servicesandPOST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default0, 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 untilPOST /domains/{domainId}/enable.unknown_rule_type— 404 from the rules paths whenruleTypeis 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.
Example
{ "error": "forbidden", "code": "credit_limit_reached"}The analytics store (ClickHouse) is unreachable.
Deliberately an error rather than a zeroed page: a page of zeros is indistinguishable from “your customers’ traffic stopped”, and someone would act on it.
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
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 fromPOST /servicesandPOST /services/{serviceId}/change-plan. Your wallet, not the client’s: funding the purchase would take you past your overdraft (default0, 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 untilPOST /domains/{domainId}/enable.unknown_rule_type— 404 from the rules paths whenruleTypeis 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.
Example
{ "error": "forbidden", "code": "credit_limit_reached"}