NAV
HTTP Python Node Java Go Ruby

Getting Started

Introduction

API Libraries

To help you get started we provide client libraries in various languages. You can find code snippets and installation instructions in your favorite environment by switching the tabs on the right.

Select programming language for installation instructions & code examples.

# Use PyPI
pip install reposify
// Get Reposify API Node client
git clone git@github.com:reposify/reposify-node.git
// Get Reposify API Java client
git clone git@github.com:reposify/reposify-java.git
// Get Reposify API GO client
git clone git@github.com:reposify/reposify-go.git
# Get Reposify API Ruby client
git clone git@github.com:reposify/reposify-ruby.git 

Reposify is discovering and learning about the world’s devices by constantly indexing all devices connected to the public Internet. Our platform enables organizations to get insights on the Internet of Things by using a simple query syntax, combined with a powerful developer API and SDKs.

Since the API is true to RESTful principles, it’s easy to interact with using any tool capable of performing HTTP requests, such as Postman or cURL. We provide a Postman collection exemplifying correct usage of our API.

Terminology

Insights are ready to be queried datasets built from millions of inter-connected devices being indexed daily.

Any inter-connected device is referred to as a Device, each Device may be running one or multiple Services (i.e database, webcam, website, router).

Authentication

# Authentication with API token as a query parameter.

curl 'https://api.reposify.com/v1' \
        -u TOKEN:
import reposify
insights = reposify.Insights(token='TOKEN')
var repsify = require("./")
ReposifyClient insights = new ReposifyClient("TOKEN");
import "github.com/reposify/reposify-go"
insights := reposify.NewInsights("TOKEN")
require 'reposify'
insights = Reposify::Insights.new("TOKEN")

To access Reposify API, all requests to all API endpoints require you to provide your API token. The most easy and convenient way is to provide the API token as a query parameter.

Response Codes

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

Code ID Meaning
200 OK Request succeeded.
201 Created Resource created, for example a new scan or export task was created.
Code ID Meaning
400 Bad Request Request invalid, validate usage and try again.
401 Unauthorized Request not authenticated, API token is missing, invalid or expired.
403 Forbidden Request not authorized, provided credentials do not provide access to specified resource.
404 Not Found Request failed, the specified resource does not exist.
405 Method Not Allowed Request failed, the specified method was not allowed.
429 Too Many Requests Request failed, wait for rate limits to reset and try again, see rate limits.
Code ID Meaning
500 Internal Server Error Something is broken. Please contact support so the Reposify team can investigate.
503 Service Unavailable The Reposify servers are up & running, but overloaded with requests. Try again later.

Pagination

Example of request with specific page number on insights search

curl 'https://api.reposify.com/v1' \
        -u TOKEN:
import reposify

# Set access token given to your account
insights = reposify.Insights(token='TOKEN')
# Perform a search by banner, get page number 5.
results = insights.search(banner = "Test", page = 5)
// Set access token given to your account
var Insight = new repsify.Insights({token:"TOKEN"})

// Perform a search by banner, get page number 5.
Insight.search({banner:"Test",page:"5"},
function(result, err){
    if(!err) {
        console.log(result);
    }
});
// Perform a search by banner, get page number 5.
InsightsSearchResponse results = client.searchInsights("Test", "", 5);
import "github.com/reposify/reposify-go"

// Set access token given to your account
insights := reposify.NewInsights("TOKEN")
// Perform a search by banner, get page number 5.
results, err := insights.Search("Test", _, 5)
require 'reposify'

# Set access token given to your account
insights = Reposify::Insights.new("TOKEN")

# Perform a search by banner, get page number 5.
results = insights.search("Welcome", nil, 5)

Example of response from insights search

