RoboWhois API v1 Documentation

This describes the resources that make up the official RoboWhois API v1. If you have any problems or requests please contact please contact support.

URL

All API access is over HTTPS, and accessed from the api.robowhois.com domain.

In order to maintain compatibility in the future, all requests must specify an API version, which is appended to the URL.

$ curl -i https://api.robowhois.com/v1/

Current Version

The current API version is v1.

Schema

The RoboWhois API is implemented as vanilla JSON over HTTP. You can explore the API through a regular browser or using an HTTP client.

Blank fields are included as null instead of being omitted.

Authentication

Authentication is managed using HTTP Basic authentication. Every request must include the Authorization HTTP header.

Use your API key as the username, and X (or some otherwise bogus text) as the password (only the API key is used for authenticating API requests).

$ curl -u "05d4dd2c1b3335c75f50:X" https://api.robowhois.com/v1/account
The API key represents your password for use with web services, so don't distribute it - that would be like giving your password away.

HTTP Verbs

Where possible, RoboWhois strives to use appropriate HTTP verbs for each action. The HTTP verb to use for a specific action is indicated in the action reference, as follows:

GET /account

Response Codes

RoboWhois uses conventional HTTP response codes to indicate success or failure of an API request.

  • 200 OK - Everything worked as expected.
  • 400 Bad Request - Often a required parameter is invalid.
  • 401 Unauthorized - No valid API key provided.
  • 402 Payment Required - You exceeded your plan limits.
  • 404 Not Found - The requested item doesn’t exist.
  • 500, 502, 503, 504 Server errors - something went wrong on RoboWhois’s end.

Visit the Errors page to learn more about error codes and meanings.

Credits

Pay-as-you-go plans use a credit allocation system. You can purchase credits and use them when you want.

All API requests cost one credit unless otherwise specified. If you do not have enough credits to make an API request you will receive a 402 response.

You can check the status of your credits using the account API.

$ curl -u "<API_KEY>:X" https://api.robowhois.com/v1/account

{
  "account": {
    "id": "4ef12dbfca71cce5fd000001",
    "email": "email@example.com",
    "api_token": "0123456789",
    "credits_remaining": 480
  }
}

In addition, each request made to our APIs, successful or not, contains credit information in the HTTP response headers. Look for the following keys:

X-CreditLimit-Remaining: 500
Credit system doesn't apply to monthly plans.

Examples

The majority of the examples in this documentation use the curl command line tool.

$ curl -u "<API_KEY>:X" https://api.robowhois.com/v1/account

The output is formatted using the jsonpretty command line utility.

$ curl -u "<API_KEY>:X" https://api.robowhois.com/v1/account | jsonpretty

{
  "account": {
    "id": "4ef12dbfca71cce5fd000001",
    "email": "email@example.com",
    "api_token": "0123456789",
    "credits_remaining": 480
  }
}