REST API – Domain NSSETs

WEDOS REST API is still in development. Access and features may change without notice.

This article partially covers the Domains endpoint of WEDOS REST API. Domains and Domain contacts have their own articles. For WEDOS API (WAPI) see WAPI – WEDOS Domains.

For basic information anbout WEDOS REST API, consult the WEDOS REST API Manual.

In this article, you will find the following information:

NSSETs Endpoint Access

An NSSET is a named set of DNS servers that can be managed on its own and assigned to several domains at once (used mainly for .cz domains). This API covers NSSET management under the /v2/nssets URL prefix.

Base URL and Authentication

The base URL for the NSSETs endpoints is: https://api.wedos.com/v2

All communication runs over HTTPS, and authentication uses only OAuth2: send the header Authorization: Bearer <TOKEN> with every request. The token must have the domains scope (one shared scope for domains, contacts and NSSETs). Without valid authentication the API returns an error.

Data requests (POST/PATCH) are sent as JSON (Content-Type: application/json).

You can add the parameter example=1 to any endpoint (e.g. ?example=1, or &example=1 if the URL already contains other query parameters). Instead of executing the request, the API then returns a sample curl command for that call. Valid authentication is required even in this mode.

Endpoint Overview

MethodEndpointDescription
GET/nssets/checkCheck availability/existence of an NSSET
GET/nssets/{name}NSSET information
POST/nssetsCreate an NSSET
POST/nssets/{name}/transferTransfer an NSSET
POST/nssets/{name}/auth-info/sendSend the NSSET’s authorization code
PATCH/nssets/{name}Modify an NSSET

Response format

The API response is always a JSON object with the keys code (return code), msg (text description), request_id (request identifier) and, where applicable, data (returned data on success).

Besides the specific (business) return codes listed for each call below, all endpoints may also return these general REST-layer codes:

  • 1000 – the request was executed successfully
  • 2000 – authentication (OAuth2 Bearer token) missing or invalid
  • 2004 – maximum allowed request size exceeded (URL or request body)
  • 4000 – unknown/unsupported API method or action
  • 4001 – input data validation failed
  • 4005 – no example defined for the current URL form in example=1 mode
  • 6000 – internal error initializing request processing

GET /nssets/check

Checks whether an NSSET handle is free to use and what its status is at the registry.

Parameters:

  • tld – required, query, string – TLD for which the NSSET is checked
  • name – required, query, string – NSSET handle
  • reg_key – optional, query, string – identifier of a specific registry

Return codes:

  • 1000 – the NSSET is available for registration
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – invalid TLD
  • 2247 – unsupported NSSET format
  • 3242 – the NSSET is unavailable
  • 3245 – the NSSET is already registered
  • 3248 – NSSET unavailable – quarantine
  • 3249 – NSSET unavailable – reserved
  • 3250 – NSSET unavailable – blocked
  • 3251 – the NSSET is already registered with us
  • 4218 – check failed – communication error
  • 5001 – internal authentication error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/nssets/check?tld=cz&name=NSSET'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g1"
}

GET /nssets/{name}

Returns detailed information about an NSSET, including its DNS servers.

Parameters:

  • name – required, path – NSSET handle
  • tld – required, query, string – TLD
  • reg_key – optional, query, string – identifier of a specific registry

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – invalid TLD
  • 2209 – syntax error
  • 2247 – unsupported NSSET format
  • 3214 – failed to load the NSSET
  • 3242 – the NSSET is unavailable
  • 4204 – connection error

Response data:

  • nsset – object with NSSET details:
    • name – NSSET handle
    • status – NSSET status at the registry
    • reg_owner, reg_creator, reg_update – registrar identifiers
    • created_date, updated_date, transfer_date – creation/update/transfer dates
    • tech_c – technical contact identifier
    • dns.server – array of the NSSET’s DNS servers (name, addr_ipv4, addr_ipv6)

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/nssets/NSSET?tld=cz'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g2",
  "data": {
    "nsset": {
      "name": "NSSET",
      "status": "ok",
      "tech_c": "CONTACT",
      "created_date": "2024-01-10",
      "dns": {
        "server": [
          { "name": "ns.wedos.com", "addr_ipv4": null, "addr_ipv6": null },
          { "name": "ns.wedos.org", "addr_ipv4": null, "addr_ipv6": null }
        ]
      }
    }
  }
}

POST /nssets

Creates a new NSSET.

Parameters:

  • tld – required, string – TLD for which the NSSET is created
  • name – optional, string – requested NSSET handle; if not given, it is generated automatically
  • dns – required, array – array of DNS servers in the form [{"name":"ns1.example.com","addr_ipv4":"1.2.3.4","addr_ipv6":"..."},...] (addr_ipv4/addr_ipv6 are optional for each server; same form as in POST /domains/create)
  • tech_c – optional, string – technical contact identifier; if not given, the default is used
  • reg_key – optional, string – identifier of a specific registry

