API Reference

v1.0.0

The BarkScan API provides programmatic access to internet-wide scanning data, banner grabbing results, DNS records, and protocol analysis. All endpoints return JSON.

Base URL

https://barkscan.com/api/v1

Authentication

All API requests require authentication. You can authenticate using either a Bearer token header (recommended) or a query parameter.

API keys are managed from your account settings.

Bearer Token (Recommended)

Include your API key in the Authorization header.

Authorization: Bearer bsk_live_abc123...

Query Parameter

Append your API key as a query parameter.

GET /api/v1/search?api_key=bsk_live_abc123...

Code Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://barkscan.com/api/v1/search?q=nginx

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"q": "nginx"}
)
data = resp.json()

require "net/http"
require "json"

uri = URI("https://barkscan.com/api/v1/search?q=nginx")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(resp.body)

const resp = await fetch("https://barkscan.com/api/v1/search?q=nginx", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Your API Key

Used for "Try it" requests below

Pagination

Endpoints that return lists support pagination via page and per_page query parameters. The maximum per_page value is 100 (default: 25).

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
per_page	integer	25	Results per page (1-100)

Responses include a meta object with pagination info:

{
  "data": [...],
  "meta": {
    "total": 1542,
    "page": 1,
    "per_page": 25
  }
}

Rate Limiting

API requests are subject to rate limiting. When rate-limited, you will receive a 429 Too Many Requests response. Monitor your usage with the following response headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	UTC epoch timestamp when the window resets

Errors

The API uses standard HTTP status codes. All error responses include a JSON object with an error field containing a human-readable message.

Code	Meaning
200	Success
400	Bad Request -- invalid parameters
401	Unauthorized -- missing or invalid API key
404	Not Found -- resource does not exist
429	Too Many Requests -- rate limit exceeded
500	Internal Server Error

{
  "error": "Missing API key. Use Authorization: Bearer <key> header or ?api_key= parameter."
}

GET/search

Search across all banner grabbing results with flexible filtering. Supports a smart query parameter that auto-detects the query type (IP address, port number, CIDR range, etc.), as well as explicit filter parameters.

Parameters

Name	Type	Required	Description
q	string	No	Smart query string. Auto-detects: IP, port, CIDR range, or banner text.
ip	string	No	Filter by exact IP address.
port	integer	No	Filter by port number (1-65535).
status	string	No	Filter by result status (e.g. SUCCESS, TIMEOUT, REFUSED).
protocol	string	No	Filter by detected protocol:`ssh`,`http`,`tls`
banner	string	No	Substring search within banner text (case-insensitive).
start_date	datetime	No	Only include results grabbed at or after this datetime (ISO 8601).
end_date	datetime	No	Only include results grabbed at or before this datetime (ISO 8601).
page	integer	No	Page number (default: 1).
per_page	integer	No	Results per page, max 100 (default: 25).

Response

{
  "data": [
    {
      "id": 918274650,
      "ip": "203.0.113.1",
      "port": 443,
      "status": "SUCCESS",
      "banner": "HTTP/1.1 200 OK\r\nServer: nginx/1.24.0\r\n...",
      "protocol_details": {
        "tls": { "version": "TLSv1.3", "cipher": "TLS_AES_256_GCM_SHA384" },
        "http": { "status_code": 200, "server": "nginx/1.24.0" }
      },
      "grabbed_at": "2026-02-20T14:30:00Z"
    }
  ],
  "meta": { "total": 1542, "page": 1, "per_page": 25 }
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/search?q=203.0.113.1&port=443&protocol=tls"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"q": "203.0.113.1", "port": 443, "protocol": "tls"}
)

uri = URI("https://barkscan.com/api/v1/search?q=203.0.113.1&port=443&protocol=tls")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/search?q=203.0.113.1&port=443&protocol=tls", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

port

page

per_page

Response

GET/host/{ip}

Retrieve all recent banner grabbing results for a specific IP address, ordered by most recent first.

Parameters

Name	Type	Required	Description
ip	string	Required	IPv4 or IPv6 address (path parameter).
page	integer	No	Page number (default: 1).
per_page	integer	No	Results per page, max 100 (default: 25).

Response

{
  "data": [
    {
      "id": 918274650,
      "ip": "198.51.100.42",
      "port": 22,
      "status": "SUCCESS",
      "banner": "SSH-2.0-OpenSSH_9.6",
      "protocol_details": {
        "ssh": {
          "server_software": "OpenSSH_9.6",
          "kex_algorithms": ["curve25519-sha256", "diffie-hellman-group16-sha512"],
          "host_key_algorithms": ["ssh-ed25519", "rsa-sha2-512"]
        }
      },
      "grabbed_at": "2026-02-21T08:15:30Z"
    }
  ],
  "meta": { "total": 2, "page": 1, "per_page": 25 }
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/host/198.51.100.42"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/host/198.51.100.42",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

uri = URI("https://barkscan.com/api/v1/host/198.51.100.42")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/host/198.51.100.42", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

page

per_page

Response

GET/host/{ip}/ports

Retrieve a sorted list of distinct port numbers observed for a specific IP address.

Parameters

Name	Type	Required	Description
ip	string	Required	IPv4 or IPv6 address (path parameter).

Response

{
  "data": [22, 80, 443, 3306, 8080],
  "meta": {}
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/host/198.51.100.42/ports"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/host/198.51.100.42/ports",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

uri = URI("https://barkscan.com/api/v1/host/198.51.100.42/ports")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/host/198.51.100.42/ports", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

Response

GET/dns/{domain}

Retrieve DNS records for a specific domain, ordered by most recently updated first. Supports pagination.

Parameters

Name	Type	Required	Description
domain	string	Required	Domain name to look up (path parameter).
page	integer	No	Page number (default: 1).
per_page	integer	No	Results per page, max 100 (default: 25).

Response

{
  "data": [
    {
      "id": 47291830,
      "domain": "example.com",
      "tld": "com",
      "ip": ["93.184.216.34"],
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2026-02-20T12:30:00Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 25 }
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/dns/example.com"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/dns/example.com",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

uri = URI("https://barkscan.com/api/v1/dns/example.com")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/dns/example.com", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

domain

page

per_page

Response

GET/dns/reverse/{ip}

Find domains that resolve to a given IP address. Returns up to 100 matching DNS records, ordered by most recently updated first.

Parameters

Name	Type	Required	Description
ip	string	Required	IPv4 address to look up (path parameter).

Response

{
  "data": [
    {
      "id": 47291830,
      "domain": "example.com",
      "tld": "com",
      "ip": ["93.184.216.34"],
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2026-02-20T12:30:00Z"
    },
    {
      "id": 47291831,
      "domain": "www.example.com",
      "tld": "com",
      "ip": ["93.184.216.34"],
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2026-02-20T12:30:00Z"
    }
  ],
  "meta": {}
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/dns/reverse/93.184.216.34"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/dns/reverse/93.184.216.34",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

uri = URI("https://barkscan.com/api/v1/dns/reverse/93.184.216.34")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/dns/reverse/93.184.216.34", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

Response

GET/stats/ports

Returns the count of banner results grouped by port number, sorted by count descending. By default, covers the last 24 hours.

Parameters

Name	Type	Required	Description
since	datetime	No	Only count results grabbed at or after this datetime (ISO 8601). Defaults to 24 hours ago.

Response

{
  "data": [
    { "port": 80, "count": 1842503 },
    { "port": 443, "count": 1623871 },
    { "port": 22, "count": 987432 },
    { "port": 3306, "count": 234187 },
    { "port": 8080, "count": 198432 }
  ],
  "meta": {}
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/stats/ports?since=2026-02-20T00:00:00Z"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/stats/ports",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"since": "2026-02-20T00:00:00Z"}
)

uri = URI("https://barkscan.com/api/v1/stats/ports?since=2026-02-20T00:00:00Z")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/stats/ports?since=2026-02-20T00:00:00Z", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

since

Response

GET/stats/protocols

Returns the count of banner results by detected protocol (SSH, HTTP, TLS). By default, covers the last 24 hours.

Parameters

Name	Type	Required	Description
since	datetime	No	Only count results grabbed at or after this datetime (ISO 8601). Defaults to 24 hours ago.

Response

{
  "data": {
    "ssh": 987432,
    "http": 1842503,
    "tls": 1623871
  },
  "meta": {}
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/stats/protocols"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/stats/protocols",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

uri = URI("https://barkscan.com/api/v1/stats/protocols")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/stats/protocols", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

since

Response

GET/account

Returns information about the authenticated user and the API key used for the request.

Parameters

This endpoint has no additional parameters beyond authentication.

Response

{
  "data": {
    "email": "[email protected]",
    "admin": false,
    "api_key": {
      "name": "Production Key",
      "created_at": "2025-11-01T09:00:00Z",
      "last_used_at": "2026-02-22T10:15:30Z"
    },
    "active_api_keys": 2
  },
  "meta": {}
}

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://barkscan.com/api/v1/account"

import requests

resp = requests.get(
    "https://barkscan.com/api/v1/account",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

uri = URI("https://barkscan.com/api/v1/account")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

const resp = await fetch("https://barkscan.com/api/v1/account", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await resp.json();

Try it

No parameters required. Uses your API key for authentication.

Response

OpenAPI Specification

Download the full OpenAPI 3.0 specification for use with code generators, Postman, or other API tools.

Download openapi/v1.yaml

Ready to get started?

Create a free account and generate your API key in seconds.

Get API Key View API Solutions