REST API Reference

Base URL: https://api.nsin.ir — authenticate every request with an API key via Authorization: Bearer nsin_… or X-Api-Key.

A key acts as your account: domains you own and domains shared with you are reachable exactly as in the panel, and domain-level roles still apply on top. Read-only keys may only call GET endpoints. Account (/users), admin and auth endpoints are never available to API keys. You can read subscription, usage and invoice data (below), but keys can never move money — wallet top-ups and plan purchases must be done from the panel and return 403.

{domain} in a path is the domain’s id (from GET /domains/), not its name. Trailing slashes matter — use the paths exactly as written.

Account

Method	Path	Description
GET	/proxy-ip/	The edge IP to point proxied DNS records at

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

Domains

Method	Path	Description
GET	/domains/	List your domains (owned + shared, each with my_role)
POST	/domains/	Add a domain — body {"name":"example.com","dns_mode":"managed"} (managed or external)
GET	/domains/{domain}	One domain’s details, verification state and your permissions
PUT	/domains/{domain}	Update settings (DNS mode, cache caps/TTL, security headers)
DELETE	/domains/{domain}	Remove the domain from your account
POST	/domains/{domain}/enable	Activate the domain once nameservers point at NSIN
POST	/domains/{domain}/check-ns	Re-check delegation now instead of waiting for the ticker
POST	/domains/{domain}/verify	Start ownership verification (TXT token)
POST	/domains/{domain}/verify/retry	Retry a failed verification
POST	/domains/{domain}/developer-mode	Enable developer mode (temporarily bypass the edge cache)
DELETE	/domains/{domain}/developer-mode	Disable developer mode

curl -X POST -H "X-Api-Key: $NSIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"example.com","dns_mode":"managed"}' \
  https://api.nsin.ir/domains/

DNS records

Method	Path	Description
GET	/domains/{domain}/records/	List records (ids, proxy status, TTL)
POST	/domains/{domain}/records/	Create a record
PUT	/domains/{domain}/records/{id}	Update a record (omitted fields unchanged)
DELETE	/domains/{domain}/records/{id}	Delete a record
GET	/domains/{domain}/records/scan	Scan public DNS for existing records before import
POST	/domains/{domain}/records/scan-import	Import the records found by a scan
POST	/domains/{domain}/records/import/parse	Parse a pasted BIND zone file into records (preview)
POST	/domains/{domain}/records/import	Import records from a parsed zone file
POST	/domains/{domain}/records/batch-update	Update many records in one call
POST	/domains/{domain}/records/batch-delete	Delete many records in one call

# Create a proxied A record for www.example.com
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/

Record types: A, AAAA, CNAME, ANAME, TXT, MX (with mx_priority), NS, SRV, CAA, PTR, TLSA, SSHFP, URI.

SSL

Method	Path	Description
GET	/domains/{domain}/ssl/	Certificate status, expiry, issuer, SANs
POST	/domains/{domain}/ssl/	Upload your own certificate + private key
POST	/domains/{domain}/ssl/parse	Validate/inspect a certificate before uploading
POST	/domains/{domain}/ssl/issue	Trigger a Let’s Encrypt issuance for the domain

Issuing your own certificates (including wildcards) via DNS-01? The acme.sh DNS plugin drives the records API with the same key.

Rules

Every rule type shares the same seven-endpoint shape under /domains/{domain}/rules/{type}/:

Method	Path	Description
GET	/domains/{domain}/rules/{type}/	List rules of this type (in priority order)
POST	/domains/{domain}/rules/{type}/	Create a rule
PATCH	/domains/{domain}/rules/{type}/reorder	Reorder rules (body: ordered list of rule_ids)
GET	/domains/{domain}/rules/{type}/{id}	Get one rule
PUT	/domains/{domain}/rules/{type}/{id}	Update a rule
DELETE	/domains/{domain}/rules/{type}/{id}	Delete a rule
PATCH	/domains/{domain}/rules/{type}/{id}/toggle	Enable/disable a rule without deleting it

Available {type} values:

{type}	What it controls
cache	Edge cache rules — TTL, scope, path includes/excludes, cache-safety toggles
redirect	URL redirects (301/302)
rewrite	Request/response header and path rewrites
drop	Block matching requests at the edge
rate-limit	Per-client request rate limits
captcha	Challenge matching requests with a CAPTCHA
waf	Web Application Firewall rules
bot-route	Route or block traffic by bot/user-agent classification
fingerprint	TLS/HTTP fingerprint (tunnel & VPN) rules
origin_pool	Origin server pools for load balancing
origin_route	Route requests to a specific origin pool
error-page	Custom branded error pages

# List a domain's cache rules
curl -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.ir/domains/example.com/rules/cache/

# Add a 1-hour cache rule for /assets
curl -X POST -H "X-Api-Key: $NSIN_KEY" -H "Content-Type: application/json" \
  -d '{"ttl_sec":3600,"scope":"default","path_match_type":"wildcard","path_includes":["/assets/*"]}' \
  https://api.nsin.ir/domains/example.com/rules/cache/

Cache