Return codes:

  • 1000 – OK, NSSET created
  • 2100 – required parameter missing
  • 2101 – invalid input parameter format
  • 2201 – incorrectly specified TLD
  • 2210 – invalid DNS server array format
  • 2211 – too many DNS servers
  • 2216 – invalid contact syntax
  • 2247 – unsupported NSSET format
  • 3228 – the registry does not support contacts
  • 3229 – error loading the contact
  • 3242 – the NSSET is unavailable
  • 3244 – NSSET creation failed
  • 3245 – the NSSET is already registered
  • 4212 – connection error
  • 4218, 4219 – check/creation failed – communication error

Response data:

  • nsset – handle of the created NSSET

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets' \
  --data '{
    "tld": "cz",
    "dns": [
      { "name": "ns.wedos.com" },
      { "name": "ns.wedos.org" }
    ]
  }'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g3",
  "data": {
    "nsset": "NSSET"
  }
}

POST /nssets/{name}/transfer

Transfers an NSSET to us from another registrar.

Parameters:

  • name – required, path – NSSET handle
  • tld – required, string – TLD
  • auth_info – required, string – the NSSET’s authorization code
  • reg_key – optional, string – identifier of a specific registry

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – unsupported TLD
  • 2215 – auth_info missing
  • 2247 – invalid NSSET name
  • 2249 – NSSET transfer is not allowed for this TLD
  • 3214 – failed to load the NSSET
  • 3242 – NSSET not supported
  • 3251 – the NSSET is already registered with the target registrar
  • 3255 – authorization error
  • 3256 – NSSET transfer failed
  • 4221 – transfer failed – connection error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets/NSSET/transfer' \
  --data '{"tld": "cz", "auth_info": "AUTHCODE123"}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g4"
}

POST /nssets/{name}/auth-info/send

Sends the NSSET’s authorization code to the technical contact’s e-mail.

Parameters:

  • name – required, path – NSSET handle
  • tld – required, string – TLD
  • reg_key – optional, string – identifier of a specific registry

Return codes:

  • 1000 – OK, authorization code sent to the contact e-mail
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – unsupported TLD
  • 2243 – sending the authorization code is not allowed for this NSSET
  • 3214 – failed to load the NSSET
  • 3217 – sending the authorization code failed
  • 3242 – the NSSET is unavailable
  • 4222 – sending failed – connection error
  • 5001 – internal authorization error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets/NSSET/auth-info/send' \
  --data '{"tld": "cz"}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g5"
}

PATCH /nssets/{name}

Modifies an existing NSSET – its DNS servers, technical contact, or test scope.

Parameters:

  • name – required, path – NSSET handle
  • tld – required, string – TLD
  • dns – required, array – array of DNS servers in the same form as in POST /nssets
  • auth_info – required, string – the NSSET’s authorization code
  • tech_c – optional, string – technical contact identifier; if not given, it stays unchanged
  • reg_key – optional, string – identifier of a specific registry
  • report_level – optional – scope of the tests the registry performs during the modification

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – incorrectly specified TLD
  • 2209 – syntax error
  • 2210 – invalid DNS server array format
  • 2211 – too many DNS servers
  • 2216 – invalid contact syntax
  • 2247 – invalid NSSET
  • 3214 – failed to load the NSSET
  • 3242 – the NSSET is not supported by this domain/registry
  • 3252 – authorization error
  • 3254 – NSSET modification failed
  • 4204, 4220 – NSSET unavailable/modification failed – connection error
  • 4212 – contact unavailable – connection error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X PATCH -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets/NSSET-1' \
  --data '{
    "tld": "cz",
    "auth_info": "AUTHCODE123",
    "dns": [
      { "name": "ns.wedos.com" },
      { "name": "ns.wedos.org" }
    ]
  }'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g6"
}

Notes

  • The endpoints under /v2/domains, /v2/contacts and /v2/nssets are handled by one shared server class and all share one OAuth2 scope, domains. From the client’s point of view, they are three logically separate but administratively unified APIs.
  • The dns parameter is given as a plain array of objects {"name": "...", "addr_ipv4": "...", "addr_ipv6": "..."}. Internally, it is converted to the legacy format used by older API versions before the WAPI call. The addr_ipv4 and addr_ipv6 items are optional for each server.
  • For NSSETs, tld is always a required parameter, because the same handle (name) may in theory exist at several registries, and the validation/format of the data differs by TLD/registry.

Was this helpful?

Thanks for your feedback!
Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Article TOC
Browse Categories