List gateways

GET

/domains/{domain}/gateways/

const url = 'https://api.nsin.ir/domains/example.com/gateways/?icons=url';
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.ir/domains/example.com/gateways/?icons=url' \
  --header 'Authorization: Bearer <token>'

Every gateway currently offered, each with whether it is switched on for this domain and, when it is, the record that was created for it — together with this domain’s gateway plan standing: whether gateways are included at all, and how much of the rolling 30-day allowances (requests and egress bytes) has been used. Gateways switched on earlier whose catalog entry has since been withdrawn are listed too, marked retired, so they can still be switched off. Requires domain.view.

Each entry carries its icon inline as a base64 data: URI, which is most of the response’s size. Pass icons=url to get a cacheable icon_url instead (see GET /gateway-presets/{presetId}/icon).

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

domain

required

string

The domain name (for example example.com) — not a numeric id.

Example

example.com

Query Parameters

icons

string

Allowed values: url

url returns icon_url instead of the inline icon.

Responses

200

Gateway list and quota standing.

application/json

The gateway catalog for one domain, plus that domain’s gateway quota.

Gateway traffic is metered separately from the domain’s own traffic: a plan allows a fixed number of gateway requests per ROLLING 30 days. There is no reset date — capacity returns gradually as older requests age out of the window. While the allowance is spent, only the gateway hostnames stop serving (they answer 429); the rest of the domain is unaffected.

object

items

Array<object>

One entry in the gateway catalog, plus whether it is switched on for the domain you asked about. The origin and upstream Host header behind a gateway are NSIN’s and are not exposed.

object

Pass this as gatewayId to switch the gateway on or off.

integer

title

Display name.

string

slug

Prefix of the generated hostname — the record is named <slug>-<5 digits>.

string

description

Short explanatory line. May be empty.

string

upstream

The service this gateway forwards to, e.g. api.openai.com. Sent as the Host header upstream. The origin address behind it is not exposed.

string

icon

Icon as a base64 data: URI, ready to use as an <img> source. May be empty. Empty when the list was asked for with icons=url.

string

icon_url

Only with icons=url: the icon’s content-addressed path on the API origin (/gateway-presets/{id}/icon?v=…), cacheable for a year. Empty when the gateway has no icon.

string

category

Group the gateway is filed under on the Gateways page. Empty means uncategorised.

string

enabled

Whether this gateway is currently on for this domain.

boolean

blocked

The gateway is on but its hostname is answering 429 right now, because the domain’s gateway allowance is spent (or its plan no longer includes gateways).

boolean

retired

The gateway is no longer offered but is still on for this domain. It keeps working and can be switched off; it cannot be switched on again.

boolean

record

The record created for this gateway. Absent when enabled is false.

object

Record id.

integer

name

Name relative to the domain, e.g. chatgpt-84213.

string

original_name

Fully qualified name, e.g. chatgpt-84213.example.com.

string

available

Whether the domain’s plan includes gateways. When false, switching a new gateway on is refused; gateways already on stay listed and can still be switched off.

boolean

max_requests_30d

Requests allowed in the rolling 30-day window. Null means unlimited.

integer | null

max_gb_30d

Egress allowed in the rolling 30-day window, in GB. Null means unlimited.

integer | null

requests_30d

Requests served by this domain’s gateways in the window, as of counted_at. The 429s the quota itself produces are not counted.

integer format: int64

bytes_30d

Egress bytes served by the gateways in the same window. A meter for the allowance, not a separate charge — the bytes are billed as the domain’s ordinary traffic.

integer format: int64

quota_exceeded

Whether an allowance is currently spent, so the gateways are answering 429.

boolean

quota_reason

Which allowance ran out. Absent while neither has.

string

Allowed values: requests bytes

counted_at

When the count was last recomputed. Absent before the first count.

string format: date-time

dns_mode

This domain’s DNS mode. Gateways need managed: on an external domain the record would live in a zone NSIN does not serve, so switching one on is refused whatever the plan says. Gateways already on stay listed and can still be switched off.

string

Allowed values: managed external

Example

{
  "items": [
    {
      "upstream": "api.push.apple.com",
      "icon_url": "/gateway-presets/12/icon?v=3kx9q1m2r7a"
    }
  ],
  "quota_reason": "requests",
  "dns_mode": "managed"
}

401

Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

limited

{
  "error": "rate limit exceeded"
}