JSON API

Introduction

An API interface has been implemented for several of the tools. It is still in an early beta stage. The API has been made available to gather feedback and to support further development of the website 'under the hood'. At this point, there are still a lot of things missing, but the essentials are there, and the API is working as intended on the selected tools.

Feedback

The main purpose, of pushing the API at this point, is to gather feedback.

I hope you will share any thoughts, ideas and experiences with me.

Mail me at iamrootdottech@gmail.com - looking forward to your input!

Latest API related changes

• 2025-03-22: API documentation update
  The API description has been updated with new section added on error handling.
  
  
• 2025-03-22: API TryOut fix
  As the API TryOut feature was working from the server itself, a ratelimit error was raised allmost every time. This has been fixed.
  
  
• 2025-03-22: API response adjustment
  A MessageStatus node has been added, allowing for an overall status check of the API request and response.
  
  
• 2025-02-05: New API endpoint for DNS lookups
  An API endpoint for the DNS lookup tool has been made available.
  
  
• 2025-02-05: DNS lookup log rework
  In preparation of a DNS lookup API, the logging of the DNS lookup tool has been entirely reworked.
  
  

Next up

• Further tuning of the API, establishing common ground, and developing core concepts.
• Adding API endpoints for additional tools

Please note...

...the API will be subject to changes and updates going forward. I will make sure to detail major changes on this page, and in the sitewide changelog as well.

URL/endpoint structure

The intent is, that the URL structure of each API, has to mirror the URLs used at the website. For instance, the website URL for a WHOIS-lookup of yahoo.com, looks like this:

https://iamroot.tech/whois/?host=yahoo.com&qt=PreferRdap

The matching API request, looks like this:

https://iamroot.tech/whois/api/?host=yahoo.com&qt=PreferRdap

More tool-specific details below.

Authentication and rate limits

Authentication is done by passing an Authorization HTTP header containing an API key.

You can obtain an API key through the user system. Simply create an account, go to the API keys section, and generate as many API keys as you need. There is no limit on the number of API keys you can create.

However, there is a 24-hour rate limit. The default rate limit is currently 1000 requests per 24 hours. Upgrading or increasing your rate limit is not an option at the moment (though it will be in the future).

From the API keys section of the user system, detailed information on the latest requests is available for debugging, along with statistics on the current 24-hour API usage.

Sample http request includeing an API key:

Anonymous usage
Anonymous usage, without providing an API key in each request, is also possible. The rate limit for anonymous use is 200 requests per 24 hours.

API response wrapper

All API responses share a common JSON object on the root level. It has various status and meta info. Should be pretty straightforward to interpret.

{
    "MessageStatus":"AllGood",
    "Message": null,
    "RequestTimestamp": "2023-10-05T21:04:45.970403Z",
    "RequestServer": "horsens",
    "RequestTool": "whois",
    "RequestUuid": "09b8878f0e054808b89a4e3d125a6d07",
    "RequestExecutionTime": 1084,
    "UserUuid": null,
    "UserApikeyUuid": null,
    "UserQueryLimit24h": 500,
    "UserQueryLimit24hUsage": 196,
    "DataObjectType": "SslInfoV2Simplified",
    "Data": [...]
}

Error handling

If errors occur, the returned HTTP status will NOT necessarily reflect this. Using HTTP status codes for feedback on both the API itself and the tool execution makes it very difficult for everyone involved to determine what went wrong and why.

HTTP Errors
HTTP status errors indicate issues with the API itself, the server, the website, or other parts of the ecosystem. For instance, they may occur due to code issues, database problems, or similar failures.

If you ever receive anything other than HTTP status 200, please reach out—that is my problem to solve. Let me know, and I will fix any issues as quickly as possible.

API/Tool Errors
Issues at the tool level are reflected by the MessageStatus node. Additional details are always available via the Message node.

If you ever receive a MessageStatus other than AllGood, you will need to review your code and what you are trying to accomplish, as there is an issue. Details are available in the Message node. This may happen, for example, if you attempt to execute tools on non-existent domains, experience network latency causing timeouts during tool execution, exceed the API rate limit, or encounter similar issues.

The MessageStatus node has three possible values—no more, no less:

• AllGood - Everything is working as expected, and tool execution was successful.
• Warning - Minor warnings for informational purposes. Details are available in the Message node.
• Error - A significant error occurred for one reason or another. Details are available in the Message node.

You may read more about the WHOIS/RDAP tool at https://iamroot.tech/whois/. When using the tool in your browser, the URL of the corresponding API call is mentioned as a part of the result.

Perform WHOIS / RDAP lookup

Samples & output

Lookup of '8.8.8.8', prefer RDAP with failover to WHOIS:

Lookup of 'AS16509', force WHOIS:

You may read more about the TLS/SSL tool at https://iamroot.tech/ssl-certificate-check/. When using the tool in your browser, the URL of the corresponding API call is mentioned as a part of the result.

Perform TLS/SSL certifictae check of host

Samples & output

SSL/TLS check of 'google.com', all default settings:

SSL/TLS check of 'wrong.host.badssl.com', all default settings:

You may read more about the port scan tool at https://iamroot.tech/port-scan/. When using the tool in your browser, the URL of the corresponding API call is mentioned as a part of the result.

Perform port scan of host

Samples & output

Port scan of 'www.db4free.net':

Port scan of 'ftp.gnu.org', with additional check of port 5000:

You may read more about the DNSBL check at https://iamroot.tech/dnsbl-blacklist-checker/. When using the tool in your browser, the URL of the corresponding API call is mentioned as a part of the result.

Perform DNSBL check of host

Samples & output

DNSBL check of 'iamroot.tech':

You may read more about the DNS propagation at https://iamroot.tech/dns-propagation/. When using the tool in your browser, the URL of the corresponding API call is mentioned as a part of the result.

Perform DNSBL check of host

Samples & output

DNS propagation check of A-records of 'iamroot.tech':

You may read more about theDNS propagation at https://iamroot.tech/ping-tracert/. When using the tool in your browser, the URL of the corresponding API call is mentioned as a part of the result.

Please note that, at this point, only the ping-specific parts of the tool are available via the API.

Perform ping of host

Samples & output

Ping of 'reddit.com':

You may read more about the DNS lookup at https://iamroot.tech/dns-lookup/. When using the tool in your browser, the URL of the corresponding API call is mentioned as a part of the result.

Perform DNS lookup of domain name

Samples & output

DNS lookup for A-, AAAA- and MX-records of 'iamroot.tech':