{
    "devices": [
        {
            "asn": "AS5662",
            "domain": "example.com",
            "id": "089257cb-6766-4f06-9f64-c2c7f0598af5",
            "timestamp": "2016-07-21T22:09:27.809",
            "location": {
                "city": "Atlanta",
                "country_code": "us",
                "postal_code": "30348",
                "timezone": "EDT",
                "longitude": -84.38800048828125,
                "region_name": "Georgia",
                "country_name": "United states",
                "latitude": 33.749000549316406,
                "region_code": "ga",
                "area_code": "678"
            },
            "services": [
                {
                    "banner": "<html><title>Welcome</title></html>",
                    "os": "4.4.0-38-generic x86_64 x86_64 GNU/Linux",
                    "id": "bd84717a-5962-44f6-a1df-6a03fa5a6380",
                    "timestamp": "2016-07-21T22:09:27.908",
                    "type": "website",
                    "protocol": "http",
                    "name": "example.com",
                    "port": 80,
                    "transport": "tcp",
                    "version": "1.0",
                    "isp": "Turner Broadcasting", 
                    "ip_address": "151.165.220.20",
                    "smart_data": {
                       "domain": "example.com",
                       "id": "0448aeb2-be97-413b-ad8b-033472beef2d",
                       "tags": [],
                       "technologies": [],
                       "language": "cy",
                       "meta": [],
                       "timestamp": "2016-05-21T22:09:34.811"
                    }
                }
            ]
        }
    ],
    "pagination": {
        "page_count": 1,
        "page": 1,
        "total_pages": 1,
        "has_more": false
    },
    "total_count": 1
}

All requests on Insights search returns paginated results, each page holds up to 100 devicesEach device holds information about host such as ASN, location, domains and services, You can paginate through results and receive the next page by providing page parameter with selected page number (see example on the right). Each response contains pagination property with the following attributes:

Pagination Attributes

Attribute Type Description
page integer returned results page number.
page_count integer how many devices are in current returned page.
total_pages integer how many pages are available for given query.
has_more boolean indicates whether there’s more pages after the current page.

Rate Limiting

We only allow a certain number of requests per minute depending on your plan and the endpoint. As an API consumer, you should expect to be able to make the following number of requests per minute:

Plan Requests per minute
Free 5
Startup 10
Business 50
Enterprise Unlimited

Once you exceed the limit, calls will return HTTP status 429 and a message telling you that you’ve been limited.

Credits

For each plan you get credits for query and export. Credits allow you to perform an action, please note that each action’s results may be limited by a quota depending on your current account’s plan.

Insights

Insights let you to get data about devices you care about. You can get full information on devices using Search endpoint, get devices count using Count endpoint or get full dataset of devices with Export endpoint.

Filters

Using filters parameter you can make your query more accurate to get the specific results you want.

Filter syntax is “filter:value”, for example, if you want to search for devices from germany and with running operating system linux you’ll use the following filters: country:germany os:linux.

Below you can find all available filters for Search, Count and Export endpoints:

Filters

Name Type Description Example
ip_address string IP Address ip_address:150.10.5.1
cidr string CIDR address prefix ip_address:150.10.5.1/16
asn string ASN number asn:39478
isp string ISP name isp:turner
domain string Domain name domain:reposify.com
domain_extension string Domain extension domain_extension:com
country_code string Country ISO code country_code:us
country_name string Country name country_name:germany
region_name string Region name region_name:lowa
region_code string Region code region_code:515
city string City name city:new york
postal_code integer Postal code postal_code:30843
area_code string Area code area_code:“5087”
geo string GEO location geo:25.0872 115.1932
port integer Port port:80
transport string Transport layer transport:tcp
protocol string Protocol protocol:http
type string Device’s type type:router
app string Running applications app:apache
version string Related versions version:1.0
os string Operating system os:linux

Search for devices with “Welcome” text in their response, on port 80:

import reposify

# Set credentials using provided token
insights = reposify.Insights(token='TOKEN')
# Perform a search for devices return "Welcome" response on port 80
results = insights.search(banner = "Welcome", filters = "port:80")
// Set access token given to your account
var Insight = new repsify.Insights({token:"TOKEN"})

// Perform a search for devices return "Welcome" response on port 80
Insight.search({banner:"Welcome", filter:"port:80"},
function(result, err){
    if(!err) {
        console.log(result);
    }
});
// Perform a search for devices return "Welcome" response on port 80
InsightsSearchResponse results = client.searchInsights("Welcome", "port:80", 1);
import "github.com/reposify/reposify-go"

// Set credentials using provided token
insights := reposify.NewInsights("TOKEN")
// Perform a search for devices return "Welcome" response on port 80
results, err := insights.Search("Welcome", "port:80", 1)
require 'reposify'

# Set credentials using provided token
insights = Reposify::Insights.new("TOKEN")

# Perform a search for devices return "Welcome" response on port 80
results = insights.search("Welcome", "port:80", 1)

The above command returns JSON structured like this:

{
    "devices": [
    {
        "asn": "AS5662",
        "domain": "example.com",
        "id": "089257cb-6766-4f06-9f64-c2c7f0598af5",
        "timestamp": "2016-07-21T22:09:27.809",
        "location": {
            "city": "Atlanta",
            "country_code": "us",
            "postal_code": "30348",
            "timezone": "EDT",
            "longitude": -82.38800048828125,
            "region_name": "Georgia",
            "country_name": "United states",
            "latitude": 37.749000549316406,
            "region_code": "ga",
            "area_code": "678"
        },
        "services": [
            {
                "banner": "<html><title>Welcome To Router 550</title></html>",
                "os": "4.4.0-38-generic x86_64 x86_64 GNU/Linux",
                "id": "bd84717a-5962-44f6-a1df-6a03fa5a6380",
                "timestamp": "2016-05-21T22:09:27.908",
                "type": "website",
                "protocol": "http",
                "name": "example.com",
                "port": 80,
                "transport": "tcp",
                "version": "1.0",
                "smart_data": {
                    "domain": "example.com",
                    "id": "0448aeb2-be97-413b-ad8b-033472beef2d",
                    "tags": [],
                    "technologies": [],
                    "language": "eng",
                    "meta": [],
                    "timestamp": "2016-07-21T22:09:34.811"
                }
            }
        ],
        "isp": "Turner Broadcasting", 
        "ip_address": "151.165.220.20"

        // ... More Entities
        // <reposify.Device[...] ...>
        // <reposify.Device[...] ...>
    }],
    "pagination": {
        "page_count": 50,
        "page": 1,
        "total_pages": 5,
        "has_more": true
    },
    "total_count": 250
}

This endpoint perform queries on Reposify’s insights. You can query by text on devices response’s banner and by filters listed below.

HTTP Request

GET https://api.reposify.com/v1/insights/search

Query Parameters

Parameter Type Mandatory Description
token string true Your account’s access token.
banner string false Device’s response text.
filters string false Any filter listed in filters.
page integer false Query’s page number.

Count

Get total devices’ count on port 443:

import reposify

# Set credentials using provided token
insights = reposify.Insights(token='TOKEN')
# Get total devices' on port 443
results = insights.count(filters = "port:443")
// Set credentials using provided token
var Insight = new repsify.Insights({token:"TOKEN"})

// Get total devices' on port 443
Insight.count({filter:"port:443"},
function(result,err){
    if(!err)
        console.log(result);
});
// Get total devices' on port 443
InsightsCountResponse results = client.getInsightsCount("", "port:443");
import "github.com/reposify/reposify-go"

// Set credentials using provided token
insights := reposify.NewInsights("TOKEN")
// Get total devices' on port 443
results, err := insights.Count("", "port:443")
require 'reposify'

# Set credentials using provided token
insights = Reposify::Insights.new("TOKEN")
# Get total devices' on port 443
results = insights.count(nil, "port:443")

The above command returns JSON structured like this:

{
    "total_count": 158473
}

This endpoint return number of devices matched to specified banner and filters.

HTTP Request

GET https://api.reposify.com/v1/insights/count

Query Parameters

Parameter Type Mandatory Description
token string true Your account’s access token.
banner string false Device’s response text.
filters string false Any filter listed in filters.

Discovery

Discovery API allows you to scan the internet or a certain address range for devices by port and protocol. After submitting a request you will receive a job ID that you will use to poll the server until the scan is completed. Once the scan is completed you will received an email with a detailed report.

Internet

This endpoint allows to query all public devices for the specified port and protocol. Only one such request can be active at a time. Note that unlike the other endpoints this request should be done via POST.

curl --request POST \
  --url 'https://api.reposify.com/v1/scan/internet/?token=TOKEN' \
  --form port=80 \
  --form protocol=smtp
import reposify

# Set credentials using provided token
discovery = reposify.Discovery(token='TOKEN')
# Scan all devices using SMTP on port 25
response = discovery.internet(port=25, protocol='smtp')
// Set credentials using provided token
var Insight = new repsify.Insights({token:"TOKEN"})

// Scan all devices using SMTP on port 25
Discovery.internet({port:"25",protocol:"SMTP"},
function(result,err){
    if(!err)
        console.log(result);
})
// Scan all devices using SMTP on port 25
ScanResponse response = client.scanInternet("smtp", 25);
import "github.com/reposify/reposify-go"

