Documentation

Run a browser check, integrate the SDK, or call the IP API. Start with a working example, then check the data flow and error behavior.

For an HTML page, use the hosted SDK below. Its small loader fetches the full collectors when you first run a scan. The npm package is not published yet; a package-install instruction is not required for this example.

HTML · collect and submit with the SDK

<script src="https://creepjs.org/sdk.js"></script>
<label>API token <input id="token" type="password" autocomplete="off"></label>
<button id="check" type="button">Collect & submit</button>
<output id="result" aria-live="polite"></output>
<script>
  const button = document.querySelector('#check');
  const output = document.querySelector('#result');
  button.addEventListener('click', async () => {
    const token = document.querySelector('#token').value.trim();
    if (!token) { output.textContent = 'Enter an API token.'; return; }
    button.disabled = true;
    output.textContent = 'Collecting and submitting…';
    try {
      // Run only after the visitor agrees to collection and API submission.
      const client = new CreepJS.CreepJS({ token, cache: false });
      const result = await client.getFingerprint();
      output.textContent = 'Diagnostic ID: ' + result.fingerprintId;
    } catch {
      output.textContent = 'Request failed. Check the token and connection, then retry.';
    } finally {
      button.disabled = false;
    }
  });
</script>

This example transmits the complete collected payload to the API. Full scans include a Google STUN request. Use a test token and collect only after your own disclosure and consent requirements are satisfied. Browser tokens can be inspected by page scripts.

Need a local report without an API submission?

This version computes a report locally and does not send it to the CreepJS API. Its WebRTC collector still contacts Google STUN servers.

HTML · local collection only

<script src="https://creepjs.org/sdk.full.js"></script>
<button id="inspect" type="button">Inspect locally</button>
<output id="local-result" aria-live="polite"></output>
<script>
  const button = document.querySelector('#inspect');
  const output = document.querySelector('#local-result');
  button.addEventListener('click', async () => {
    button.disabled = true;
    output.textContent = 'Collecting…';
    try {
      const result = await CreepJSFull.collectFingerprint();
      output.textContent = 'Diagnostic ID: ' + result.fingerprintId;
    } catch {
      output.textContent = 'Collection failed. Retry or inspect individual signals.';
    } finally { button.disabled = false; }
  });
</script>

API reference

Base URL: https://api.creepjs.org. Authenticated requests use X-API-Token. Public IP and own-IP lookups do not need a token.

Endpoints, inputs, authentication, and returned output
EndpointInput & accessOutput & limits
POST /v1/tokenJSON: { email }. No existing token.Token is returned here, not emailed. Issuance limits apply.
POST /v1/fingerprintA real collected snapshot; token required.Recalculated ID, data, coverage, timings. Maximum 128 KiB.
GET /my-ipNo address or token needed.Your public IP, approximate location, and optional risk context.
GET /v1/ip/public/:ipOne IPv4 or IPv6 literal; no token.IP report. 30 lookups per visitor per day.
GET /v1/ip/:ipOne IPv4 or IPv6 literal; token required.IP report with daily quota metadata.
POST /v1/ip/batchJSON: { ips: [...] }; token required.Up to 50 entries. Per-row outcomes; partial results stay usable.

Authenticated requests share an allowance of 1,000 requests per day across tokens issued to the same email. Batch responses expose charged and skipped outcomes; use the returned quota fields rather than assuming every row succeeded. To check a list without writing code, use the batch lookup on the IP checker.

cURL · authenticated IP lookup

curl --fail-with-body --max-time 15 'https://api.creepjs.org/v1/ip/8.8.8.8' \
  -H 'X-API-Token: YOUR_API_TOKEN'
SDK cache and request options
cache
Defaults to true. Set false for a new collection and API request.
cacheTtl
Seconds, default 86400; capped at 7 days. Zero disables caching.
timeoutMs
Bounds the API request. Handle timeout as an uncertain request outcome.
fullBundleUrl
Defaults to the sibling sdk.full.js. Set it when self-hosting collector assets.

Read the output before making a decision

fingerprintId
A diagnostic ID derived from the submitted components. Changes in environment or available signals can change it.
data
The actual observed collector values. Missing APIs and false or zero values must remain distinct.
coverage / confidence
Collection completion, not a uniqueness estimate or probability of fraud. Inspect successful, failed, and skipped counts.
collectors / timings
Per-collector outcomes and duration. Use these to investigate a partial scan before comparing IDs.
Find the method and limits for each signal

Fix a failed request

400 · invalid input
Check the returned validation details. IP tools accept address literals, not URLs, hostnames, ports, or ranges.
401 · token rejected
Replace the token and retry. Never put the token in a query string.
413 · payload too large
The fingerprint endpoint accepts at most 128 KiB. Inspect the actual collected JSON before resubmitting.
429 · quota reached
Wait for the returned retry or reset time. Generating more tokens for the same inbox does not increase its allowance.
Network error or timeout
Keep inputs and retry manually when ready. A timed-out POST may have been processed; do not replay it automatically.
Partial or missing data
Keep available fields, mark missing fields unknown, and retry failed rows or collectors independently. Missing evidence is not proof of safety.

Privacy & interpretation limits

Browser fingerprinting combines observable rendering, environment, and capability signals. It does not prove a person’s identity. Private browsing can isolate stored data while leaving many browser values observable.

Local collectors do not require an API token. SDK submission sends the collected payload to the API, which validates it and records coarse aggregate comparison statistics. Token records contain the email and creation time. IP reports may be cached. SDK caching is local to the browser; set cache to false if you do not want it.

Read data handling and retention. Use the checker to compare observed settings before drawing a conclusion from a score.