1. Install the Node client

This guide uses the published @radsoft/markbase SDK, version 2026.11.2 or later, in a Node.js runtime with built-in fetch. The package uses ES modules; save the script as search.mjs or use "type": "module" in your package.json.

bun add @radsoft/markbase

Create a Free account and copy your API key from the dashboard into your server's secret configuration as MARKBASE_API_KEY. Free includes 5,000 requests per month and up to 25 results per search. Keep the key on your server; browser bundles and public environment variables expose it to visitors.

2. Make a keyed search

The client reads MARKBASE_API_KEY from the environment. Check that it exists before constructing the client so a missing deployment secret does not silently use keyless access. This request searches software and electronics class 9 without excluding pending applications or other statuses.

import { Markbase, statusOf } from "@radsoft/markbase";

if (!process.env.MARKBASE_API_KEY) {
  throw new Error("Set MARKBASE_API_KEY in your server environment");
}

const markbase = new Markbase({ timeout: 10_000, maxRetries: 2 });
const result = await markbase.search({
  q: "acme",
  trademarkClass: 9,
  page: 1,
  limit: 10,
});

for (const mark of result.hits) {
  console.log(mark.serial_number, mark.word_mark, statusOf(mark.status_code));
}

console.log("Monthly requests remaining:", markbase.rateLimit?.quotaRemaining);
node search.mjs

SDK options use camelCase: trademarkClass becomes the REST parameter international_code, and statusCode becomes status_code. The response keeps the API's snake_case fields. Store serial numbers as strings, including any leading zeros. statusOf groups known USPTO codes and returns unknown for codes it does not recognize; retain the original code when displaying a record.

3. Keep pagination bounded

Fetch a small number of pages for a user's query instead of walking the entire register. Each page is a request against your quota. The loop below reuses markbase from the previous step and reads at most three pages, stopping earlier when a page is short.

const pageSize = 10;

for (let page = 1; page <= 3; page++) {
  const { hits } = await markbase.search({
    q: "acme",
    trademarkClass: 9,
    page,
    limit: pageSize,
  });

  for (const mark of hits) {
    console.log(mark.serial_number, mark.word_mark);
  }

  if (hits.length < pageSize) break;
}

The page size of 10 fits both keyless and Free access. Larger limits depend on your plan; requesting more does not raise its result cap. Search results can change while imports update the index, so pagination is not a consistent database export. For a saved result, retrieve its current record with await markbase.getTrademark(serialNumber).

4. Treat monthly quotas differently from short rate limits

The SDK retries temporary per-minute limits, server errors, and network failures up to your maxRetries setting. Monthly quota errors are not retried automatically. A timeout applies to each request attempt; retries and waits can make the full call take longer. Handle the final error at your server boundary.

import { AuthError, PlanError, RateLimitError, MarkbaseError } from "@radsoft/markbase";

try {
  const result = await markbase.search({ q: "acme", limit: 10 });
  console.log(result.hits.length);
} catch (error) {
  if (error instanceof AuthError) {
    console.error("Check the server's Markbase API key");
  } else if (error instanceof PlanError) {
    console.error("This operation requires a different plan");
  } else if (error instanceof RateLimitError) {
    if (error.kind === "quota") {
      console.error("Monthly quota exhausted; check usage in the dashboard");
    } else {
      console.error("Short-term rate limit; pause requests and try later");
    }
  } else if (error instanceof MarkbaseError) {
    console.error("Markbase request failed", error.status);
  } else {
    throw error;
  }
}

Avoid adding an unbounded retry loop around the SDK. Show an explicit temporary-unavailable state when a request fails; an error is not evidence that no trademark matches exist. markbase.rateLimit describes the most recent response on that client, not a separate usage ledger. With concurrent requests, read it as a snapshot.

5. Separate search from name screening

Search retrieves records. For a proposed name, clearance returns similar marks and screening risk signals. Add phonetic: true to include whole-name sound-alike evidence.

const screening = await markbase.clearance("Acme", {
  trademarkClass: 9,
  limit: 10,
  phonetic: true,
});

console.log(screening.highest_risk, screening.matching);
for (const match of screening.matches) {
  console.log(match.serial_number, match.word_mark, match.similarity, match.signals?.phonetic);
}

Omit phonetic for spelling-only results. Read phonetic evidence separately from spelling similarity and risk. The clearance guide covers unsupported names, retrieval limits, and batch quota.

A class filter narrows the search; it does not resolve legal questions about related goods or services. An empty result does not guarantee availability. Markbase covers US records, and screening is not legal advice. Check the data status before relying on freshness, and use a qualified trademark professional for a clearance opinion.

Connect your first keyed request

Your Free key includes 5,000 monthly requests. The dashboard shows usage so you can verify that your server integration is working.

curl "https://api.markbase.co/search?q=your-brand"

Keep reading