Method	Path	Description
DELETE	/domains/{domain}/cache/	Purge the domain’s entire edge cache
GET	/cache/stats/?domain={domain}	Cached entry count and on-disk size for the domain

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

Analytics

All domain-scoped analytics take ?domain={domain} and an optional &period=; account-wide endpoints aggregate across every domain you can see. Analytics requires a plan with monitoring enabled.

Per-domain

Method	Path	Description
GET	/analytics/summary	Requests, bandwidth, visitors, cache ratio
GET	/analytics/requests	Requests over time
GET	/analytics/bandwidth	Bandwidth over time
GET	/analytics/visitors	Unique visitors over time
GET	/analytics/cache	Cache hit/miss breakdown
GET	/analytics/status-codes	Response status-code distribution
GET	/analytics/countries	Traffic by visitor country
GET	/analytics/asns	Traffic by visitor ASN
GET	/analytics/protocols	Traffic by HTTP protocol
GET	/analytics/top-uris	Most-requested URIs
GET	/analytics/top-requests	Top individual requests
GET	/analytics/origins	Traffic by origin server
GET	/analytics/user-agents	Traffic by user agent
GET	/analytics/traffic-by-cache	Bandwidth split by cache status
GET	/analytics/traffic-by-reqstatus	Bandwidth split by request status
GET	/analytics/traffic-by-node	Bandwidth split by edge node
GET	/analytics/unreachable-reasons	Why origin requests failed
GET	/analytics/waf-logs	WAF match log
GET	/analytics/logs	Recent request logs
GET	/analytics/markdown-tester	Preview Markdown-for-Agents conversion
POST	/analytics/query	Ad-hoc read-only SQL over your own request logs

Account-wide

Method	Path	Description
GET	/analytics/overview	Headline metrics across all your domains
GET	/analytics/domains-overview	Per-domain summary rows
GET	/analytics/global-summary	Combined totals
GET	/analytics/bandwidth-overview	Bandwidth across all domains
GET	/analytics/tunnel-suspects	Domains showing tunnel/VPN signatures
GET	/analytics/node-countries	Edge node locations

Periods: 1h, 6h, 24h, 7d, 30d.

curl -H "X-Api-Key: $NSIN_KEY" \
  "https://api.nsin.ir/analytics/summary?domain=example.com&period=24h"

Uptime

Origin-outage detection and history, scoped by ?domain={domain}.

Method	Path	Description
GET	/uptime	Incident history (sustained origin outages)
GET	/uptime/live	Current per-subdomain origin health
GET	/uptime/settings	Read outage-detection thresholds
PUT	/uptime/settings	Update outage-detection thresholds and alerts

Recommendations

Per-domain advisory checklist (analytics + config + live probes), scoped by ?domain={domain}.

Method	Path	Description
GET	/recommendations	List active recommendations
GET	/recommendations/count	Count of active recommendations
POST	/recommendations/dismiss	Dismiss a recommendation
DELETE	/recommendations/dismiss	Un-dismiss a recommendation

Subscriptions & billing

Read-only. Keys can inspect a domain’s plan, enabled features, traffic usage and invoices, but cannot buy, switch, renew or top up — those return 403 and must be done from the panel.

Method	Path	Description
GET	/domains/{domain}/subscription	The domain’s current subscription
GET	/domains/{domain}/subscriptions	Subscription history for the domain
GET	/domains/{domain}/subscriptions/{id}	One subscription’s details
GET	/domains/{domain}/features	Plan features enabled for the domain
GET	/domains/{domain}/traffic-usage	Traffic used against the plan allowance
GET	/domains/{domain}/invoices	Invoices for the domain
GET	/domains/{domain}/invoices/{id}	One invoice
GET	/wallet	Account wallet balance
GET	/wallet/transactions	Wallet transaction history

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

Sharing

Manage who else can access a domain. Requires the owner or an admin role on the domain.

Method	Path	Description
GET	/domains/{domain}/members	List members and their roles
PATCH	/domains/{domain}/members/{userId}	Change a member’s role
DELETE	/domains/{domain}/members/{userId}	Remove a member
GET	/domains/{domain}/invites	List pending invitations
POST	/domains/{domain}/invites	Invite by email or create a share link
POST	/domains/{domain}/invites/{inviteId}/resend	Resend an email invite
DELETE	/domains/{domain}/invites/{inviteId}	Revoke a pending invite
GET	/invites/{token}	Look up an invite by its token
POST	/invites/{token}/accept	Accept an invite

Support tickets

Method	Path	Description
GET	/tickets	List your support tickets
GET	/tickets/unread-count	Count of tickets with unread replies
POST	/tickets	Open a ticket
GET	/tickets/{id}	Read a ticket and its messages
POST	/tickets/{id}/messages	Post a reply

Errors

Errors are JSON: {"error": "message"} with conventional status codes — 400 invalid input, 401 invalid/revoked key, 403 missing permission (read-only key on a write, or insufficient domain role), 404 domain not found or not yours, 409 conflict (e.g. domain already registered), 429 rate limited (300 requests/minute per key).

Note

Prefer talking to NSIN in natural language? Connect an AI assistant through the MCP server instead — same key, same permissions.