// Set credentials using provided token
discovery := reposify.NewDiscovery("TOKEN")
// Scan all devices using SMTP on port 25
results, err := discovery.Internet("smtp", 25)
require 'reposify'

# Set credentials using provided token
discovery = Reposify::Discovery.new("TOKEN")
# Scan all devices using SMTP on port 25
results = discovery.internet("smtp", 25)

This requests will return JSON structured as follows:

{
  "job_id": "dc233e85-91ce-4f0c-a438-98fc4228731b",
  "ips": "*",
  "status": "pending"
}

Host

This endpoint allows the user to discover devices and protocols on specific IP addresses or CIDR networks. You are limited to 65536 unique address per query, and consequentially, CIDR network masks of at least 16 bits in size. You are also limited to three active queries at a time. This endpoint accepts two arguments, a list of IP addresses and a list of ports, protocols, and transports.

The list of IP addresses is a comma delimited list of IPv4 addresses and/or CIDR networks in standard CIDR notation. As mentioned before the overall number of unique addresses cannot exceed 65536. This argument is mandatory.

The second argument is a list of tuples of port, protocol and transport combinations, in that order. If transport is supplied it must represent a valid transport for the specified protocol (e.g., DNS can work over TCP or UDP but HTTP must work over TCP). In contrast, port numbers can be freely supplied and discovery will be attempted on the port-protocol-transport combination even if the port is not a usual one for the given protocol. It is also allowed to supply only port number, only protocol, or only port and protocol in a given tuple. In that case the missing arguments will be automatically inferred. This argument is optional. In case it is not provided, auto-discovery will be preformed on the supplied addresses and the correct port-protocol-transport combination will be inferred where possible.

The list of tuples should be encoded as a strictly valid JSON. See the HTTP/cURL usage for formatting examples. SDK users on the other hand should supply normal dictionary objects since encoding issues are abstracted away for them.

curl --request POST \
  --url 'https://api.reposify.com/v1/scan/host/?token=TOKEN' \
  --form 'ips=208.130.29.0/30, 66.88.77.33' \
  --form 'arguments=[{"port":53, "protocol":"dns", "transport":"tcp"}, {"port":80}, {"protocol":"ftp"}]'
import reposify

# Set credentials using provided token
discovery = reposify.Discovery(token='TOKEN')
# Request for auto-discovery over the IP address range
# 208.130.29.0/30 and also IP address 66.88.77.33
result = discovery.host(ip_addresses='208.130.29.0/30, 66.88.77.33')
# Scan for devices using DNS on port 53, devices using port 80, and devices using FTP, over the IP address range
# 208.130.29.0/30 and also IP address 66.88.77.33
arg_map = [{'port': 53, 'protocol': 'dns', 'transport': 'tcp'}, {'port': 80}, {'protocol': 'ftp'}]
response = discovery.host(ip_addresses='208.130.29.0/30, 66.88.77.33', arguments=arg_map)
// Set credentials using provided token
var Discovery = new repsify.Discovery({token:"TOKEN"})

// Request for auto-discovery over the IP address range
// 208.130.29.0/30 and also IP address 66.88.77.33
Discovery.host({ips:"208.130.29.0/30, 66.88.77.33"}),
function(result,err){
    if(!err)
        console.log(result);
})

// Scan for devices using DNS on port 53, devices using port 80, and devices using FTP, over the IP address range
// 208.130.29.0/30 and also IP address 66.88.77.33
Discovery.host({ips:"208.130.29.0/30, 66.88.77.33",arguments:[{"port":53, "protocol":"dns", "transport":"tcp"}, {"port":80}, {"protocol":"ftp"}]},
function(result,err){
    if(!err)
        console.log(result);
})
// Request for auto-discovery over the IP address range
// 208.130.29.0/30 and also IP address 66.88.77.33
ScanResponse result = client.scanHost("208.130.29.0/30, 66.88.77.33", null);
// Scan for devices using DNS on port 53, devices using port 80, and devices using FTP, over the IP
// 208.130.29.0/30 and also IP address 66.88.77.33
List<DiscoveryHostArgument> arg = new ArrayList<>();
arg.add(new DiscoveryHostArgument(53, "dns", "tcp"));
arg.add(new DiscoveryHostArgument(80, null, null));
arg.add(new DiscoveryHostArgument(null, "ftp", null));
ScanResponse response = client.scanHost("208.130.29.0/30, 66.88.77.33", arg);
import "github.com/reposify/reposify-go"

