TypeScript SDK

The @signa-so/sdk package is a typed, ergonomic client for the Signa API: full types for every endpoint and response, automatic pagination, built-in retries, and typed error classes.

The SDK is designed for server-side use. A Signa API key grants full access to your org’s data; putting one in browser code exposes it to every visitor. Proxy requests through your own backend instead.

Install

npm install @signa-so/sdk

yarn add @signa-so/sdk

pnpm add @signa-so/sdk

bun add @signa-so/sdk

Requires Node.js 18+ or Bun 1.0+. TypeScript 5.0+ is recommended but not required.

Configure

import { Signa } from '@signa-so/sdk';

const signa = new Signa({
  api_key: process.env.SIGNA_API_KEY,
  // Optional overrides
  base_url: 'https://api.signa.so', // default
  timeout: 30_000,                  // 30s default
  max_retries: 2,                   // default, retries on 429/5xx
});

If you omit api_key, the client reads SIGNA_API_KEY from the environment:

export SIGNA_API_KEY=sig_your_key_here

// Uses SIGNA_API_KEY automatically
const signa = new Signa();

Resources

The client organizes the API into resource namespaces. The main ones:

Namespace	Description
`signa.trademarks`	Search, retrieve, batch lookup, events, proceedings, assignments, documents, citations, citedBy
`signa.owners`	Owner profiles, trademark portfolios, GLEIF corporate relationships
`signa.entities`	Resolved entities: one company across all offices, trademarks, corporate family
`signa.attorneys`	Attorney profiles, trademark portfolios, client lists
`signa.firms`	Law firm profiles, attorneys, trademark portfolios
`signa.proceedings`	Oppositions, cancellations, and other tribunal proceedings
`signa.citations`	Office-action citations across every mark: which prior marks were cited against which applications, with disposition and stage
`signa.references`	Classifications, offices, office coverage votes, jurisdictions, event types, design codes, deadline and opposition rules
`signa.goodsServices`	Goods & services term catalog and AI-assisted specification drafting
`signa.deadlines`	Batch maintenance-deadline computations
`signa.oppositions`	Batch opposition-window computations
`signa.reconcile`	Compare your own records against register data
`signa.portfolios`	Portfolio CRUD, member marks, deadlines
`signa.watches`	Watch CRUD, pause/resume, preview, bulk create, diagnostics
`signa.alerts`	Read-only alert listing, retrieval, and bulk lookup
`signa.webhooks`	Webhook endpoint CRUD, secret rotation, test deliveries, delivery audit
`signa.events`	Org event stream: list and retrieve with diffs
`signa.organization`	Account identity, usage, API key management, request logs

Search and list trademarks

search() takes the POST body: q, similarity, structured filters under filters, exclusions under exclude, and options for aggregations, totals, and partial results:

const results = await signa.trademarks.search({
  q: 'SIGNA',
  similarity: ['identical', 'fuzzy', 'phonetic'],
  filters: { jurisdictions: ['US', 'EU'], nice_classes: [9, 42] },
  exclude: { entity_id: ['ent_7hQx2mPa'] },
  options: { aggregations: ['office_code'], include_total: true },
});

for (const hit of results.data) {
  console.log(hit.mark_text, hit.relevance_score, hit.match?.tier, hit.match?.via);
}
console.log(results.aggregations);
console.log(results.search_meta);

relevance_score orders the results and is not a likelihood of confusion. match.tier and match.via say how close the hit is and which channels found it. See Response. list() takes the flat GET keys. Filters are top-level params, not nested:

const page = await signa.trademarks.list({
  q: 'signa',
  offices: ['US'],
  status_primary: 'active',
  filing_date_gte: '2024-01-01',
  mark_text_not_is: ['SIGNA'],
  entity_id_not: ['ent_7hQx2mPa'],
  limit: 50,
});

Presets

Presets holds the two common channel sets. Spread one into list() or search():

import { Signa, Presets } from '@signa-so/sdk';

const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

// Fast knockout: identical, fuzzy, embedded
const knockout = await signa.trademarks.list({ q: 'vyntra', ...Presets.knockout, nice_classes: [9] });

// Full clearance: all five channels, adds sound-alikes
const clearance = await signa.trademarks.list({ q: 'vyntra', ...Presets.clearance, nice_classes: [9] });

Without a preset or similarity, q runs the default channels: identical, fuzzy, embedded, and lookalike.

List parameters

On list(), the mark_text_* filters and the *_not exclusions take arrays. The SDK sends them as repeated keys (mark_text_is=nike&mark_text_is=mike), never comma-joined, so a comma inside a mark is safe. Values within one key match any; different keys and q must all match. When the query string passes 2 KB, list() sends the same search as a POST.

const variants = await signa.trademarks.list({
  mark_text_is: ['VYNTRA', 'VYNTRA LABS', 'VYN-TRA'],
  nice_classes: [9, 42],
});

Both return a SignaList, see Pagination below.

Retrieve and batch

const tm = await signa.trademarks.retrieve('tm_8kLm2nPq');
console.log(tm.mark_text, tm.status.primary);

// Madrid territory coverage, mark-to-mark relationships and source provenance
// ship inline on the detail response; there is nothing extra to request.
console.log(tm.coverage?.territory_count, tm.relationships.length, tm.provenance.source_data_date);

// The prosecution timeline is unbounded, so it stays a sub-resource
const events = await signa.trademarks.events('tm_8kLm2nPq', { limit: 50 });

Look up multiple trademarks in one call, by Signa ID or office identifier (max 100 per call):

const result = await signa.trademarks.batch({ ids: ['tm_8kLm2nPq', 'tm_9jNq3rTw'] });

