Request and Response Formats

Request

The No-IP API follows HTTP standards. URL path segments and query parameter are expected to be percent-encoded.

The request body is always JSON format unless otherwise noted. The content-type HTTP header must be set to application/json.

Example Request with Curl

curl --user ":<api key>" \
  --header "Content-Type: application/json" \
  --data '{"zone_name": "example.com"}' \
  https://api.noip.com/v1/dns/zones

Response

The No-IP API makes use of the standard HTTP response codes to indicate success and failure. Specific possible codes are included for each resource in the API reference.

200 - 299: Success.
400 - 499: Client error; correct the error in the request and submit it again.
500 - 599: Server error; the API is experiencing problems. Our engineering team has been automatically notified.

Success

The response body of successful requests will be returned as a JSON object. If there is data in the response it will be under the data key.

{
    "data": {
        "name": "example.com",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2024-08-24T14:15:22Z"
    }
}

Other keys may exist that describe or augment the data, such as warnings and page information.

Paging

When the data key is an array a sibling key, page, will accompany it with information about the list.

page is an object with three keys,

limit: the maximum number of items in the data array.
offset: the start position of the data.
total: the total number of items available.

Example

{
    "data": [
        {
            "name": "example.com",
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2024-08-24T14:15:22Z"
        }
    ],
    "page": {
        "limit": 0,
        "offset": 0,
        "total": 10
    }
}

Warnings

A top level field warnings: [] may be included in all responses as a sibling to data: and paging:. Non-critical indications may appear here, such as approaching expirations and SPF formatting issues in TXT records.

Success Example

{
  "data": [ ... ],
  "page": { ... },
  "warnings": [
    {
      "title": "Change may not be as expected",
      "code": "W1000",
      "detail": "Request was completed but has a possibly unwanted side effect."
    }
  ]
}

Errors

Responses with HTTP codes 400 - 499 will have a JSON response body. Responses with HTTP codes 500 - 599 may have a JSON body but since they are a critical server error that cannot be guaranteed.

The errors key will always be a list of objects.

Error object fields. id, code, and title will always be included.

id: a unique string that identifies this error in our logs
code: identifies exactly in our code where the problem occurred and is very helpful in debugging
title: the main error message
detail: additional information specific to this request
location: in what part of the request the error occurred. For instance “query” for the query string.
pointer: more exact information on where the error occurred, such as a JSON pointer, if possible.

Example

{
  "errors": [{
    "id": "err_eXgLfYUj",
    "code": "2451",
    "title": "invalid request query",
    "detail": "unknown variant `summary`, expected `detail` or `name_only`",
    "location": "query"
  }, {
    "id": "err_oWfehpGt",
    "code": "3809",
    "title": "invalid url encoded request body",
  }],
}

Warnings

Non-critical indications may appear in the warnings key along with errors, such as approaching expirations and SPF formatting issues in TXT records.

Error Example

{
  "errors": [ ... ],
  "warnings": [
    {
      "title": "Resource expiring soon",
      "code": "W1001",
      "detail": "The related resource will expire soon"
    }
  ]
}