REST API – Domains

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. Domain contacts and NSSETs 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:

Domains Endpoint Access

This API covers domain management under the /v2/domains URL prefix. Domain contacts and NSSETs are documented in separate articles.

Base URL and Authentication

The base URL for the domains 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/domains (equivalently /domains/list)List of the customer’s domains
GET/domains/{name}Detail of one domain
GET/domains/infoDetail of one or more domains
GET/domains/checkCheck availability of domain(s) for registration
GET/domains/{name}/transfer/checkCheck whether a domain can be transferred
GET/domains/tld-periodsCheck a valid registration period for a TLD
POST/domains/createRegister a new domain
POST/domains/{name}/renewRenew a domain registration
POST/domains/{name}/transferTransfer a domain from another registrar
POST/domains/{name}/auth-info/sendSend the authorization code to the domain owner’s contact
PATCH/domains/{name}/nsset/updateChange the domain’s DNS servers / NSSET
PATCH/domains/{name}/keyset/updateSet the domain’s DNSSEC (KEYSET)

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 /domains

Returns a list of all domains of the logged-in customer, optionally filtered by status. The equivalent path GET /domains/list does the same (no change in behaviour, just an alternative URL form).

Parameters:

  • status – optional, query, string – returns only domains in the given status; if not specified, domains in all statuses are returned

Return codes:

  • 1000 – OK
  • 2101 – invalid format of parameter status
  • 2242 – unknown domain status
  • 5001 – nobody is logged in

Response data:

  • domain – array of the customer’s domains; each item contains:
    • name – domain name
    • status – domain status

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains?status=active'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "domain": [
      { "name": "domain1.tld", "status": "active" },
      { "name": "domain2.tld", "status": "active" }
    ]
  }
}

GET /domains/{name}

Returns detailed information about one domain by its name in the URL path.

Parameters:

  • name – required, path – domain name

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • 3216 – error loading domain information
  • 3222 – failed to load the domain object
  • 3223 – the domain is in another customer account
  • 4205 – registry connection error

Response data:

  • domain – object with domain information:
    • name – domain name
    • status – domain status at the registry
    • reg_owner, reg_creator, reg_update – registrar identifiers (ours/other)
    • setup_date, expiration, updated_date, transfer_date – registration/expiration/update dates
    • owner_c, admin_c, tech_c – identifiers of associated contacts (per registry)
    • dns.server – array of configured DNS servers (name, addr_ipv4, addr_ipv6)
    • dnssec_keys – configured DNSSEC keys (if any)
    • own_* (own_name, own_company, own_email, own_addr_street, …) – snapshot of the owner contact’s details at the time of the query

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains/domena1.tld'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d5",
  "data": {
    "domain": {
      "name": "domena1.tld",
      "status": "active",
      "reg_owner": "WEDOS",
      "setup_date": "2024-01-10",
      "expiration": "2027-01-10",
      "owner_c": "CONTACT-1",
      "dns": {
        "server": [
          { "name": "ns.wedos.com", "addr_ipv4": null, "addr_ipv6": null },
          { "name": "ns.wedos.org", "addr_ipv4": null, "addr_ipv6": null }
        ]
      },
      "own_name": "Esmeralda Excavadora",
      "own_email": "esmeralda@wedos.com"
    }
  }
}

GET /domains/info

Functionally the same as GET /domains/{name}, but lets you request information about several domains at once (comma-separated names) via a query parameter.

Parameters:

  • name – required, query, string – domain name, or several names separated by commas (no spaces)

Return codes:

  • 1000 – OK (for multi-domain queries the API always returns this code; the result for each domain is in its own node, see below)
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • 3216, 3222, 3223, 4205 – see GET /domains/{name}

Response data:

  • For one domain: domain – an object with the same structure as GET /domains/{name}
  • For several domains: domain – an array of objects, each additionally containing code (the processing return code for that domain) and result (its text description). In a batch query the processing status is tracked per domain, not at the level of the whole response.

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains/info?name=domain1.tld,domain2.tld'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d6",
  "data": {
    "domain": [
      { "name": "domain1.tld", "status": "active", "expiration": "2027-01-10" },
      { "name": "domain2.tld", "code": 3223, "result": "Domain belongs to another account" }
    ]
  }
}

GET /domains/check

Checks whether one or more domains are available for registration (with us, or generally according to availability at the registry).

Parameters:

  • name – required, query, string – domain name, or several names separated by commas

Return codes:

  • 1000 – the domain is available for registration (for multi-domain queries the API always returns this code; the result for each domain is in its own node, see below)
  • 2100 – parameter name missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • 2250 – check limit exceeded (locked)
  • 2251 – limit check failed
  • 3201 – the domain is already registered
  • 3203 – the domain is not available
  • 3204 – the domain is in quarantine
  • 3205 – the domain is reserved
  • 3206 – the domain is blocked (the reason – premium/trademark/reservation/short name – is given in the text description)
  • 4201 – check failed – registry connection error
  • other status codes specific to the availability check