console.log(result.data);      // trademarks that matched
console.log(result.not_found); // IDs or identifiers that didn't match

Pagination

Every list and search method returns a SignaList<T>, which supports three consumption patterns. The first page is fetched eagerly; later pages are fetched lazily. Async iteration, the simplest approach:

for await (const tm of signa.trademarks.list({ offices: ['US'] })) {
  console.log(tm.mark_text);
}

Collect to an array with toArray(). It never returns a short array silently. It throws SignaTruncatedError, whose items carry what was collected, in two cases:

reason: 'client_limit': no limit was passed and the list holds more than 10,000 items. Pass { limit } for at most that many items, or { limit: Infinity } for all of them.
reason: 'server_window': the API ended a trademark search at its 10,000-row search window while more rows match, before your limit was reached. The signal is the API’s result_window_reached warning on the last page; counts alone never make toArray() throw. Narrow the query with filters.

for await and getNextPage() never throw for this; they stop where the API stops (has_more: false).

const page = await signa.trademarks.list({ jurisdictions: ['US'], status_primary: 'active' });
const allMarks = await page.toArray();                // throws SignaTruncatedError past 10,000
const first500 = await page.toArray({ limit: 500 });  // at most 500, no error
const everything = await page.toArray({ limit: Infinity }); // may still throw 'server_window'

Manual paging, for full control over when the next request fires:

let page = await signa.trademarks.list({ offices: ['US'], limit: 100 });

console.log(`Page 1: ${page.data.length} items`);
console.log(`Request ID: ${page.request_id}`);

while (page.has_more) {
  page = await page.getNextPage();
  console.log(`Next page: ${page.data.length} items`);
}

getNextPage() returns an empty list (not an error) once there are no more pages. Every SignaList exposes data, has_more, request_id, and, on search responses, search_meta and aggregations. There is no public pagination field on the list itself, use has_more and getNextPage() to drive pagination rather than reaching for a cursor directly.

Error handling

All errors extend SignaError. API errors (4xx/5xx) extend SignaAPIError and carry a typed subclass per status code:

SignaError
├── SignaAPIError
│   ├── BadRequestError        400
│   ├── AuthenticationError    401
│   ├── PermissionError        403
│   ├── NotFoundError          404
│   ├── ConflictError          409
│   ├── RateLimitError         429 (has retry_after)
│   └── InternalServerError    5xx
├── ConnectionError            DNS, TCP, TLS failures
├── TimeoutError               request exceeded timeout
└── SignaTruncatedError        toArray() without a limit passed 10,000 items

Use instanceof to handle specific error types:

import { Signa } from '@signa-so/sdk';

const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

try {
  const tm = await signa.trademarks.retrieve('tm_invalid');
} catch (err) {
  if (err instanceof Signa.NotFoundError) {
    console.log('Trademark not found');
  } else if (err instanceof Signa.RateLimitError) {
    console.log(`Rate limited, retry after ${err.retry_after}s`);
  } else if (err instanceof Signa.AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof Signa.SignaAPIError) {
    console.log(`API error ${err.status}: ${err.message}`);
  } else if (err instanceof Signa.ConnectionError) {
    console.log('Network issue:', err.message);
  } else if (err instanceof Signa.TimeoutError) {
    console.log('Request timed out');
  }
}

Every SignaAPIError carries the structured error body plus the request ID:

try {
  await signa.trademarks.list({ offices: ['invalid_office'] });
} catch (err) {
  if (err instanceof Signa.BadRequestError) {
    console.log(err.error.type);   // machine-readable slug, e.g. "validation_error"
    console.log(err.error.detail); // human-readable detail
    console.log(err.request_id);   // include this in support requests
  }
}

Automatic retries

Error type	Retried?
`ConnectionError`	Yes
`TimeoutError`	Yes
`RateLimitError` (429)	Yes, after the `retry_after` delay
`InternalServerError` (5xx)	Yes, unless the error body says `retryable: false`
`BadRequestError` (400)	No
`AuthenticationError` (401)	No
`NotFoundError` (404)	No

An explicit retryable: false in the server’s error body overrides the status-based rule: a deterministic failure like the watch preview’s 504 timeout is not retried, since a blind retry would re-run the same over-budget work. Retries use exponential backoff with jitter.

const signa = new Signa({
  api_key: process.env.SIGNA_API_KEY,
  max_retries: 3, // default: 2, set to 0 to disable
});

Override retry behavior per request:

const tm = await signa.trademarks.retrieve('tm_8kLm2nPq', undefined, { max_retries: 0 });

Timeouts

The default timeout is 30 seconds. Configure it globally or per request:

const signa = new Signa({ api_key: process.env.SIGNA_API_KEY, timeout: 60_000 });

const tm = await signa.trademarks.retrieve('tm_8kLm2nPq', undefined, { timeout: 10_000 });

Debug mode

const signa = new Signa({ api_key: process.env.SIGNA_API_KEY, debug: true });

Logs each request and response (method, URL, status, timing) to stderr.

Overview

Trademarks

Parties

Records

Intelligence

Filing & docketing

Monitoring

Analytics

Reference

Administration

SDK

Install

Configure

Resources

Search and list trademarks

Presets

List parameters

Retrieve and batch

Error handling

Automatic retries

Timeouts

Debug mode

​Install

​Configure

​Resources

​Search and list trademarks

​Presets

​List parameters

​Retrieve and batch

​Pagination

​Error handling

​Automatic retries

​Timeouts

​Debug mode

Install

Configure

Resources

Search and list trademarks

Presets

List parameters

Retrieve and batch

Pagination

Error handling

Automatic retries

Timeouts

Debug mode