// Set credentials using provided token
discovery := reposify.NewDiscovery("TOKEN")
// Request for auto-discovery over the IP address range
// 208.130.29.0/30 and also IP address 66.88.77.33
results, err := discovery.Host("208.130.29.0/30, 66.88.77.33", nil)
// Scan for devices using DNS on port 53, devices using port 80, and devices using FTP, over the IP
// 208.130.29.0/30 and also IP address 66.88.77.33
args := []reposify.DiscoveryHostArgument{{Port: 53, Protocol: "dns", Transport: "tcp"}, {Port: 80}, {Protocol: "ftp"}}
results, err = discovery.Host("208.130.29.0/30, 66.88.77.33", args)
require 'reposify'

# Set credentials using provided token
discovery = Reposify::Discovery.new("TOKEN")

# Request for auto-discovery over the IP address range
# 208.130.29.0/30 and also IP address 66.88.77.33
results = discovery.host("208.130.29.0/30, 66.88.77.33", nil)

# Scan for devices using DNS on port 53, devices using port 80, and devices using FTP, over the IP
# 208.130.29.0/30 and also IP address 66.88.77.33
args = {:Port => 53, :Protocol => "dns", :Transport => "tcp"}
results = discovery.host("208.130.29.0/30, 66.88.77.33", args)

This requests will return JSON structured as follows:

{
  "status": "pending",
  "job_id": "e976e634-1e5c-4d10-b131-30fc106b8672",
  "ips": "208.130.29.0/30, 66.88.77.33"
}

Status

This endpoint is useful for polling the server for the state of your Discovery requests. To identify the request you will need to use the job ID that is returned when the request is submitted. Once the scan is completed you will receive an email with a detailed report.

curl --request GET \
  --url 'https://api.reposify.com/v1/scan/status/?token=TOKEN&job_id=6c506856-2d74-4329-b9bc-95257afb2264'
import reposify

# Set credentials using provided token
discovery = reposify.Discovery(token='TOKEN')
# Request status for specified job id
scan_status = discovery.status(job_id='6c506856-2d74-4329-b9bc-95257afb2264')
// Set credentials using provided token
var Discovery = new repsify.Discovery({token:"TOKEN"})

// Request status for specified job id
Discovery.status({jobId:"24918e52-a42e-4d9b-a6d4-31088386a053"}, 
function(result,err){
    if(!err)
        console.log(result);
})
// Request status for specified job id
StatusResponse scan_status = client.scanStatus("6c506856-2d74-4329-b9bc-95257afb2264");
import "github.com/reposify/reposify-go"

// Set credentials using provided token
discovery := reposify.NewDiscovery("TOKEN")
// Request status for specified job id
scan_status, err := discovery.Status("6c506856-2d74-4329-b9bc-95257afb2264")
require 'reposify'

# Set credentials using provided token
discovery = Reposify::Discovery.new("TOKEN")
# Request status for specified job id
results = discovery.status("6c506856-2d74-4329-b9bc-95257afb2264")

This requests will return JSON structured as follows:

{
  "status": "processing",
  "job_id": "6c506856-2d74-4329-b9bc-95257afb2264",
  "created_date": "2017-03-01T16:50:08.906Z",
}

Account

Status

Get account’s status information:

import reposify

# Set credentials using provided token
account = reposify.Account(token='TOKEN')
# Get account's status information
status = account.status()
// Set credentials using provided token
var account = new repsify.Account({token:"TOKEN"});

// Get account's status information
account.status(function(result,err){
    if(!err)
        console.log(result);
})
// Get account's status information
AccountStatusResponse status = client.getAccountStatus();
import "github.com/reposify/reposify-go"

// Set credentials using provided token
account := reposify.NewAccount("TOKEN")
// Get account's status information
status, err := account.Status()
require 'reposify'

# Set credentials using provided token
account = Reposify::Account.new("TOKEN")
# Get account's status information
results = account.status()

The above command returns JSON structured like this:

{
    "query_credits": 15040,
    "plan": "Business"
}

This endpoint return account information such as current account’s plan and insights credits balance.

HTTP Request

GET https://api.reposify.com/v1/account/status