Response data:

  • For one domain: name – the queried domain name (the check result is directly in the response’s code/msg)
  • For several domains: an array of objects, each with name, code (the check result for that domain) and result (its text description)

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains/check?name=domain1.tld,domain2.tld'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d7",
  "data": [
    { "name": "domain1.tld", "code": 3201, "result": "Domain is already registered" },
    { "name": "domain2.tld", "code": 1000, "result": "OK" }
  ]
}

GET /domains/{name}/transfer/check

Checks whether the domain can be transferred to us from another registrar, without needing to know the authorization code.

Parameters:

  • name – required, path – domain name

Return codes:

  • 1000 – the domain is available for transfer
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • 3207 – the domain is already registered with us
  • 3208 – cannot be transferred because expiration is too close
  • 3266 – cannot be transferred, the domain has expired
  • 4206 – registry connection 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/domains/domain1.tld/transfer/check'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d8"
}

GET /domains/tld-periods

Checks whether a domain under the given TLD can be registered/renewed for the given number of years.

Parameters:

  • tld – required, query, string – TLD (without the dot, e.g. cz)
  • period – required, query, integer – requested period in years

Return codes:

  • 1000 – OK, the period is valid for the TLD
  • 2100 – input parameter missing
  • 2101 – invalid input parameters
  • 2203 – the period is not valid for the TLD

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/domains/tld-periods?tld=eu&period=1'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d9"
}

POST /domains/create

Registers a new domain. You must provide exactly one of the parameters dns or nsset (to set the domain’s DNS/NSSET), never both.

Parameters:

  • name – required, string – name of the domain to register
  • period – required, integer – registration length in years
  • owner_c – required, string – identifier (handle) of the domain owner contact
  • admin_c – optional, string – identifier of the administrative contact
  • dns – optional, 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); mutually exclusive with nsset
  • nsset – optional, string – handle of an existing NSSET to assign to the domain (only for registries that support NSSETs, e.g. .cz); mutually exclusive with dns
  • rules – optional, array – confirmation of consent to the registration rules (required only for TLDs that require it)

Return codes:

  • 1000 – OK, domain registered
  • 1001 – request accepted, will be completed asynchronously
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • 2203 – invalid period
  • 2204 – parameter owner_c missing
  • 2207 – invalid format of owner_c
  • 2208 – invalid format of admin_c
  • 2209 – NSSET syntax error
  • 2210 – DNS server syntax error
  • 2211 – too many DNS servers
  • 2245 – consent to the registration terms not given
  • 3001 – invalid currency
  • 3002 – insufficient credit
  • 3211 – contact owner_c unavailable
  • 3212 – contact admin_c unavailable
  • 3221 – domain creation failed
  • 4002 – deducting credit from the account failed
  • other error codes specific to domain registration

Response data:

  • num – order number
  • expiration – domain expiration date
  • credit – credit balance after payment

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/domains/create' \
  --data '{
    "name": "domain1.tld",
    "period": 1,
    "owner_c": "CONTACT-1",
    "dns": [
      { "name": "ns.wedos.com" },
      { "name": "ns.wedos.org" }
    ]
  }'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3e1",
  "data": {
    "num": "202610010001",
    "expiration": "2027-10-01",
    "credit": "1234.50"
  }
}

POST /domains/{name}/renew

Renews the domain registration by the given number of years. This cannot be done for .eu domains – they renew automatically.

Parameters:

  • name – required, path – domain name
  • period – required, integer – number of years to renew

Return codes:

  • 1000 – OK
  • 1001 – request accepted, will be completed asynchronously
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2203 – invalid period
  • 2269 – an unpaid (new) period already exists
  • 3001 – invalid currency
  • 3002 – insufficient credit
  • 3222 – failed to open the domain
  • 3223 – the domain does not belong to this customer account
  • 3224 – domain renewal failed
  • 3265 – the domain cannot be renewed now – the number of days to expiration exceeds the allowed limit
  • 4208 – renewal failed – connection error

Response data:

  • num – order number
  • expiration – new domain expiration date
  • credit – credit balance after payment

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/domains/domain1.tld/renew' \
  --data '{"period": 1}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3e2",
  "data": {
    "num": "202610010002",
    "expiration": "2028-10-01",
    "credit": "1134.50"
  }
}

POST /domains/{name}/transfer

Transfers a domain to us from another registrar. The dns parameter works as follows: if it is not included in the request at all, the domain’s current DNS server settings are taken over automatically; false or an empty array sets the default WEDOS servers; an array of objects sets specific servers.

