Field-scoped search
This guide documents the field-scoped search surface of GET /trademarks (in MCP, the same
question is asked with search_trademarks): the parameter list, the AND semantics between fields, the q + fields rule, RUT
normalization, and configurable ordering with sort=.
The complete, always-current per-field schema lives in the interactive OpenAPI reference at
https://api.tarno.cl/docs(Scalar). This guide explains the semantics of combined search and links to that reference — it does not restate the schema. The reference is authoritative when a field is not documented here.
Throughout this guide the base URL is https://api.tarno.cl and every call carries the X-API-Key
header — as in getting started and authentication. It uses the
brands:read scope.
What this guide covers
GET /trademarks is a single route that freely combines:
- Text search —
qranks by the denomination channels (exact / fuzzy / phonetic / semantic, fused by RRF). - Field filtering — exact, range and person predicates (
niceClass,status,applicationNumber,holder,taxId, …) that narrow the result.
All present parameters combine with AND. The response is a keyset page — the
{ results[], limit, next, hasMore, total, meta } envelope of getting started.
Already have a list of application numbers? Use
GET /trademarks?applicationNumber=a,b,c(up to 100, one quota unit) instead of N detail calls. Marks come back in request order, withmeta.notFound= the numbers that do not exist. The other filters apply to the batch (a mark that exists but does not match simply does not appear; it is not innotFound). The batch does not page or sort:limit,cursor,sort,minScore,q,denominationorfacetswithapplicationNumberare a400.
Parameters
All optional. A multi-value parameter repeats (?niceClass=9&niceClass=25) and does OR within the
field; different fields do AND between each other.
| Param | Type | Multi-value | Notes |
|---|---|---|---|
q |
string | no | Free text (Spanish FTS + fuzzy + phonetic + semantic, RRF). Up to 256 characters (longer ⇒ validation_error); the same cap applies to similarTo. |
denomination |
string | no | Text on the denomination, same engine as q. Up to 512 characters (q takes 256). |
applicationNumber |
string | yes | Application number, exact match. Each number up to 17 characters (12 digits, a hyphen and a series suffix of up to 4). |
registrationNumber |
string | no | Registration number, exact match. Up to 17 characters. |
holder |
string | yes | Substring on the holder, accent/case-insensitive. One value is one whole name, commas included ("PEPSICO, INC."); several by repeating the parameter (see Party names). Up to 20 values of 2 to 256 characters, with at least one letter or digit (anything else ⇒ validation_error); the same cap applies to representative and taxId. |
representative |
string | yes | Substring on the representative. Same rules as holder: a comma does not separate values. |
taxId |
string | yes | Normalized RUT (see RUT); exact match against holder and representative. Several by repeating the parameter: a comma does not separate values. |
party |
string | yes | A party by internal id (the id of GET /parties?q=) and role: <id>:holder or <id>:representative. Several values are OR'ed; see Parties by id. Up to 20 values. |
includeApplicationNumber |
string | yes | Applications added to the portfolio (OR with the party filters); every other filter still applies to them. See Portfolio by hand. Up to 500. |
excludeApplicationNumber |
string | yes | Applications always removed (AND NOT), even when they match. See Portfolio by hand. Up to 500. |
relation |
enum | no | current (default) · former · all — scopes holder/representative/taxId/party to current, former or both ownership. |
niceClass |
integer | yes | Nice class, 1–45. Up to 45 values. |
status |
string | yes | Status code (controlled catalog). Matches the published status, which is the derived one (D11): a mark INAPI still calls en_tramite but that already has a registration number comes back with status=registrada, and INAPI's literal in statusInapi. Up to 14 values (the catalog codes). |
signType |
string | yes | Sign-type code. Up to 14 values (the catalog codes) of up to 20 characters (the longest, combinacion_de_color). |
goodsAndServices |
string | no | ⭐ The goods-and-services text of the mark's classes, by words, accent- and case-insensitive (calzado finds «Calzados»). Not equality; one matching class is enough. 2–200 characters. -word excludes, but at least one word that must appear is required: only stop words (de la) or only exclusions (-calzado) is a 400 validation_error. |
filedFrom / filedTo |
YYYY-MM-DD |
no | Filing-date range (filedOn). |
milestoneFrom / milestoneTo |
YYYY-MM-DD |
no | ⭐ Marks with a milestone in the range (see Milestones): without milestoneKind, any of the four — expiry, opposition close, renewal-window opening or grace end. milestoneFrom > milestoneTo is 400 invalid_range. |
milestoneKind |
enum | yes | Narrows the milestone filter to these kinds: expiry, opposition_close, renewal_window_open and/or grace_end. Any other value —appeal_close too, published but not filterable— is a 400. Requires milestoneFrom and/or milestoneTo (without a range it is 400 validation_error). |
renewalStatus |
enum | yes | ⭐ Only the marks whose renewalStatus (see Milestones), evaluated on the date of the response, is one of not_due · window_open · grace · lapsed · renewed_expiry_pending. It is the same value every returned mark carries; marks with renewalStatus: null never match. Any other value is a 400. |
liveOnly |
boolean | no | Live marks only: excludes marks in a terminal status (rechazada, denegada, desistida, abandonada, anulada, caducado, vencida). A mark with no known status is kept. Absent = no filter. Written true or false; any other value (yes, 1, empty) ⇒ 400 validation_error. |
sort |
enum | no | Order (see Order). relevance (default) · filedOn:desc/:asc · denomination:asc/:desc · status:asc/:desc (by the published, derived status). |
limit |
integer | no | Page size. Default 20, max 100. |
cursor |
string | no | Opaque keyset cursor. |
A sort outside the enum, a malformed parameter or a value above its cap (more values or more characters than stated) returns 400 validation_error — including a boolean that is not exactly true or false. A malformed taxId
returns 400 invalid_rut (see RUT).
Holders and representatives in the list (holders, representatives)
Every mark in the response carries holders (holder names) and representatives (representative names): string[], [] when there is none, never null. representatives lists only the current
relation (role representante or ambas); it carries no party id (for that, GET /trademarks/{n} with
parties). Meant for exports that must not fetch the record row by row.
holders is also the current relation only (it used to mix in former holders). Ask for the
former ones with includeFormer=true (optional parameter, false by default; only true or false
are accepted): each mark then carries formerHolders and formerRepresentatives (string[], [] when there
is none), apart from holders and representatives. Without the parameter those two keys are not sent. It
works the same on GET /trademarks, POST /trademarks/search and search_trademarks, with or without q,
similarity, opposition window or batch. It does not change which marks come back (to filter by former holders
use relation). The record GET /trademarks/{n} does not need it: it already separates parties (current)
from formerParties.
Milestones (milestones)
Every mark in the response —and the record GET /trademarks/{n}— carries milestones[]: its dated
milestones, [] when it has none. Each milestone says where it comes from (basis): source (a date
INAPI publishes) or derived (a computed deadline, which ALWAYS carries its anchor, rule and article).
Sorted by date. This is the list of kinds (the other guides link here):
kind |
basis |
what it is | filters? |
|---|---|---|---|
expiry |
source |
the expiry date INAPI publishes (field: "expiresOn") |
yes |
opposition_close |
derived or estimated |
the close of the opposition window: the 30th business day after the publication of the extract. legalBasis cites the three norms: Ley 19.039 art. 5 (term), Ley 19.039 art. 11 (business_days) and Ley 19.880 art. 25 (computation, suppletory). Its date is oppositionWindow.deadline. If INAPI set a publication aside and republished the extract, the anchor is the last publication (the one INAPI publishes as the mark's publication date; its «Fin de plazo» falls 30 business days after it) |
yes |
renewal_window_open |
derived |
the opening of the renewal window: the expiry − 6 months, date to date (31 Aug − 6 months = 28 Feb). anchor: {kind: "expiry"}, rule: "6_months_before_expiry", legalBasis Ley 19.039 art. 24 (term), Decreto 82/2022 art. 27 (regulation), Código Civil art. 48 (computation; whether it applies is question 4, open to counsel) and Ley 19.880 art. 25 (computation; the same fourth norm as grace_end) |
yes Not published in renewed_expiry_pending. |
grace_end |
derived or estimated |
the end of the renewal grace period: the expiry + 6 months, date to date, and, when that day is a Saturday, Sunday or public holiday, the next business day (the same holiday calendar as opposition_close). rule: "6_months_after_expiry_next_business_day"; legalBasis the same four norms as renewal_window_open, the last one Ley 19.880 art. 25 (computation: when the last day of the term is a non-business day, it is extended to the next business day; INAPI confirmed in writing that a renewal filed on that business day is on time). estimated with estimateReasons: ["outside_holiday_calendar"] when the date falls after the declared coverage of the holiday calendar (today up to 2030-12-31): weekends and only the known holidays are skipped, so the real day is that one or later. No reservation |
yes |
appeal_close |
derived |
⭐ (44-14) the last day to appeal a REJECTION (024) or a PARTIAL ACCEPTANCE (444): the 15th business day STRICTLY after that resolution was published in the Estado Diario. anchor: {kind: "rejection_notice"}, rule: "15_business_days_after_notification", legalBasis Ley 19.039 art. 17 bis B (term), Ley 19.039 art. 11 (business_days) and Ley 19.880 art. 25 (computation). Only when the 024 or the 444 is the most recent resolutive movement (between the two, the most recent; on the same date, the 024), on a business day, inside the declared calendar and not via Madrid; otherwise it is absent (never estimated) and get_deadlines says why — or, with resolutions after an earlier 024 or 444, gives the date with its caveat (caveat) and no milestone |
no (400) |
opposition_response_close |
derived or estimated |
⭐ (2026-10-10) the last day to answer the transfer of an opposition: the 30th business day STRICTLY after the transfer was notified; not extendable. anchor: {kind: "transfer_notice", date, annotationId, sectionCode} — the act the date comes from: the C1 notification in the Estado Diario or, failing that, the transfer resolution (458, 647, 1197, 1198)—, rule: "30_business_days_after_notification", legalBasis Ley 19.039 art. 9 (term), Ley 19.039 art. 11 (business_days), Ley 19.880 art. 25 (computation) and Decreto 82/2022 art. 24 (regulation: once the term has elapsed, «se haya o no evacuado el traslado», the procedure goes on — not answering is not abandonment). derived with notification and resolution on the same day; estimated when one of the two is missing (notification_inferred_from_resolution_date or transfer_resolution_not_in_corpus). The most recent transfer rules. Absent for Madrid designations, transfers before 2022-05-09, an anchor on a non-business day or outside the calendar: get_deadlines and get_filing_context say why |
no (400) |
grant_fee_close |
estimated |
⭐ (2026-10-10) the last day to prove payment of the grant fees: the 60th business day STRICTLY after the notification of the acceptance (029) or of the certificate of finality (911, 912); unpaid, the application is held abandoned. anchor: {kind: "acceptance_notice" \| "finality_certificate", date, annotationId, sectionCode}, rule: "60_business_days_after_notification", legalBasis Ley 19.039 art. 18 bis E (term), Ley 19.039 art. 11 (business_days) and Ley 19.880 art. 25 (computation). Always estimated (estimateReasons: ["anchor_by_office_practice"]) and with reservation {code, text {es, en, pt}}: the law counts the 60 days from the day the resolution becomes final; INAPI, from its notification; the date follows what INAPI applies. Show it with that reservation. Absent with a partial acceptance or an opposition ruling not yet certified, for Madrid, before 2022-05-09, on a non-business day or outside the calendar: get_deadlines says why |
no (400) |
resolution |
derived |
⭐ (2026-10-26) the date INAPI decided the application —not a deadline—: the most recent acceptance or rejection act. date = anchor.date; anchor: {kind: "acceptance" \| "rejection", date, annotationId, sectionCode}, rule: "latest_acceptance_or_rejection", legalBasis Ley 19.039 art. 13 (notification: the resolution is notified by the Estado Diario). Acceptance: 029, 444, 484, 485, W146, W151, W152, W147, the Estado Diario section M4 and the acts that comply with a TDPI ruling granting the registration (915, 916, 918, 919, 921, 922, W150, W149); rejection: 024, 486, W160, W148 and the section M6. On the same day the code beats the section. Absent (never null) when the application was never decided (428 «tener por no presentada», withdrawn or abandoned before a decision), when a later TDPI act alters it without saying which way (920, 743, W126) or on a renewal file (W390, 539, 706, 632, 961, 540) |
no (400) |
designation_ceased |
derived |
⭐ (2026-10-28) the date INAPI declared the protection of a Madrid designation ceased after a WIPO DEATH notification —not a deadline—. date = anchor.date; anchor: {kind: "office_cessation", date, annotationId, sectionCode} with the latest cessation: 1238 (renunciation of Chile), 1240 (cancellation), 1241 (non-renewal) or 1242 (dependency on the basic mark); 1237 (partial transfer) does not extinguish. rule: "office_cessation_after_wipo_death", legalBasis Madrid Protocol arts. 6.3, 6.4 and 9 bis and Common Regulations rules 25 and 27 (role extinction). Present exactly when the mark publishes status: caducado because of that cessation (raw registrada or denegada, cessation after the latest DEATH and the latest PROLONG, no later registration entry). ⭐ (2026-11-04) Also when WIPO's cancellation (DEATH) reached INAPI during the procedure and INAPI granted afterwards (raw registrada, DEATH before the grant and the expiry, no PROLONG, BIRTH, CORRECTION, cessation or additional series on its day or later): date = anchor.date = the DEATH, anchor: {kind: "wipo_death", date, annotationId, sectionCode: "MAD01"}, rule: "wipo_death_received_before_grant", the same legalBasis |
no (400) |
legalBasis is a list of {norm, article, role}. opposition_close is derived when it can be
affirmed, and estimated —same shape, plus estimateReasons— when it cannot:
published_on_non_business_day— published on a Saturday, Sunday or holiday (the law does not say from which day the count runs then); counted from the first business day after it;outside_holiday_calendar— the publication-to-close span falls outside the declared coverage of the holiday calendar (meta.coverageofGET /holidays, today 2013-2030 — see Holidays); only weekends and the known holidays are skipped, so the real close is that day or later.
oppositionWindow carries the same legalBasis and, when estimated, the same estimateReasons. A
mark without a publication date has no opposition_close: there is no anchor.
The two renewal milestones only exist on national registrada or esperando_renovacion marks with an expiry from
2022-05-09 (the current art. 24 rule). With them travels renewalStatus, on every mark of the
response and on the full record, evaluated on the date of the response (Chile time):
renewalStatus |
when (V = published expiry) |
|---|---|
not_due |
before V − 6 months |
window_open |
from V − 6 months to V, both included |
grace |
after V and up to the grace_end date, included (V + 6 months, or the next business day when that one is a non-business day): the registration is still in force and can still be renewed |
lapsed |
once the grace period is over |
renewed_expiry_pending |
instead of window_open, grace or lapsed, before or after V: the mark has a renewal grant (a renewals[] entry of kind: "grant") dated from V − 6 months and already in — INAPI already renewed and the published expiry is the previous one, pending update; the mark publishes neither renewal_window_open nor grace_end, and returns to the rule as soon as the expiry is updated |
null |
the rule does not apply: no expiry date (never a guessed state), neither registrada nor esperando_renovacion, or filed via Madrid (9-digit number) |
Expiries before 2022-05-09 follow the old art. 24: window_open until V, grace until the 30th
business day after it, lapsed afterwards, and no milestones. renewalStatus describes the term to
request the renewal. ⭐ In grace the registration is in force: it lapses for want of renewal only if the grace period
ends without a renewal request (Ley 19.039 art. 24, 2nd paragraph), a renewal runs from the expiry with
no gap (Decreto 82/2022, art. 27, 2nd paragraph) and the lapse is not retroactive (INAPI Directrices,
chapter 23). INAPI cites registrations in their grace period as an art. 20 h obstacle just as it cites
those in force. ⚠ lapsed does not say that no renewal was requested (a granted renewal moves the
published expiry). The full rule, with its articles, is in
the description of renewalStatus in the OpenAPI reference at
https://api.tarno.cl/docs.
The milestone filter applies to the collection, the search, the batch, similarity, the opposition
window and /insights, and so does the renewalStatus filter. Without milestoneKind it matches any
of the four kinds ([BEH]: until 2026-09-25 it did not look at the two renewal dates). The renewal kinds
match exactly the date the mark publishes: an old-regime or Madrid mark, or one neither registrada nor esperando_renovacion, never matches
them, even if its expiry ± 6 months falls in the range. The
close filter returns exactly the marks whose published opposition_close —derived or estimated—
falls in the range: it becomes bounds on the publication date (one query, no range cap).
# "Which marks of this list are in their grace period?" — ONE call; every mark returned has renewalStatus = "grace".
curl -sS "https://api.tarno.cl/trademarks?applicationNumber=1171492,1181941,1198902&renewalStatus=grace" \
-H "X-API-Key: $TARNO_API_KEY"
# "Which marks can start renewing next month?"
curl -sS "https://api.tarno.cl/trademarks?milestoneKind=renewal_window_open&milestoneFrom=2026-10-01&milestoneTo=2026-10-31" \
-H "X-API-Key: $TARNO_API_KEY"
# → e.g. 1257468 OXIBLOCK: renewal_window_open 2026-10-30 (expires 2027-04-30), renewalStatus "not_due"
# "Which marks of this list have a milestone in the next 30 days, and when?" — ONE call with the batch of 100.
curl -sS "https://api.tarno.cl/trademarks?applicationNumber=1672581,1712345,1720001&milestoneFrom=2026-09-24&milestoneTo=2026-10-24" \
-H "X-API-Key: $TARNO_API_KEY"
# → results[].milestones = [{ "kind": "expiry", "date": "2026-10-10", "basis": "source", "field": "expiresOn" }]
# The close of the opposition window of a mark published on Friday 2026-08-14 (1648329):
curl -sS "https://api.tarno.cl/trademarks/1648329" -H "X-API-Key: $TARNO_API_KEY"
# → milestones = [{ "kind": "opposition_close", "date": "2026-09-28", "basis": "derived",
# "anchor": { "kind": "publication", "date": "2026-08-14" },
# "rule": "30_business_days_after_publication",
# "legalBasis": [ { "norm": "Ley 19.039", "article": "5", "role": "term" },
# { "norm": "Ley 19.039", "article": "11", "role": "business_days" },
# { "norm": "Ley 19.880", "article": "25", "role": "computation" } ] }]
# → oppositionWindow.deadline = "2026-09-28", with the same legalBasis
# "Which marks close their opposition window next week?" — ONE call.
curl -sS "https://api.tarno.cl/trademarks?milestoneKind=opposition_close&milestoneFrom=2026-09-28&milestoneTo=2026-10-04" \
-H "X-API-Key: $TARNO_API_KEY"
# → every mark carries in milestones[] its opposition_close between 09-28 and 10-04
The core publishes dates; it never notifies anyone. Who to alert and when (30 days before, 7, on the day) is your application's decision.
Notices from the expediente (notices)
Some trademarks carry on their detail (GET /trademarks/{applicationNumber} ≡ get_trademark) and in
their report a list notices[]: facts checked by hand in INAPI's expediente and in WIPO's International
Register that the public sources do not carry. A notice decides nothing else: status, statusInapi,
statusStale and milestones[] are decided by the annotations of the corpus. The key is omitted (never [] nor null)
on every mark without a notice, which is nearly all of them.
| field | what it says |
|---|---|
kind |
wipo_designation_ended: WIPO recorded in the International Register that Chile is no longer designated · wipo_refused_recording: WIPO did not record INAPI's statement of grant of protection (Common Regulations rule 18ter.1), because Chile is not among the designated Contracting Parties |
date |
the date of the fact: WIPO's act, the recording or the notice refusing one (source.recordedOn) |
cause |
only on wipo_designation_ended; what WIPO recorded: renunciation (of the designation of Chile), cancellation, dependency (cancellation because the basic mark ceased to be protected, Madrid Protocol art. 6.4), non_renewal |
label |
the notice in es-CL, en and pt-BR |
source |
the primary source: WIPO's recording (kind: "wipo_record"), with reference (RNN/2024/11, CBN/2025/15, or GP-I/2135499301/BB on a refusal notice), recordedOn, internationalRegistrationNumber and madridMonitorUrl (the registration in Madrid Monitor; null when the number was not recorded) |
corroboration |
the backing: the document of INAPI's expediente (kind: "inapi_expediente_document") with documentIndex (its position in the index of the expediente), label and date; null when not recorded |
A notice does not decide status or the milestones: the annotations of the corpus do. A Madrid designation
that INAPI granted after receiving WIPO's cancellation during the procedure publishes caducado with the
milestone designation_ceased (see Milestones), and the notice stays next to it with its source;
the same when INAPI dictates the cessation. A mark may carry both notices, in date order.
// GET /trademarks/991718309 (excerpt)
{
"status": "caducado",
"statusInapi": "registrada",
"statusStale": true,
"notices": [{
"kind": "wipo_designation_ended",
"date": "2024-02-15",
"cause": "renunciation",
"label": { "es-CL": "La OMPI inscribió en el Registro Internacional que Chile ya no está designado. …", "en": "…", "pt-BR": "…" },
"source": {
"kind": "wipo_record",
"reference": "RNN/2024/11",
"recordedOn": "2024-02-15",
"internationalRegistrationNumber": "1718309",
"madridMonitorUrl": "https://www3.wipo.int/madrid/monitor/en/showData.jsp?ID=ROM.1718309"
},
"corroboration": {
"kind": "inapi_expediente_document",
"documentIndex": 11,
"label": "Madrid OD - Notificación de OMPI tipo DEATH",
"date": "2024-02-15"
}
}]
}
Series of a Madrid registration
An international registration (Madrid Protocol) can have more than one series in Chile. INAPI treats
each additional series as a separate application and numbers it with the number of the first one plus a
suffix (991652209 and 991652209-2). The contract does the same: each series is one more
trademark, with its own registration number, classes, dates and history, fetched by its own number.
| field | where | what it says |
|---|---|---|
baseApplicationNumber |
on an additional series: collection, search, similarity, batch, trademarks of a party, reports and detail | the application number of series 1 of the same registration (991652209) |
seriesSuffix |
same | the suffix, exactly as INAPI writes it (2, A). applicationNumber = baseApplicationNumber + - + seriesSuffix |
relatedSeries[] |
on the detail (GET /trademarks/{applicationNumber} ≡ get_trademark) of any series of a registration the corpus holds several of |
the other series, series 1 first: applicationNumber, seriesSuffix (null for series 1), registrationNumber, status, classes and registeredOn |
The three fields are omitted (never sent as null) on any other trademark: a trademark that is not
part of a registration with several series answers exactly what it answered before.
- In search, similarity, batch and portfolio the trademark appears once per series, each with its classes and its registration number. Searching by the registration number of an additional series finds that series.
- In the renewal calendar there is one line per registration: the registration expires once and is renewed once, so an additional series never gets a row of its own. Today, moreover, Madrid-route trademarks publish no renewal milestones (see above).
- Asking for the base number (
991652209) returns series 1, as always (except for the lettered-only case below). Asking for991652209-2returns series 2. Do not strip the suffix when you normalize a number: you would attribute series 2 to series 1. - An absent
relatedSeriessays the corpus holds no other series of that registration, not that INAPI has none: a series still being processed may not be loaded. - The suffix can be a letter (
991866300-A,-B…): it is the expediente INAPI opens when part of the registration changes hands (partial transfer). It is served the same way, as one more trademark, with its own holder, classes and history. In most cases the living trademark is the lettered one and the base number is left with its own status (often refused or ceased): before writing off a Madrid trademark, look atrelatedSeries. - A registration whose only Chilean expediente is the lettered one. Some international
registrations never designated Chile under their base number: in Chile only the lettered expediente
exists (
<base>-A), which is how INAPI lists it. That trademark is published under the lettered number (baseApplicationNumber= the base,seriesSuffix= the letter, norelatedSeries) and asking for the base number still finds it:GET /trademarks/{applicationNumber}≡get_trademark,/deadlines≡get_deadlinesand/annotations≡list_trademark_annotationsanswer200with the lettered trademark (look at itsapplicationNumber), not404. The batch lookup (GET /trademarks?applicationNumber=…), search and watch do not recognise that base number: use the lettered number there. The Estado Diario acts the bulletin prints with the base number land on that trademark. - The Estado Diario acts of an additional series appear on series 1: the bulletin prints only the base number. The series' own history comes from INAPI's record page.
- A series can be watched on its own, with its own classes.
curl -sS "https://api.tarno.cl/trademarks/991652209" -H "X-API-Key: $TARNO_API_KEY"
# → "applicationNumber": "991652209", "registrationNumber": "1433511", …
# "relatedSeries": [{ "applicationNumber": "991652209-2", "seriesSuffix": "2",
# "registrationNumber": "1500507", "status": "registrada",
# "classes": [35], "registeredOn": "2026-06-23" }]
curl -sS "https://api.tarno.cl/trademarks/991652209-2" -H "X-API-Key: $TARNO_API_KEY"
# → "applicationNumber": "991652209-2", "baseApplicationNumber": "991652209", "seriesSuffix": "2", …
# "relatedSeries": [{ "applicationNumber": "991652209", "seriesSuffix": null, … }]
AND semantics
All present parameters combine with AND. Each field narrows the result further:
# Marks in class 9 OR 25 (OR within the field), AND whose holder contains "sonda",
# AND filed since 2020 (AND between fields).
curl -sS "https://api.tarno.cl/trademarks?niceClass=9&niceClass=25&holder=sonda&filedFrom=2020-01-01" \
-H "X-API-Key: $TARNO_API_KEY"
- OR within a multi-value field:
?niceClass=9&niceClass=25= class 9 or 25. - AND between different fields: adding
holder=narrows to those that also satisfy that predicate.
Party names: a comma does not separate
holder, representative and taxId are free text, and a party name carries commas, dots, & and
quotes ("PEPSICO, INC.", "MARS, INCORPORATED", "SARGENT & KRAHN"). So a comma never separates values in
these three parameters: the value travels whole, with its signs. For several names (OR), repeat the
parameter; in the body of POST /trademarks/search and in MCP, one array item per name.
# Trademarks of "PEPSICO, INC." OR "MARS, INCORPORATED" (encode each value: the comma travels as %2C)
curl -sS -G "https://api.tarno.cl/trademarks" \
--data-urlencode "holder=PEPSICO, INC." --data-urlencode "holder=MARS, INCORPORATED" \
-H "X-API-Key: $TARNO_API_KEY"
- Leading/trailing spaces are trimmed and runs of spaces count as one.
- An empty or whitespace-only value, one with fewer than 2 characters or one without a letter or
digit (
holder=%) is a400 validation_error— never "no filter". - Encode each value: in a query string a raw
+is a space (BAUSCH + LOMBtravels asBAUSCH%20%2B%20LOMB). - For one specific party, without substrings, use its id: Parties by id.
- The other lists (
niceClass,status,applicationNumber,party,includeApplicationNumber…) are numbers, ids or a closed vocabulary and still accepta,b.
q is a candidate set, not a predicate
Each q channel (exact, fuzzy, phonetic, semantic) returns at most its 200 best candidates, and the result is their
fusion. For a common term (q=cosme matches more than 200 marks) the answer is therefore a sample of the best
candidates, not every mark that matches.
Narrowing filters (filedFrom, niceClass, status, …) are applied inside each channel, before the 200 cap: with a
filter you get the best candidates of the filtered set, not those of plain q trimmed afterwards. Do not assume:
q & filteris not a subset ofq: the filter can bring marks that plainqdid not return because they fell outside the cap. Measured (2026-10-14):q=cosme⇒ 553 marks;q=cosme&filedFrom=2020-01-01⇒ 566, 359 of them absent from the first.meta.estimatedTotalis the size of that candidate set (a lower bound, never the corpus-wide count of matches). It is exact for what that query pages through, but a query with a filter and one without are not comparable: a larger total with a filter does not mean the filter widened the search.- To count or walk every mark meeting a criterion, use the field listing (without
q).
q + fields rule
q is discarded only when a competing text/identity field arrives — denomination,
applicationNumber or registrationNumber — which then drives the combined field search. The narrowing
filters (niceClass, status, signType, filedFrom/To, holder, representative, taxId) do not
discard q: they keep it and only narrow it with AND.
?q=cafe⇒ classic free-text search (ranked, carriesscore).?q=cafe&niceClass=43⇒qis kept; the result is "cafe marks in class 43".?q=cafe&denomination=nescafe⇒qis discarded (a competing field arrived);denomination=drives.- To search by denomination inside the advanced mode, use
denomination=(notq=).
Order and sort=
sort= picks the order; an explicit sort always wins. Without sort=, text is relevance (RRF) and no
text is filedOn desc. Marks with a null filedOn go last. A sort outside the list returns
400 validation_error.
Every item of results[] carries the four dates you can sort and filter by: filedOn, publishedOn,
registeredOn and expiresOn (YYYY-MM-DD or null), the same as the detail
(GET /trademarks/{applicationNumber} ≡ get_trademark). So you can show and check the order you
received without fetching each trademark's detail.
The list of sortable fields and their exact pagination lives in the reference
https://api.tarno.cl/docs— not duplicated here.
matchedFields[]
Each element of results[] may include matchedFields[], answering "why did this mark appear?". Each
entry is { field, kind } (field = matched field; kind = channel: exact, fuzzy, phonetic,
semantic). field is the name of the filter that surfaced the mark: denomination,
applicationNumber, registrationNumber, holder, representative or taxId (and highlight.field is
denomination). It is omitted when there is no identity/text match (e.g. a plain ?niceClass=9 listing). It is
additive: a client that doesn't read it keeps working.
Similarity and generic terms: the distinctive channel
With similarTo (free text), the similarity engine adds a fourth channel, distinctive. It searches
for the distinctive element of the text: what is left once the generic terms of the requested classes
are removed and joined words are split. It exists because of a real case: «ALTODESEMPEÑO CONSULTORES» in
class 35 only found marks with «CONSULTORES» and missed «MAS DESEMPEÑO».
What counts as generic:
- A neutral curated list, with a source and a review date on every entry (version
2026-09-28): connectors (de,la,the…), company forms (ltda,s.a.,spaonly as the last word and never in classes 3 and 44…), demonyms, domains, and commerce words (classes 35 and 25) or professional-services words (35 and 42). - Class frequency: a word carried by at least
max(50, 0.75 %)of the marks in the class (e.g. «cafe» in 43, «clinica» in 44). - Joined words: «altodesempeno» ⇒ «alto» + «desempeno», only if the whole word is not in the corpus and both parts are.
The discount is declared. When the channel runs, the marks it brought carry distinctive in
matchedBy, and meta publishes genericTerms (each term with its reasons), distinctiveCore (what was
searched) and decompounded. signals and score do not change: they still measure the whole text.
When it does not run. If there is nothing to discount, if only generic terms are left, or if what is left has fewer than 3 letters (e.g. «AB CONSULTORES» ⇒ «ab», which resembles anything), the channel does not run: the response is exactly what it was before and the three keys are absent. It does not run either if it fails (it is logged and the search goes on with the other channels). The similarity watch does not use it (it is switched off there).
How much it weighs in the order. In the fusion the distinctive channel weighs 2 (the semantic and lexical channels weigh 1, the phonetic one 2). The weight was calibrated on 2026-09-29 against the real corpus: 32 cases measured in production. It is the lowest weight with which the 19 marks that had to surface enter the group of the clearance report, without letting unrelated marks into the top 20 of the 13 control cases. With 2, «MAS DESEMPEÑO» ranks 32nd for «ALTODESEMPEÑO CONSULTORES» (with the previous 1.5 it ranked 77th).
Latency. When there are generic terms to discount, the channel adds about 0.7 s to the response (measured in production on 2026-09-28: ~0.73–0.79 s warm and ~1 s the first time per class). Without generic terms it adds nothing.
⛔ A word being generic is not a verdict on registrability: it is how the engine decides what to search for, and it says so.
RUT: normalization and invalid_rut
The taxId parameter matches exactly against the RUT of holder and representative. The server
normalizes the value before comparing, so all three formats are accepted:
| Input | Normalized to |
|---|---|
76.123.456-7 |
76123456-7 |
761234567 |
76123456-7 |
76123456-7 |
76123456-7 |
⭐ A well-formed
taxIdwhose check digit does not compute is no longer an error: it returns an empty result (the corpus holds people whose RUT fails the check digit). AtaxIdwhose shape is not a RUT (letters in the body, or a check digit outside0–9/K) returns400 invalid_rut— identical in REST and MCP.⭐
partyRole(since 2026-09-28) limitstaxIdto one role:holderorrepresentative. WithoutpartyRolethe RUT matches both roles, as always; it combines withrelation(e.g.partyRole=representative&relation=former: the trademarks that RUT used to represent).partyRolewithouttaxIdis400 validation_error, identical over REST and MCP.curl -s "$TARNO_BASE_URL/trademarks?taxId=76.086.428-5&partyRole=representative" -H "X-API-Key: $TARNO_API_KEY"⭐ Natural persons' RUT. Today every party's RUT is published whole and
taxIdfinds anyone. The service can switch to a mode, announced beforehand in the changelog, in which thetaxIdof a party whosekindis notlegalis masked (***678-5: the last 3 digits of the body and the check digit) and thetaxIdfilter finds legal entities only (a natural person's RUT returns an empty result, not an error). That mode is recognisable bymeta.naturalPersonTaxId: "masked"in every collection; if the key is absent, nothing changes.
Parties by id
party=<id>:<role> filters by the party's identity, not its name: it never pulls in trademarks of
parties with a similar name, and it also works for parties without a RUT (foreign ones). The id is the
one of GET /parties?q= ≡ list_parties; the role is holder or representative.
- Several values are OR'ed: a trademark comes back when any of those parties has that role
on it.
partyis AND'ed with every other filter (niceClass,status, dates…). - A role means what it means in
GET /parties/{id}/trademarks?role=: a party recorded as both holder and representative counts for both, andrelationchooses current (default), former or all relations.party=<id>:representativereturns the same trademarks asGET /parties/{id}/trademarks?role=representative, now with filters, sorting, facets and cursor. - Repeatable or comma-separated, up to 20 values. A value without the
<id>:<role>shape, or more than 20, is400 validation_error, identical over REST and MCP. An id that is no party matches no trademark. - It also applies on
POST /trademarks/search(withsimilarTo/similarToTrademark), on/insights/trademarksand on the renewal calendar; withoppositionWindowit is a400.
curl -s "$TARNO_BASE_URL/trademarks?party=306948:representative&party=1234:holder&niceClass=25" -H "X-API-Key: $TARNO_API_KEY"
Portfolio by hand: include and exclude applications
A portfolio is what its party filters say, plus some applications added by hand, minus others removed by hand; the listing filters apply on top of that:
result = ((portfolio scope ∪ includeApplicationNumber) − excludeApplicationNumber) ∩ every other filter
- The portfolio scope is the party filters:
party,holder,representativeandtaxId(withpartyRole), with theirrelation. Among themselves they are still AND'ed, as always. - Everything else is a listing filter and applies afterwards, to the included ones too:
q,denomination,status,niceClass,signType, dates, milestones,renewalStatus,liveOnly,goodsAndServicesand the batchapplicationNumber. An included application that does not match them does not appear. - Exclusion wins: an excluded application is not returned even if it matches the scope or is included.
- Without any party filter, the included applications are the portfolio (only them, ∩ the listing filters); exclusion removes just the same, also over the whole corpus.
- Order, cursor,
totalandmeta.facetsare computed on the final set. - Repeatable or comma-separated, up to 500 numbers per parameter, written as INAPI writes them
(
991652209-2,990373519-C). For long lists, use commas in theGET(500 numbers repeated one by one do not fit in a URL) or the body ofPOST /trademarks/search, which accepts the same. A malformed number, an empty list or more than 500 is400 validation_error, the same in REST and MCP. A number that does not exist adds nothing. - Also on
POST /trademarks/search(withsimilarTo/similarToTrademark),/insights/trademarksand the renewal calendar; withoppositionWindowit is a400.
curl -s "$TARNO_BASE_URL/trademarks?party=306948:representative&includeApplicationNumber=1672581&excludeApplicationNumber=991652209-2&status=registrada" -H "X-API-Key: $TARNO_API_KEY"
The portfolio object: what was added by hand is always in
With the flat fields above, an application included by hand drops out when it fails the filters that
refine the portfolio (class, status, dates…). The portfolio object tells the two kinds of filters apart:
result = (((parties ∩ refine) ∪ includeApplicationNumber) − excludeApplicationNumber) ∩ top-level filters
{
"portfolio": {
"party": ["123:holder", "456:representative"],
"refine": { "niceClass": [9, 42], "status": ["registrada"], "filedFrom": "2015-01-01" },
"includeApplicationNumber": ["1672581"],
"excludeApplicationNumber": ["991652209-2"]
},
"niceClass": [9]
}
portfolio.party: the portfolio's parties, with the same value asparty(<id>:<role>).portfolio.refine: the portfolio refinements. It accepts the same predicate filters as/trademarks/application-numbers(niceClass,status, dates, milestones,renewalStatus,liveOnly,holder/taxId,relation, the batch…) and narrows only the parties' trademarks. Itsrelationalso decides which relations the parties ofportfolio.partyare read with.q,denomination, the engines,facets, the norm filters andparty/includeApplicationNumber/excludeApplicationNumberinsiderefineare a400.portfolio.includeApplicationNumber: always in the portfolio, whateverrefinesays.portfolio.excludeApplicationNumber: always out — exclusion wins.- The top-level filters are the listing filters (what the user adds while browsing) and apply to the whole set, included applications too.
- Without
portfolio.partythe portfolio is its includes (∩ the listing), never the corpus. - Inside
portfolio, each list takes up to 10,000 numbers. - With
portfolio, a top-levelparty,includeApplicationNumberorexcludeApplicationNumberis a400 validation_error(onenot_combinableentry per field): one place for each thing. Withoutportfolio, everything stays as above. - Body only:
POST /trademarks/searchandPOST /trademarks/application-numbers(and in MCP,search_trademarksandlist_application_numbers).GET /trademarksstays flat. WithoppositionWindowit is a400; withsimilarTo/similarToTrademarksimilarity ranks inside the portfolio.
The text object: configurable text search
text configures the text search with Algolia's vocabulary. With every option at its default it
answers exactly what q answers; q/denomination stay the shortcut for text: { query }, and
combining them with text is a 400.
{
"text": {
"query": "colgate",
"queryType": "contains",
"typoTolerance": false,
"minWordSizefor1Typo": 1,
"minWordSizefor2Typos": 1,
"exactOnSingleWordQuery": "word",
"removeWordsIfNoResults": "allOptional",
"phonetic": false,
"semantic": false,
"getRankingInfo": false
}
}
| option | values (default first) | what it does |
|---|---|---|
queryType |
prefixNone, prefixLast, prefixAll, contains, exact |
How a word matches: whole; the last one may be the start of a word; every one may be; anywhere in the denomination, also inside a word; the whole denomination, word by word. |
typoTolerance |
true, false, min, strict |
Typos (Levenshtein) per word by its length; min keeps only the fewest typos; strict, those and one more. |
minWordSizefor1Typo · minWordSizefor2Typos |
1 · 1 |
Minimum word length to accept 1 and 2 typos (Algolia uses 4 and 8). |
exactOnSingleWordQuery |
word, attribute, none |
What is "exact" in the order for a one-word query: the denomination has the word; the denomination is the word; nothing. |
removeWordsIfNoResults |
allOptional, none, lastWords |
Which words are required: one is enough (more words rank first); all; all or, when no trademark has them all, the longest leading run that does. |
phonetic · semantic |
true · true |
Add the phonetic and semantic look-alikes after the keyword block. |
getRankingInfo |
false |
Adds rankingInfo to each hit: block, exact, prefix, words and typos. |
Two blocks, in this order. Configured, the keyword block comes first: a deterministic and
complete set (a trademark is in or out by the rules above, with no per-channel cap), ordered exact →
prefix (the denomination starts with the query) → more words → fewer typos → sort → application
number. Then, with phonetic or semantic, the approximate hits, with no defined edge and in
relevance order (sort does not reorder them). Without approximate hits total is the exact
size of the answer; with them (when one of those channels runs) total is absent, meta.keywordTotal is the keyword block's exact
size and meta.estimatedTotal counts both blocks (a lower bound). The cursor walks that same order
and is bound to the request. Any option away from its default (getRankingInfo: true included)
selects this engine.
querytakes at most 16 words, repeated ones included; one with no letter or digit is a400. An option that never acts with the others is a400too (typoTolerance: falsewith minimum sizes,exactwithremoveWordsIfNoResults);exactOnSingleWordQueryandremoveWordsIfNoResults, whose effect depends on the number of words, are accepted with any query.-
With the default minimum sizes (1 and 1) every word accepts 2 typos: a short word outside a portfolio may give a
422. For a general search box, useminWordSizefor1Typo: 4andminWordSizefor2Typos: 8(Algolia's). -
In
GET /trademarksit is flattened:text=colgate&textQueryType=contains&textTypoTolerance=false&textPhonetic=false&textSemantic=false. An option withouttextis a400. - In
/trademarks/application-numbersand inportfolio.refine.textit works as a set: only the keyword block, so it requiresphonetic: falseandsemantic: false(getRankingInfois not accepted). - With
portfolio, a top-leveltextnarrows and ranks the final set. textwith the batch,registrationNumber,similarTo/similarToTrademarkoroppositionWindowis a400, and so isminScorewith a configuredtext. Where a set is answered,exactOnSingleWordQuery(it only ranks) is a400too.- An approximate page whose channels are not the previous page's (one failed or timed out) is
409 cursor_stale: start again withoutcursor. With no keyword match and every approximate channel down,503: retry, it does not mean «no trademarks». - A keyword block with more than 50,000 candidates is
422 text_set_too_large: narrow the filter, use longer words or turn typo tolerance off.
# A portfolio's search box: literal, exact total.
curl -s -X POST "$TARNO_BASE_URL/trademarks/search" -H "X-API-Key: $TARNO_API_KEY" -H 'Content-Type: application/json' \
-d '{"portfolio":{"party":["306948:representative"]},"text":{"query":"colgate","queryType":"contains","typoTolerance":false,"phonetic":false,"semantic":false}}'
Pagination: keyset only
There is no offset. Pagination is keyset by cursor, for every order:
- For the next page, re-send
nextunchanged ascursor. next: nullmeans end — stop.- The cursor is opaque (base64url of the order keys); treat it as a black box.
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20" -H "X-API-Key: $TARNO_API_KEY"
# page 2: re-send the `next` from page 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20&cursor=<next>" -H "X-API-Key: $TARNO_API_KEY"
Every number of a filter, page by page
GET /trademarks/application-numbers ≡ list_application_numbers (scope brands:read) returns only
the application numbers of every trademark that matches the filter, ordered by application number
as text (not numeric: 1000001 comes before 990373519-C), in pages of up to 10,000. The filter
is the one of GET /trademarks (batch, parties, portfolio by hand, class, status, dates, milestones,
renewalStatus, liveOnly, goodsAndServices…) and the set is the one the collection would walk page
by page.
{ "applicationNumbers": ["1161630", "1192677"], "total": 2, "next": null, "cap": 10000,
"dataAsOf": "2026-10-18T03:12:44.000Z", "coverageThrough": "2026-10-17" }
limit(1..10,000, default 10,000 =cap) sets the page size.nextis the opaque cursor of the next page andnullon the last one: while it is notnullthe list is incomplete.totalis the exact count of the whole set and, likedataAsOf, is the same on every page.- Pass the cursor back as
cursorwith the same filter (limitmay change); with another filter it is a400 validation_erroroncursor. Within one walk no number repeats or goes missing. - If a corpus sync started or finished between two pages, the next one answers
409 cursor_stale: restart from page one, withoutcursor. - Predicates only:
q,denomination,similarTo,similarToTrademark,allClasses,oppositionWindow,facetsand the norm filters are a400 validation_errorwith one entry per field (the text and similarity engines rank a neighbourhood, they do not define a set). There is nosortorminScore. - A batch over 100 is
422 batch_too_large, as in the collection. POST /trademarks/application-numbersgives the same answer with the filter in the JSON body (samelimit,cursor,next,409 cursor_stale), and is the only form that takes theportfolioobject. The cursor is bound to the whole filter,portfolioincluded.
curl -sS "https://api.tarno.cl/trademarks/application-numbers?party=306948:representative&status=registrada" -H "X-API-Key: $TARNO_API_KEY"
# the next page, with the `next` of the previous one:
curl -sS "https://api.tarno.cl/trademarks/application-numbers?party=306948:representative&status=registrada&cursor=$NEXT" -H "X-API-Key: $TARNO_API_KEY"
MCP parity
The MCP tool search_trademarks accepts exactly the same parameters with identical semantics
(including sort, taxId normalization and the invalid_rut error), and returns the same JSON as
GET /trademarks for the same question. The batch is search_trademarks with
applicationNumber: [a, b, c]. See the MCP guide.
Until 2026-09-24 this route had its own twin listing tool; it was withdrawn because it was the same question as
search_trademarks. The REST route does not change.
Response time
A text search (q or denomination) queries four channels at once: exact, fuzzy, phonetic and by
meaning. It does not wait for a channel longer than 3 s: after that, and with at least one channel
that has already found matches, it answers 200 with the ones it has. Normally all four answer in under a second; the limit
only acts when one is slow.
What an answer that missed a channel looks like (the same as when a channel fails):
- the matches of that channel are not in the page, and its label (
exact,fuzzy,phonetic,semantic) is not inmatchedByormatchedFields[].kind; - if the meaning channel was missed,
signals.semanticmay benullin every result (nullis "not evaluated", never a 0); meta.estimatedTotalcounts what the channels that answered found;- ⭐
meta.degradedChannelsnames the channels that were missed (e.g.["semantic"]), in the same vocabulary asmatchedBy. Absent = every channel ran.semanticcounts only where a meaning service is configured. The same holds forsimilarTo(channelsfuzzy,semantic,distinctive) and fortext(phonetic,semantic).
The next pages of a relevance search with q, denomination or similarTo are built from the
same channels as the first one (the
cursor remembers them): if one that was in the first page fails now, the answer is the retryable
503; if one that was missed on the first page is back, it stays out and is declared in
meta.degradedChannels, so the walk neither repeats nor skips trademarks. (With text a
change of channels between pages is still 409 cursor_stale.) An explicit minScore that discards
everything still gives an empty page, with meta.degradedChannels if a channel was missed.
The same search repeated a few seconds later may bring more matches and a slightly different order.
So ask for the pages of a search one after another, without a long wait between one and the next. An
empty page is never returned because of this: if no channel has found anything at 3 s the search
keeps waiting for the first one that does, or for all of them to finish (an empty page still means
that every channel ran and none found anything); if one is missing and the rest find nothing, it is
the 503 of the table below.
The latency objective of the search (p95 < 3 s) is in the SLA. similarTo does not
have this limit.
Errors
All errors use the RFC 9457 body described in getting started.
| HTTP | code |
When |
|---|---|---|
| 400 | validation_error |
Invalid parameters (sort outside the enum, niceClass outside 1–45, malformed date). |
| 400 | invalid_rut |
A taxId whose shape is not a RUT — also with similarTo/similarToTrademark and oppositionWindow. |
| 400 | invalid_range |
A range with From > To (filedFrom/To, expiresFrom/To, registeredFrom/To, publishedFrom/To, milestoneFrom/To) — also with similarity and the opposition window. |
| 400 | validation_error |
⭐ A parameter the route does not declare (one errors[] entry per key, field = the key) — never silently ignored. |
| 400 | validation_error |
The batch combined with limit, cursor, sort, minScore, q, denomination or facets — one errors[] entry per field (field = the field, code: "not_combinable"). |
| 400 | validation_error |
⭐ The other dispatch rules —what similarity or the opposition window do not apply, similarTo with similarToTrademark, oppositionWindow without niceClass, partyRole without taxId, milestoneKind without a range, norm filters on trademarks, a goodsAndServices with nothing searchable— also carry errors[], one entry per field: code: "not_combinable" when it clashes with another field of the request (detail says which), "custom" for any other contract rule (the code schema validation gives a custom rule), "too_big"/"too_small" for a size. |
| 422 | batch_too_large |
A batch (applicationNumber) with more than 100 values. |
| 422 | text_set_too_large |
The keyword block of text has more than 50,000 candidates or is too costly to verify. |
| 401 / 403 | unauthorized / forbidden |
Key absent/invalid, or missing the brands:read scope. |
| 429 | rate_limited / quota_exceeded |
Burst limit or monthly quota. |
| 503 | service_unavailable |
⭐ A text search (q, denomination, text or similarTo) that missed some channel while the rest found nothing, or in which every channel failed. Retryable. An empty page reads as «no trademark matches», and with a channel down that is not known: until 2026-10-01 it was an empty 200 with everything down, and until 2026-11-03 with some channel down. If some channels fail and the rest find something, the answer is 200 and meta.degradedChannels declares them. A next page whose first-page channel is now down, and a page that could not be read whole, are also a 503. |
See also
- Getting started — base URL, envelope, keyset pagination, error body.
- People search —
GET /parties, the person as the subject of the query. - Authentication and scopes —
X-API-Key,brands:read. - The live OpenAPI reference at
https://api.tarno.cl/docs.