REST API

Base URL, authentication, conventions and limits for the NSIN REST API, plus where to find the full endpoint reference.

Base URL: https://api.nsin.ir
Authentication: an API key
Full reference: REST API Reference, from the OpenAPI document the API serves.

Authenticate

bash

curl -H "Authorization: Bearer nsin_your_key_here" https://api.nsin.ir/domains/
curl -H "X-Api-Key: nsin_your_key_here"            https://api.nsin.ir/domains/

A key acts as you: your domains, plus domains shared with you, roles on top. Read-only keys may only issue GET, HEAD, OPTIONS — plus POST /analytics/query, which writes nothing. GET /whoami tells you which kind of key you hold.

Conventions

{domain} is the domain name, not a numeric id:

bash

curl -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.ir/domains/example.com/records/

Trailing slashes matter: /domains/ and /domains/{domain}/records/ have one; /domains/{domain} doesn't.

Errors: {"error": "human readable message"}. Timestamps: RFC 3339 UTC. Byte counts: bytes.

What a key cannot do

Blocked for every key, so a leak can't spend money:

Surface	Why
`/users/**`	Profile, password, sessions, keys — can't mint or revoke keys.
`/auth/**`	Login, registration, OTP.
`/billing/**`	Plan catalogue, billing settings.
`/admin/**`	Admin surface.
`POST /wallet/topup`, `…/subscriptions/purchase`, `/switch`, `/auto-renew`	Moves money.
`PUT /domains/{domain}/billing-member`	Picks whose wallet pays.

Reading traffic usage, invoices and wallet state is fine — only writes are blocked.

Rate limits and status codes

300 requests/minute per key — panel traffic has its own limit.

Code	Meaning
`400`	Invalid input.
`401`	Missing, invalid or revoked key.
`402`	The domain has no active plan (the feature needs one).
`403`	Read-only write, wrong role, denied surface, or plan gap.
`404`	Not found, or hidden from you.
`409`	Conflict — domain exists or is disabled.
`429`	Rate limited — `{"error": "rate limit exceeded"}`.

What's in the reference

Group	Covers
Domains	Add, configure, verify, enable, remove; dev mode; NS checks.
DNS Records	CRUD, batch update/delete, zone scan, BIND import.
SSL	Status, manual issuance, custom cert upload/parsing.
Rules	15 types, 7 endpoints each (list, create, reorder, get, update, delete, toggle).
Cache	Footprint stats, browse entries, purge, refresh.
Analytics	Traffic, visitors, bandwidth, cache, status codes, geography, logs, WAF logs, ad-hoc queries.
Uptime	Outage incidents, live per-host status, detection settings.
Recommendations	Advisory checklist, dismissals.
Sharing	Members, roles, invitations.
Billing	Read-only subs, features, traffic usage, invoices, wallet.
Support	Tickets, replies.

A first request

bash

export NSIN_KEY=nsin_your_key_here

curl -H "X-Api-Key: $NSIN_KEY" https://api.nsin.ir/domains/

curl -X POST -H "X-Api-Key: $NSIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"www","type":"A","destination":"203.0.113.10","proxied":true}' \
  https://api.nsin.ir/domains/example.com/records/

curl -X DELETE -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.ir/domains/example.com/cache/