Detect signatures with Node.js

Node 18 and newer include fetch, which is enough. You do not need an SDK. The API key stays in the environment of the server that sends the request. Do not ship it in a browser bundle. Anyone who can read the key can spend your credits.

export SIGNATURE_API_KEY="your_api_key_here"

Create that key from the dashboard after signup. A new account has 10 credits.

Image URL

imageUrl must be an http or https URL. The API downloads it without your headers, so the object has to be readable by a plain GET.

const response = await fetch("https://signature-detector.com/api/detect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.SIGNATURE_API_KEY,
  },
  body: JSON.stringify({
    imageUrl: "https://example.com/document.jpg",
  }),
});
 
const data = await response.json();
 
if (!response.ok) {
  console.error(response.status, data.error);
  process.exit(1);
}
 
console.log("count", data.result.count);
console.log("credits", data.creditsRemaining);
console.log("cached", data.cached === true);
 
for (const detection of data.result.detections) {
  const { x1, y1, x2, y2 } = detection.bbox;
  console.log(detection.class_name, detection.confidence, x1, y1, x2, y2);
}

result.confidenceThreshold is 0.1. There is no request field for it. class_name in the published example is "signature".

cached: true means these image bytes were detected before, and this call did not spend a credit. On a fresh call the property is absent, not false.

Base64 from disk

Use this when the file is private. Send imageBase64 instead of imageUrl. The route returns 400 if both are present, and 400 if neither is present.

import { readFile } from "node:fs/promises";
 
const bytes = await readFile("document.png");
 
const response = await fetch("https://signature-detector.com/api/detect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.SIGNATURE_API_KEY,
  },
  body: JSON.stringify({
    imageBase64: bytes.toString("base64"),
  }),
});

The route also accepts a data:image/png;base64, prefix and strips it. The playground sends the raw base64, which is what Buffer.toString("base64") produces. The playground UI refuses non-images and files over 10MB. That check is in the playground, not in the API route.

Status codes

if (response.status === 401) {
  throw new Error("API key was rejected");
}
if (response.status === 402) {
  // data.credits is the balance, data.needsPurchase is true
  throw new Error("Buy credits before retrying");
}
if (response.status === 400) {
  throw new Error(data.error);
}
if (response.status === 503 || response.status === 500) {
  // The credit for a failed detection is refunded. Retrying is safe.
  throw new Error(data.error || "Detector failed");
}

A 402 will not succeed on retry until the balance is at least 1. Credits are $10 per 100,000 ($0.0001 each). The minimum purchase is $1 (10,000 credits). They do not expire.

Coordinates are pixels of the file you sent. Drawing them, or cutting them out with sharp, is covered in Extract signature crops from bounding boxes. For a PDF, switch the body to pdfUrl or pdfBase64 and read pages, count, and creditsUsed at the top of the JSON, not under result. A PDF spends 1 credit per page. The same file again returns creditsUsed: 0. The official client method is detectPdf({ pdfUrl }) or detectPdf({ pdfBase64 }) from the signature-detector package, and it returns pageCount, creditsUsed, and pages on the object. The shape is described in Detect signatures in PDFs with Python and on PDF signature detection. Image requests may include threshold from 0 to 1 (default 0.1). PDF detection always uses 0.1.

Reference: Signature detection API, API docs, playground.