Migrating to the new search parameters

On September 29, 2026, trademark search moved to one request model. q always ranks, similarity picks how, text filters decide which marks qualify, and exclusions leave marks out. This guide maps every old parameter to its replacement. The old parameters keep working until December 28, 2026. Until then, each response that used one lists it in search_meta.deprecations, with its replacement and the sunset date. From December 28 they return 400 with unknown_parameter, naming the replacement. This applies to GET and POST /v1/trademarks, the owner, attorney, firm and entity /trademarks lists, similarity watches, the MCP search_trademarks tool and TypeScript SDK 0.17.0.

What changes without a code change

Some changes reach every integration on the release date:

Default recall is wider. q without similarity runs identical, fuzzy, embedded and lookalike. The old default was exact,fuzzy. You now also get marks with a different first letter (LIMBER for timber), look-alike characters (TIMB3R) and prefix phrases. Abbreviation matching and owner-name matching are gone; search owners with Search Owners. search_meta.ranking_version reads v12.
Cursors restart. Cursors issued before the release return 400 cursor_invalid. Start again from the first page.
Scores survive sort. With q, relevance_score and match are on every hit under any sort. They used to be null.
Timeouts fail instead of returning a partial page. A search that hits its time limit or loses a shard returns a retryable 503. Set allow_partial=true to get the rows found so far with search_meta.complete: false. The partial_results warning is gone.
No quiet downgrades. A query too expensive to run returns 400 with code: too_complex. It used to be retried with fewer strategies and a strategies_reduced warning.
mark_text_not_contains ignores punctuation and spacing, like the other text filters, and takes repeated keys for several values.
Skip warnings name a channel. A channel that can’t run on a q adds <channel>_skipped, such as phonetic_skipped, with the channel in channel.

Parameter map

Old	New	Notes
`strategies=exact`	`similarity=identical,lookalike`	The old `exact` also folded look-alike letters
`strategies=fuzzy`	`similarity=fuzzy,embedded,lookalike`	The old `fuzzy` also matched phrases, containment and look-alikes
`strategies=phonetic`	`similarity=phonetic`	`identical` is always added
`strategies=prefix`	`similarity=embedded`
`strategies=exact,fuzzy` (old default)	Omit `similarity`	The new default is wider
`match=similar`	Remove it	`q` always ranks
`match=exact&q=nike`	`mark_text_is=nike`
`match=starts_with&q=nik`	`mark_text_starts_with=nik`
`match=ends_with&q=ike`	`mark_text_ends_with=ike`	Now needs 3 characters
`match=contains&q=nik`	`mark_text_contains=nik`	Counts characters after punctuation is removed
`q=["nike","mike"]`	`mark_text_is=nike&mark_text_is=mike`	Repeated keys, never comma-split
`mark_text_not_contains=sunset`	`mark_text_not_contains=sunset`	Same name. Now a list, folded like the other filters
POST `query`	POST `q`
POST `mark_text_not_contains`	POST `exclude.mark_text.contains`
`ranking_profile`	Remove it	Choose channels with `similarity`
Watch `strategies`	Watch `similarity`	Not translated: the watch stays legacy until re-saved with `similarity`
Watch `min_match_tier`	Watch `min_tier`	`identical`, `near_identical`, `similar` or `related`. Not translated: the watch stays legacy until re-saved

Translated requests never return fewer marks than before. That is why a translated strategies set can turn on more channels than its name suggests: the old strategies ran more matching than their names said. To get exactly the channels you want, send similarity yourself.

Response fields

Old	New
`match_explanation.strategies_matched`	`match.via` (channels) and `match.tier`
`matched_terms`	`match.terms`
`search_meta.strategies_used`	`search_meta.similarity_applied`
`search_meta.match`	The text filters you sent, and `search_meta.order`
`search_meta.warnings[].code: partial_results`	`search_meta.complete` and `search_meta.incomplete_reason`
`search_meta.warnings[].code: strategies_reduced`	Removed. The request fails with `too_complex` instead

match_explanation, matched_terms, search_meta.strategies_used and search_meta.match keep being filled from the new data until December 28, 2026, so existing parsers keep working. Switch to match before then. The fine-grained labels that strategies_matched used to show are in match.details.lanes with include=match_details.

Before and after

Choose the matching

# Before
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=nova" \
  --data-urlencode "strategies=exact,fuzzy,phonetic,prefix"

# After
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=nova" \
  --data-urlencode "similarity=identical,fuzzy,embedded,phonetic,lookalike"

Starts with, ends with, contains

match replaced q with a text test. The text filters are separate parameters, so they combine with a ranked q of a different value.

# Before: marks starting with NOV, by date, no score
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=nov" \
  --data-urlencode "match=starts_with"

# After: the same marks, in text order (NOV first, then shortest)
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "mark_text_starts_with=nov"

# New: marks resembling NOVA that also start with NOV, ranked
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=nova" \
  --data-urlencode "mark_text_starts_with=nov"

