API documentation · Blacktrace

Recommended authentication: send your key in the X-API-Key request header. Bearer authentication is also supported for compatible integrations.

Quick start

Create an account, activate a plan, copy the personal API key from your profile, and send a server-side request to the versioned endpoint.

curl -X POST https://blacktrace.io/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $BLACKTRACE_API_KEY" \
  -d '{"query":"example.com","limit":5}'

Authentication

The official format is:

X-API-Key: bt_live_your_key

Keep the key on your server. Do not expose it in browser JavaScript, mobile bundles, public repositories, URLs, or logs.

Bearer compatibility

Authorization: Bearer bt_live_your_key

Both formats are supported. New integrations should prefer X-API-Key for consistency with this documentation.

Service status

GET/api/v1/status

Public health endpoint. It does not require an API key.

{
  "data": {
    "status": "ok",
    "version": "v1",
    "timestamp": "2026-09-07T17:00:00+00:00"
  }
}

Search

POST/api/v1/search

Runs a lookup and automatically classifies supported indicators such as domains, email addresses, IP addresses, usernames, hashes, and blockchain identifiers.

JSON body

Field	Type	Required	Description
`query`	string	Yes	Indicator to analyze. Maximum 320 characters.
`limit`	integer	No	Maximum number of hits to return, from 1 to 10. Default: 10.

Successful response

{
  "data": {
    "id": 1842,
    "query": "example.com",
    "selector": { "type": "domain", "value": "example.com" },
    "profile": {},
    "hits": []
  },
  "meta": {
    "requestId": "8f1c2d4a6b7e9012",
    "createdAt": "2026-09-07T17:00:00+00:00",
    "limit": 5
  }
}

The contents of profile and hits depend on the detected indicator and available public-source data. An empty result is returned as an empty array, not an error.

Integration examples

JavaScript

const response = await fetch("https://blacktrace.io/api/v1/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.BLACKTRACE_API_KEY
  },
  body: JSON.stringify({ query: "example.com", limit: 5 })
});

const payload = await response.json();
if (!response.ok) throw new Error(payload.error);
console.log(payload.data);

Python

import os
import requests

response = requests.post(
    "https://blacktrace.io/api/v1/search",
    headers={"X-API-Key": os.environ["BLACKTRACE_API_KEY"]},
    json={"query": "example.com", "limit": 5},
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"])

Errors

Errors use a stable machine-readable code:

{ "error": "INVALID_API_KEY" }

Status	Code
400	`INVALID_REQUEST`, `INVALID_JSON`
401	`AUTHENTICATION_REQUIRED`, `INVALID_API_KEY`
402	`PLAN_REQUIRED`
404	`NOT_FOUND`
422	`INVALID_QUERY`, `INVALID_LIMIT`
429	`RATE_LIMITED`
500	`SERVER_ERROR`

Limits

The search endpoint allows 30 requests per hour per API key. These response headers describe the current window:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset as a Unix timestamp
Retry-After when the limit is exceeded

Use exponential backoff for 429 and transient 5xx responses. Do not retry validation or authentication errors without changing the request.

Versioning and changes

The major version is included in the URL. Backward-compatible fields may be added within v1; existing fields will not be removed without a new major version.

Current release

2026-09-07 Added the recommended X-API-Key flow, Bearer compatibility, versioned status and search endpoints, consistent errors, and rate-limit headers.