Parameters:

  • name – required, path – domain name
  • auth_info – required, string – the domain’s authorization code (transfer code)
  • owner_c – optional, string – identifier of the owner contact (required only for TLDs where the registry requires it)
  • dns – optional, array – array of DNS servers in the same form as in POST /domains/create
  • rules – optional, array – confirmation of consent to the rules (only for TLDs that require it)

Return codes:

  • 1000 – transfer completed successfully
  • 1001 – request accepted, will be executed asynchronously
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • 2204 – owner contact identifier missing
  • 2207 – invalid owner contact identifier
  • 2210 – invalid DNS server format
  • 2215 – auth_info missing, which is required for this TLD
  • 3001 – invalid currency
  • 3207 – the domain is already registered with us
  • 3208 – cannot be transferred because expiration is too close
  • 3219 – a pending transfer request exists for this domain
  • 3220 – the domain is already in our records
  • 3226 – domain transfer failed
  • 3227 – authorization error at the domain registry
  • 3266 – cannot be transferred, the domain has expired
  • other error codes specific to domain transfer

Response data:

  • num – order number
  • expiration – domain expiration date
  • credit – credit balance after payment

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/domains/domain1.tld/transfer' \
  --data '{"auth_info": "AUTHCODE123", "owner_c": "CONTACT-1"}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3e3",
  "data": {
    "num": "202610010003",
    "expiration": "2027-10-01",
    "credit": "1134.50"
  }
}

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

Sends the domain’s authorization code (transfer code) to the e-mail of the domain owner contact.

Parameters:

  • name – required, path – domain name

Return codes:

  • 1000 – OK, authorization code sent to the domain owner’s e-mail
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • 2243 – sending the authorization code is not allowed for this domain
  • 3209 – sending the authorization code failed
  • 3210 – sending failed – the domain is unavailable
  • 3222 – failed to load the domain
  • 3223 – the domain does not belong to this customer account
  • 4214 – sending 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>' \
  'https://api.wedos.com/v2/domains/domain1.cz/auth-info/send'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3e4"
}

PATCH /domains/{name}/nsset/update

Sets new DNS servers for the domain, or links it to an existing NSSET. You must provide exactly one of the parameters dns or nsset, never both.

Parameters:

  • name – required, path – domain name
  • dns – optional, array – array of DNS servers in the same form as in POST /domains/create; mutually exclusive with nsset
  • nsset – optional, string – handle of an existing NSSET; mutually exclusive with dns

Return codes:

  • 1000 – OK
  • 1001 – OK, executed asynchronously
  • 2100 – required parameter missing (neither dns nor nsset given)
  • 2101 – invalid parameters (both dns and nsset given, or invalid format)
  • 2201 – unsupported TLD
  • 2202 – invalid domain name
  • 2209 – NSSET syntax error
  • 2210 – DNS server syntax error
  • 2211 – too many DNS servers
  • 3214 – NSSET unavailable
  • 3222 – failed to open the domain
  • 3223 – the domain belongs to another customer account
  • 3225 – DNS/NSSET update failed
  • 3315 – identical NS servers are already set for the domain
  • 4204 – connection error (NSSET)
  • 4210 – connection error (DNS)

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/domains/domain1.tld/nsset/update' \
  --data '{
    "dns": [
      { "name": "ns.wedos.com" },
      { "name": "ns.wedos.org" }
    ]
  }'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3e5"
}

PATCH /domains/{name}/keyset/update

Sets, disables or switches DNSSEC for the domain.

Parameters:

  • name – required, path – domain name
  • keyset – required – DNSSEC setting:
    • 0 – DNSSEC disabled
    • 1 – WEDOS-managed DNSSEC
    • any other string – handle of the customer’s own KEYSET

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid parameter format
  • 2201 – unsupported TLD
  • 2202 – invalid domain name format
  • other error codes specific to DNSSEC settings

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/domains/domain1.tld/keyset/update' \
  --data '{"keyset": 1}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3e6"
}

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 (for domains and NSSETs) 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 POST /domains/create, PATCH /domains/{name}/nsset/update and POST /domains/{name}/transfer, exactly one of the dns/nsset parameters must be given. For transfer, additionally: if dns is not included in the request at all, the API automatically detects and keeps the domain’s current DNS server settings.
  • For multi-domain queries (GET /domains/info, GET /domains/check with several comma-separated names), the return code of the whole response is always 1000. Read the processing result for each domain from the code/result of its element in data.
  • In GET /domains/{name} you can, in theory, also put several comma-separated names directly into the path segment (the API passes this value to the same WAPI command as GET /domains/info). In practice, use GET /domains/info for multi-domain queries, because a single domain in the path is more readable.
  • This documentation intentionally does not cover the endpoints under /v2/domains/{name}/miniweb/... (the Miniweb add-on service). They are handled by a separate class and will be documented separately.

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