A text filter without q used to list the newest filings first. It now lists in text order: marks equal to the value, then marks starting with it, then shorter marks, then newer filings. Add sort=-filing_date to keep the old order.

A list of exact spellings

# Before
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode 'q=["limber","bimber"]'

# After
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "mark_text_is=limber" \
  --data-urlencode "mark_text_is=bimber"

A cursor from the old form continues under the new form, so you can switch in the middle of a walk.

POST bodies

{
  "query": "nova",
  "strategies": ["exact", "phonetic"],
  "mark_text_not_contains": "novartis",
  "filters": { "nice_classes": [9] }
}

{
  "q": "nova",
  "similarity": ["identical", "lookalike", "phonetic"],
  "filters": { "nice_classes": [9] },
  "exclude": { "mark_text": { "contains": ["novartis"] } }
}

strategies: ["exact", "phonetic"] translates to identical, lookalike and phonetic. Drop lookalike if you don’t want look-alike characters.

Reading why a mark matched

// @docs-no-check
// Before
const phonetic = hit.match_explanation?.strategies_matched.includes("phonetic");

// After
const phonetic = hit.match?.via.includes("phonetic");
const strong = hit.match?.tier === "identical" || hit.match?.tier === "near_identical";

TypeScript SDK

SDK 0.17.0 removes the old keys from the types. The API still accepts them from older SDKs until December 28, 2026.

// @docs-no-check
// Before (0.16 and earlier)
const page = await signa.trademarks.list({
  q: "nova",
  strategies: ["exact", "fuzzy", "phonetic"],
  match: "similar",
});
const variants = await signa.trademarks.list({ q: ["limber", "bimber"] });
const body = await signa.trademarks.search({ query: "nova", strategies: ["exact"] });

// After (0.17.0)
import { Signa, Presets } from "@signa-so/sdk";

const signa = new Signa();

const page = await signa.trademarks.list({ q: "nova", ...Presets.clearance });
const variants = await signa.trademarks.list({ mark_text_is: ["limber", "bimber"] });
const body = await signa.trademarks.search({
  q: "nova",
  similarity: ["identical", "lookalike"],
  filters: { mark_text: { starts_with: ["nov"] } },
  exclude: { entity_id: ["ent_Wp8qLd4Z"] },
});

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

Presets.knockout is identical,fuzzy,embedded, a fast first screen. Presets.clearance adds phonetic and lookalike. Both spread into list() or search(). list() sends text filters and exclusions as repeated keys and switches to POST when the URL would pass 2 KB.

Watches

Existing watches keep alerting exactly as before. Their matching changes only when you update the query with the new keys. Sending the stored query back unchanged changes nothing. To use the new matching, send version: "v3", or similarity or min_tier:

{
  "name": "NOVA sound-alikes, US class 9",
  "watch_type": "similarity",
  "query": {
    "version": "v3",
    "q": "nova",
    "similarity": ["identical", "fuzzy", "phonetic"],
    "min_tier": "similar",
    "filters": { "jurisdictions": ["US"], "niceClasses": [9] }
  }
}

Watch keys are not translated. A watch written with strategies or min_match_tier is kept as a legacy watch until you re-save it with the new keys: it is stored as sent and keeps its legacy lane set and tier gate, so it alerts exactly as before. The create, update, bulk and preview responses list each old key in deprecations, with its replacement and the 2026-12-28 sunset. Sending an old key with a new one (similarity, min_tier or version: "v3") returns 400 (conflicting_params). Watches don’t take text filters or exclusions yet. Alerts gain match.tier, the same label a search hit carries. match.score is still the engine score for the watch query, not the 0 to 100 relevance_score. See Watches.

Checklist

Search your code for strategies, match, ranking_profile, query in POST bodies, and list values in q. Replace each one using the map above.
Read match instead of match_explanation and matched_terms.
Handle 503 on searches, or send allow_partial=true and check search_meta.complete.
Restart any pagination walk that stored a cursor from before September 29, 2026.
Watch your responses for search_meta.deprecations. An empty list means the request is fully migrated.
Upgrade to SDK 0.17.0.

See Search Trademarks for the full reference.

Getting started

Core concepts

Build with AI

Data

Monitoring

Working with the API

Use cases

Migrating to the new search parameters

What changes without a code change

Parameter map

Response fields

Before and after

Choose the matching

Starts with, ends with, contains

A list of exact spellings

POST bodies

Reading why a mark matched

TypeScript SDK

Watches

Checklist

​What changes without a code change

​Parameter map

​Response fields

​Before and after

​Choose the matching

​Starts with, ends with, contains

​A list of exact spellings

​POST bodies

​Reading why a mark matched

​TypeScript SDK

​Watches

​Checklist

What changes without a code change

Parameter map

Response fields

Before and after

Choose the matching

Starts with, ends with, contains

A list of exact spellings

POST bodies

Reading why a mark matched

TypeScript SDK

Watches

Checklist