Similarity watch (Vigilancia)
Vigilancia answers one question: which trademarks resemble mine? You pick an application that already exists at INAPI, by its number, and Tarno looks for its matches among the live applications of the corpus. You read the result by cursor.
⚠
[BREAK]2026-10-04. Watching through watchlists (per-client lists, with items, filters, a webhook and a signing secret) was retired at once, with no coexistence period. This page describes the model that replaces it. What disappeared and what replaces it: further down.The full, always-current per-field schema lives in the interactive OpenAPI reference at
/docs(Scalar). This guide explains the watch contract and links to that reference — it does not restate the schema. When a field is not documented here,/docsis authoritative.
Throughout this guide the base URL is written as $TARNO_BASE_URL and the key as $TARNO_API_KEY,
and every call carries the X-API-Key header — just like the
getting-started guide and the authentication guide.
What Vigilancia is
- You watch an application, not a name. Only applications that already exist at INAPI are
watched, by their number (
applicationNumber). A free-text name that is not yet an application is not watched: that is what similarity search is for. - There is nothing to configure. The search uses the application's own data (its denomination, its classes). There are no per-client filters, classes or minimum score: the result is the same for anyone who watches that application.
- The table of watched applications is shared by all clients. If several organisations watch the same application, the search is done once. The only thing that belongs to each organisation is what it watches. This has a consequence worth reading: it is not secret.
- Only live applications count. An application in a terminal status (
rechazada,denegada,desistida,abandonada,anulada,caducado,vencida, by the status Tarno derives from the acts) never enters as a match, and cannot be subscribed for watching either. - Madrid marks (international registrations) are watchable and count as matches, exactly like national ones.
- A new series of the registration you watch is announced on its own. If you watch an
application of a Madrid registration — its base number or one of its series — each other
additional series of that registration arrives in the same list with
relation: "series", whether or not it shares a class with yours. What it looks like. - Your own portfolio is not a threat. On read, matches that your organisation also watches are hidden.
- There is no webhook. Matches are read by cursor with
GET /watch/hits.
There are four operations, identical over REST and MCP:
| Operation | REST | MCP | Scope |
|---|---|---|---|
| Watch an application | POST /watch/applications |
watch_application |
watch:write |
| Stop watching it | DELETE /watch/applications/{applicationNumber} |
unwatch_application |
watch:write |
| List what you watch | GET /watch/applications |
list_watched_applications |
watch:read |
| Read the matches | GET /watch/hits |
list_similarity_hits |
watch:read |
Scopes and tenancy
Vigilancia uses two scopes, on top of the same scope rules as the rest of the contract (see the authentication guide):
| Scope | Grants access to |
|---|---|
watch:read |
Reads: GET /watch/applications, GET /watch/hits. |
watch:write |
Writes: POST /watch/applications, DELETE /watch/applications/{applicationNumber}. |
A key with no scopes is granted the base read scopes, watch:read included, but not
watch:write: that one is always granted explicitly. A key with a non-empty scopes array is granted
only those listed; calling a route whose required scope is absent is rejected with
403 forbidden naming the missing scope. The scope is checked before the input is validated:
without it, a malformed request answers 403, not 400.
The organisation is resolved from the API key (the key's consumerId), never from the
request body. Consequences:
- A key with no organisation (
consumerIdnull) cannot use Vigilancia →403 forbidden(detail:API key has no owning org), even if it has the scopes. - Each key sees only what its organisation watches and the matches of that. Unwatching something
your organisation does not watch —whether another one watches it or not— answers a uniform
404.
In short: to use Vigilancia a key needs both an organisation and the watch:* scopes.
Watch an application
POST /watch/applications ≡ watch_application — scope watch:write.
Body:
| Field | Type | Notes |
|---|---|---|
applicationNumber |
string | INAPI application number: 1 to 12 digits, or an additional series of a Madrid registration (nine digits, a hyphen and INAPI's suffix: 991652209-2). A series is watched on its own, with its own classes. |
The body is strict: any other key is a 400 validation_error.
Response — a WatchedApplication:
| Field | Type | Notes |
|---|---|---|
applicationNumber |
string | The watched application. |
watchedSince |
string (ISO date-time) | Since when your organisation watches it. |
baselineStatus |
'pending' | 'done' |
Status of that application's first search. |
baselineAt |
string (ISO) | null |
When the first search finished; null while it is pending. |
terminalSince |
string (ISO) | null |
Since when the service has seen the application in a terminal status; null while it is live. See when a watch ends. |
watchEndsOn |
YYYY-MM-DD | null |
Last day of the watch of a terminal application (Chile day); it ends by itself the day after. Not a legal deadline. |
watchEndBasis |
string | null |
Where that day comes from: appeal_close, grace_end, rejection_margin or expiry_margin. |
201— the application is now watched by your organisation.200— your organisation already watched it: it returns the same subscription and does not consume the daily cap. Exception: if the application is already in a terminal status (even while its watch runs untilwatchEndsOn), repeating it answers422 application_terminal.
Over MCP, watch_application returns that same body and does not distinguish a new
subscription from a repeated one: the 201 / 200 difference exists in REST only.
The call answers at once: the search for matches does not run inside the request (see the first search).
curl
curl -sS -X POST "$TARNO_BASE_URL/watch/applications" \
-H "X-API-Key: $TARNO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "applicationNumber": "1234567" }'
{
"applicationNumber": "1234567",
"watchedSince": "2026-10-04T15:02:11.000Z",
"baselineStatus": "pending",
"baselineAt": null,
"terminalSince": null,
"watchEndsOn": null,
"watchEndBasis": null
}
TypeScript (fetch)
const res = await fetch(`${process.env.TARNO_BASE_URL}/watch/applications`, {
method: "POST",
headers: {
"X-API-Key": process.env.TARNO_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({ applicationNumber: "1234567" }),
});
if (!res.ok) {
// Problem Details (RFC 9457): { type, title, status, detail?, code, requestId, errors? }
const problem = await res.json();
throw new Error(`${res.status} ${problem.code}: ${problem.detail ?? problem.title} (requestId=${problem.requestId})`);
}
const watched = await res.json(); // 201 = new subscription · 200 = you already watched it
What is rejected
| HTTP | code |
When |
|---|---|---|
| 400 | validation_error |
A number that is neither 1 to 12 digits nor a Madrid series (991652209-2), or an extra key in the body. |
| 404 | not_found |
The application does not exist in the corpus. detail: trademark N not found. |
| 422 | application_terminal |
The application exists but its status is terminal. The status travels in applicationStatus (and in detail). Not watched. |
| 422 | watch_limit_reached |
Your organisation already has its plan's maximum of active watched applications. The maximum travels in limit. |
| 429 | watch_daily_limit_reached |
Your organisation used up today's additions. Carries limit (the cap) and resetsAt (when it reopens). |
| 503 | service_unavailable |
The watch store, or the database the plan cap is read from, does not answer. Retryable. |
applicationStatus, limit and resetsAt are top-level members of the error body, next to
code and detail — they are not nested in another object. The 429 of this cap carries no
Retry-After header: the instant it reopens is resetsAt.
{
"type": "https://api.tarno.cl/problems/watch_daily_limit_reached",
"title": "Rate limit exceeded",
"status": 429,
"detail": "the daily limit of 500 new watched applications is reached; it resets at 2026-10-05T03:00:00.000Z",
"code": "watch_daily_limit_reached",
"requestId": "…",
"limit": 500,
"resetsAt": "2026-10-05T03:00:00.000Z"
}
{
"type": "https://api.tarno.cl/problems/application_terminal",
"title": "Business rule not satisfied",
"status": 422,
"detail": "application 1234567 is in a terminal status (rechazada) and cannot be watched",
"code": "application_terminal",
"requestId": "…",
"applicationStatus": "rechazada"
}
Stop watching
DELETE /watch/applications/{applicationNumber} ≡ unwatch_application — scope watch:write.
Returns 204 No Content. If your organisation did not watch that application, 404 not_found
(detail: application N is not watched), whether another organisation watches it or not.
MCP has no empty response, so unwatch_application returns
{ "applicationNumber": "1234567", "watched": false }.
curl -sS -X DELETE "$TARNO_BASE_URL/watch/applications/1234567" -H "X-API-Key: $TARNO_API_KEY"
Once you stop watching an application, its matches no longer show in your reads and a slot of your plan is freed. The addition you made still counts towards that day's daily cap.
List what you watch
GET /watch/applications ≡ list_watched_applications — scope watch:read. Lists the applications
your organisation watches now (those you stopped watching do not appear).
| Query | Type | Notes |
|---|---|---|
cursor |
string | Opaque keyset cursor. Treat it as a black box. |
limit |
integer | Page size. Default 50, max 200. |
Response: the common envelope — { results: WatchedApplication[], limit, next, hasMore, meta }, from
the oldest subscription to the newest. next: null (and hasMore: false) = end, same keyset
semantics as in getting started. An unreadable cursor is not an error: the
first page is served.
This list does not read the corpus, so meta.dataAsOf is always null.
Each item also carries terminalSince, watchEndsOn and watchEndBasis: all three are null
while the application is live, and they announce the end of the watch once its status becomes
terminal (how a watch changes over time). A watch that has already ended is not
listed here.
curl -sS "$TARNO_BASE_URL/watch/applications?limit=50" -H "X-API-Key: $TARNO_API_KEY"
The first search
The first time anyone watches an application, Tarno crosses it against the whole corpus. That search takes seconds and runs in the background, one at a time:
- The subscription answers at once, with
baselineStatus: "pending". - When the search finishes, the application moves to
baselineStatus: "done"andbaselineAtcarries the date. You see it inGET /watch/applications. - From then on its matches are in
GET /watch/hits. While it ispending, the list of matches of that application may be empty: empty andpendingdoes not mean "no matches".
If another organisation already watched the application and its first search was done, your
subscription answers with baselineStatus: "done" and the matches are available immediately: the
search is not repeated.
A first search that fails is retried on its own, with longer and longer waits (60 s, 120 s, 240 s…
up to a maximum of 6 h between attempts). There is no "failed" status: the application stays
pending until the search finishes.
A search in which any channel of the engine (lexical, phonetic or, when configured, semantic) was
degraded counts as failed: it is not marked finished with incomplete similar marks.
Who goes first. First searches run in series, one at a time, and organisations take turns: next is the one of the organisation that was served least recently, and within an organisation, its oldest subscription. So whoever subscribes 500 applications at once does not keep someone who subscribed one waiting behind all of them. The turn is counted over all of an organisation's subscriptions, active or removed: unwatching what was already searched does not jump the queue. A search that fails also spends the turn. And an application watched by several organisations is one search that serves them all. What this does not promise: a deadline. With many subscriptions pending, yours waits for its turn.
The search walks at most 2,000 engine results per application (20 pages of 100). The engine groups sibling applications (same denomination and same holder) into one result, and each sibling is stored as a match of its own, so the stored matches may be more than 2,000.
Read the matches
GET /watch/hits ≡ list_similarity_hits — scope watch:read.
| Query | Type | Notes |
|---|---|---|
cursor |
string | Opaque keyset cursor. Treat it as a black box. |
limit |
integer | Page size. Default 50, max 200. |
applicationNumber |
string | Optional. Only the matches of that watched application. If your organisation does not watch it, the answer is 200 with an empty page — not a 404. |
Response: the common envelope — { results: SimilarityHit[], limit, next, hasMore, meta }, in the
order in which your organisation came to see each match: ascending visibleSince, then id.
This list is a feed, and its paging has a rule of its own: next is always returned — on
the last page and on an empty list too — and the end of a read is hasMore: false, not
next: null. For the next page, pass next back unchanged as cursor; when you are done, keep
the last next: it is the cursor to ask later for only what is new (how). An
unreadable cursor is not an error: the list is read from the beginning.
meta.dataAsOf is the date of the corpus data matched was read with, as in the rest of the
contract. An empty page reads no corpus and carries meta.dataAsOf: null.
curl -sS "$TARNO_BASE_URL/watch/hits?applicationNumber=1234567&limit=50" -H "X-API-Key: $TARNO_API_KEY"
What is in the list:
- All the matches of the applications your organisation watches, including those found before you subscribed. Watching answers "what resembles my trademark"; when each one appeared does not change that it is a match.
- Only matches with
score≥ 0.7. The threshold is the same for every client and cannot be set per request. The one exception is the series alert, which is not a match: it comes without a score. - Between 0.7 and 0.8, only if the match carries a word of the watched denomination, equal or
one letter away («NOMADES» → «NOMADE», «CMP» → «CMPC»). The words that count are the watched
mark's own words that are rare in its classes (fewer than 50 marks), without its generic terms;
if it has no rare word, any of its own counts; if it is only generic terms, nothing of that band
comes in. Digits glued to letters are split before comparing («NOMADE98» → «nomade 98»). This keeps
out matches that only share an ordinary word of the trade («SL Abogados» → «Abogados
Cordillera»). From 0.8 up nothing changes. The similarity search (
similarTo,similarToTrademark), the opposition window and availability do not apply this rule. - If the watched denomination has 1 or 2 letters or digits («Q», «TE», «+B», «B5»; signs and
spaces do not count, after folding case and accents), only matches of 1 to 3 letters or digits
come in, at any
score: the identical ones and the short ones that sound alike («Q» → «K», «W» → «V»). A letter sounds like any loose initial of a long name, and without this rule an acronym got hundreds of matches atscore1 («TE» → «THE JUNGLE BOOK», «G» → «G T D INTERNET»). Watched marks of 3 characters or more do not change. The similarity search, the opposition window and availability do not apply this rule either. - Never the watched application itself.
- Not the matches your organisation also watches (your own portfolio is not a threat). If you stop watching one of them, it shows again as a match of the others.
How to learn of new matches
There is no webhook: you read, and the list hands you the cursor to do it without reading it all again.
- First read, with no
cursor. Page by passingnextback whilehasMoreistrue. - When
hasMoreisfalse, keep thatnext: it is your position. - Next time, send that position as
cursor. You get only what your organisation came to see since. If there is nothing, the page is empty andnextis the very cursor you sent.
⚠ Do not loop "until next is null": in this list it never is. A client that does keeps asking
for the same empty page for ever. The end is hasMore: false.
What "new" means. The order is not the order of detection but the instant each match became
readable by your organisation (visibleSince): the latest of when it was detected, when your
current subscription to the watched application started, and the last time you stopped watching the
matched application. So your cursor also picks up what is not new to the service but is new to you:
- the old matches of an application you subscribe to today and another organisation has watched for months;
- those hidden because they are yours, which reappear when you stop watching that trademark (or
when its watch ends by itself): they come with their same
idand a newvisibleSince; - those that were closed and come back: they come with a new
id.
If you stop watching an application and subscribe to it again, that is a new subscription: all its matches are delivered again.
The same id can reach you more than once. Treat id as a key: insert or update.
A cursor belongs to its filter. The cursor you get with applicationNumber=N continues a read
with applicationNumber=N, and the one you get with no filter continues a read with no filter. Used
with another filter, the list is read from the beginning: it repeats, it never skips.
Cursors issued before 2026-10-07 are no longer recognised: the first read with one of them starts from the beginning (one full re-read, once).
What the cursor guarantees, and what it does not. The list only serves matches that are
settled: while the service has an operation in flight on the watch, whatever is written since
that operation started waits for your next read. So a match that finishes being stored late is never
left behind the cursor you already took: it can be delayed — normally milliseconds; a few
seconds during a maintenance task — never lost. For the same reason, right after a subscription
the list of that application can be empty for a moment: read again with the next you received.
What this does not cover:
- an operation of the service that lasts more than 60 seconds stops holding the list back (so that a stuck operation cannot freeze it); what that operation writes afterwards could land behind a cursor already handed out. No normal operation comes near that duration;
- a manual data correction made by the operator of the service;
- a change of the service's
scorethreshold: the matches that come to exceed it are not reordered.
If you need to rule out any of those, a read with no cursor always walks the whole list.
A closing is not announced. When a match stops being one (its status becomes terminal, or it no
longer resembles) it simply stops showing in the list: there is no event and no "closed" row to
read, and the cursor does not bring it. You find out with a full read (no cursor): what you had
stored and no longer comes was closed. If it comes back later, it does so with a new id and at
the end of your order, so your cursor picks it up.
Match shape
Each element of GET /watch/hits is a SimilarityHit:
| Field | Type | Notes |
|---|---|---|
id |
number | Match identifier while it stays open. Not the order of the list. A match that is closed and comes back has a new id. |
watchedApplicationNumber |
string | The application you watch. |
matchedApplicationNumber |
string | The application that resembles it. |
relation |
'series' (optional) |
Only present when the application in matched is an additional series of the same Madrid registration as the watched application, which is its base number or another series (series alert). On an ordinary match the key is absent (it does not arrive as null). |
score |
number | null |
Similarity score (0..1), never below the threshold. null only on an item with relation that the similarity engine did not find: no score is invented. Without relation it is always a number. |
signals |
object | What the engine saw: matchedBy (the channels it matches by), signals (per-channel strength, 0 to 1 or null) and, on a grouped sibling only, representative. See below. |
origin |
'baseline' | 'sync' | 'series_load' |
Who wrote it: the first search, the daily engine (the cross after a sync, a match that comes back or the daily review), or the pass that follows a load of Madrid series. A series alert can carry any of the three. |
detectedAt |
string (ISO date-time) | When it was detected. It may be earlier than your subscription (why). |
visibleSince |
string (ISO date-time, UTC, with microseconds) | Since when your organisation can read it: the latest of its detection, the start of your current subscription to the watched application and the last time you stopped watching the matched application. It is the order of the list (how to read what is new). Never earlier than detectedAt. |
matched |
BrandSummary | null |
The matching trademark, read from the corpus at query time; null if the application no longer exists. |
matched is the same BrandSummary shape documented in getting started
and in /docs. It is not a frozen snapshot: it carries the status the trademark has today.
{
"id": 4812,
"watchedApplicationNumber": "1234567",
"matchedApplicationNumber": "1239876",
"score": 0.83,
"signals": {
"matchedBy": ["phonetic", "fuzzy"],
"signals": { "lexical": 0.74, "semantic": null, "phonetic": 0.91 }
},
"origin": "baseline",
"detectedAt": "2026-10-04T15:02:19.000Z",
"visibleSince": "2026-10-06T09:30:00.123456Z",
"matched": { /* BrandSummary */ }
}
signals has this shape: { matchedBy: [...], signals: { channel: 0–1 }, representative?: "N" }.
matchedBy— the engine channels that found the match (exact,fuzzy,phonetic,semantic).signals— per-channel strength (lexical,semantic,phonetic), 0 to 1;nullfor a channel that did not contribute.representative— only when the match is a sibling application the engine grouped under another one (same denomination and holder): it is that other one's number, and thescoreand the signals are its own. When the match is the representative, the key is absent.
The schema publishes signals as an open object: the engine may add keys.
Direct alert: a new series of the registration you watch
An international registration (Madrid Protocol) can have more than one series in Chile, and each
additional series is a separate application numbered with the first one's number plus a suffix
(991652209-2; see Series of a Madrid registration). An additional
series is usually filed for other classes, and the watch looks for matches inside the classes of
the watched application: by similarity alone, whoever watches 991652209 would never learn that
991652209-2 exists.
So, if you watch an application of that registration — the base number (991652209) or any of
its series (991652209-2) — each other additional series arrives in GET /watch/hits as one more
item, whether or not it shares a class with yours. The example is what the watcher of the base
number gets; the watcher of 991652209-2 gets the same item with its own number in
watchedApplicationNumber when 991652209-3 appears:
{
"id": 5120,
"watchedApplicationNumber": "991652209",
"matchedApplicationNumber": "991652209-2",
"relation": "series",
"score": null,
"signals": {},
"origin": "series_load",
"detectedAt": "2026-10-12T14:03:11.000Z",
"visibleSince": "2026-10-12T14:03:11.482913Z",
"matched": { /* BrandSummary */ }
}
How to tell it from a match:
relation: "series"says the application inmatchedis an additional series of the same registration as the watched one:matchedApplicationNumberis the base number of the watched application (its nine digits) +-+ suffix, and it differs fromwatchedApplicationNumber. On an ordinary match the key does not exist. You do not need to compare the numbers: readrelation.scoreisnullandsignalsis{}when the similarity engine did not find the series (the usual case when it shares no class): nobody compared them, so there is no score, and none is invented.- If the series does share a class and the engine finds it too, it is the same item (one
id), withrelation: "series"plus its realscoreandsignals. There are never two items for the same series, whichever arrives first — the alert or the search. originsays who wrote the item first, not whether it is a series alert nor whether it has a score:baselineif it was the first search of your watched application,series_loadif it was the pass that follows a load of series,syncif it was the daily engine (the cross or the daily review). An alert can carry ascore(the engine found the series too), and one that was closed and came back arrives withorigin: "sync"and may still havescore: null. Infer nothing fromorigin: userelationto know it is a series alert andscoreto know whether it was compared.
What is the same as for any other item of the list:
- The cursor. The alert lands at the end of your order (
visibleSince), so reading bynextbrings it with nothing special to do (how to read what is new). - Your own portfolio is not a threat. If your organisation also watches that series, the alert is hidden.
- Only live applications. No alert is raised for a series in a terminal status, and the alert
stops being listed when the series becomes terminal or leaves the corpus (it comes back, with a
new
id, if it revives).
What is different:
- It is not closed for "no longer resembles". Being a series of your registration does not
depend on similarity: if a later search stops finding it, the item stays in the list and only
loses its
score(back tonull).
Who gets it and who does not:
- Whoever watches the base number (
991652209) and whoever watches another series of the registration (991652209-2): both get the alert when991652209-3appears. - One item per watched application. If your organisation watches both
991652209and991652209-2, when991652209-3appears you get two items: one withwatchedApplicationNumber: "991652209"and one with"991652209-2". The same happens with a match that resembles two of your watched applications. TheapplicationNumberfilter shows the items of one of them. - Never the series you already watch. Whoever watches
991652209-2gets no alert for991652209-2; and if you watch both the base number and that series, none under the base number either (your own portfolio is not a threat). - The base number is never announced. Only additional series are news: whoever watches
991652209-2gets no alert that991652209exists. If the engine finds it as a match (they share a class), it arrives as an ordinary match, with ascoreand norelation.
When it arrives, with nothing for you to do:
- When you start watching an application of the registration — the base number or a series —:
normally, once its first search finishes you already have the other live series of the
registration, whether or not they share a class with yours (
origin: "baseline"). It is not a guarantee tied tobaselineStatus: "done": in every case they arrive, at the latest, with the next daily review. In particular, if you watch again an application you had recently stopped watching, the search is not repeated (it isdoneat once) and the series that appeared in between arrive with the daily review. - When the service loads new series: with the pass that follows the load
(
origin: "series_load") or, failing that, with the daily review. - In the daily review: any live series of your registration that is not in your list yet — for
example, one that was in a terminal status when you started watching and revives later —
(
origin: "sync"). It can take up to a day; if a single day had a very large number of alerts to write, the rest goes out over the following days.
GET /watch/hits announces the live series. The full list of the series of a registration,
the ones in a terminal status included, is relatedSeries of the
detail.
Caps
| Cap | What it limits | When exceeded |
|---|---|---|
| Plan | How many applications your organisation may watch at the same time (active). | 422 watch_limit_reached |
| Daily | How many additions your organisation may make in a day (500 unless its plan says otherwise). | 429 watch_daily_limit_reached |
- The plan cap counts what is active. Unwatching an application frees its slot. The number is your organisation's (500 unless another one is contracted): all its API keys share the same cap and the same count.
- The daily cap counts additions, not what is active. Watching and unwatching the same application on the same day spends one addition; subscribing it again spends another. It exists so that adding and removing without end does not exhaust resources. Your organisation's plan sets it, as it sets the plan cap.
- The day is Chile's (
America/Santiago): the counter resets at midnight in Chile, not UTC.resetsAt, in the body of the429, is that instant (in UTC), andlimitis the cap. There is noRetry-Afterheader. - Repeating a subscription that already exists answers
200and does not spend the daily cap (unless the application is already terminal:422 application_terminal).
The daily cap and the similarity threshold are service settings (WATCH_DAILY_ADDS_MAX,
WATCH_MIN_SCORE), the same for everyone; they cannot be changed per request.
Watching is global, and not secret between clients
The table of watched applications is shared. That saves work —an application is crossed once even if ten organisations watch it— and has an effect that the contract accepts knowingly:
A client may infer that another organisation already watched an application. If you subscribe an application and the answer comes with
baselineStatus: "done", or its matches carry adetectedAtearlier than your subscription, someone watched it before you.
What cannot be learned: who watches it, how many organisations, or what else anyone watches. Another organisation's subscriptions are never readable.
How a watch changes over time
The first search is a picture of the day you subscribed. From there the watch moves by itself:
The daily cross. Every time a complete sync of the corpus finishes, each watched application
is compared against the applications that changed since the last time (new filings, changes of
denomination, changes of class) and are still live. New matches show in GET /watch/hits with
origin: "sync". A day with no complete sync has no cross: those changes come in with the next one.
When a match stops being listed.
- Its status becomes terminal (rejected, lapsed…). The service checks once a day, so it can take up to a day to disappear. A rejected application with an appeal filed does not count as live: only the status decides.
- It no longer exists in the corpus, and still does not at the next day's check: a single
absence closes nothing, so it takes between one and two days (meanwhile it is listed with
matched: null). If it reappears and is live, it comes back. - It no longer resembles: yours or the other one changed its denomination or classes and no
longer reaches the threshold. (This does not apply to a series alert: that one
stays listed and only loses its
score.)
When it comes back. If it is live again, or resembles again, it reappears — with a new id
and a new detectedAt.
The search can be repeated. If your watched application changes its denomination or classes, or
if the corpus is reprocessed in bulk, the service repeats the first search of that application:
baselineStatus goes back to pending for a while and then to done. The matches you already had
stay readable meanwhile.
When a watch ends. If the status of the application you watch becomes terminal, the watch is not cut that day: something can still happen to it. It is watched until a last day, which the list announces:
watchEndBasis |
Where watchEndsOn comes from |
|---|---|
appeal_close |
The deadline to appeal the rejection, when the service publishes it as a trademark milestone. |
grace_end |
The end of the renewal grace period, when the service publishes it. |
rejection_margin |
45 calendar days after the rejection (or a withdrawal, abandonment or annulment) with no such milestone. |
expiry_margin |
6 months after the expiry with no such milestone. |
watchEndsOn is the last day of the watch, not a legal deadline: deadlines, with their article,
are read from the trademark's milestones (GET /trademarks/{n} → milestones). If the application
revives before that day, the three fields go back to null and the watch goes on. watchEndsOn
is never before the day the service saw the application in a terminal status: when the
milestone or the margin had already passed, that day is the last one, so there is always at least
one day on which you can read it.
The day after watchEndsOn the watch ends by itself: it leaves GET /watch/applications, its
matches stop showing in GET /watch/hits, and it stops counting for your plan cap. From then
on DELETE answers 404 and a new subscription answers 422 application_terminal with its status.
The same happens, with no last day announced, if the application no longer exists in the corpus
and still does not at the next day's check: an absence of a single day ends no watch.
What nobody watches is kept for 10 days. When the last organisation stops watching an application, the service keeps it for 10 days with its matches (and keeps crossing it), so a new subscription within that time finds the search already done. Then it is deleted; a later subscription starts with a new first search.
If your organisation is deactivated and comes back. While an organisation is deactivated the
service does not watch for it: its applications stop counting for its cap and, if nobody else
watches them, are no longer searched nor crossed. Its list is kept. If the organisation is
reactivated, the list comes back by itself within a minute, with the watchedSince it had and
without spending the daily cap; the applications only it watched go through
baselineStatus: "pending" for a while as they are searched again. In GET /watch/hits,
everything it can read again comes after the cursor it kept, with the same ids: it will
receive again matches it had already read, plus the new ones. A watch that ended on its own in the
meantime does not come back. An organisation that was never deactivated notices none of this.
What this release does not do yet
- There is no image (logo) similarity. Watching compares by text only.
- There is no webhook and no list of ended watches: you read, and the end is announced in
watchEndsOn.
MCP
REST is equivalent to MCP: same key, same scopes, same schemas, same error codes. The MCP server exposes these Vigilancia tools:
| MCP tool | REST equivalent |
|---|---|
watch_application |
POST /watch/applications |
unwatch_application |
DELETE /watch/applications/{applicationNumber} |
list_watched_applications |
GET /watch/applications |
list_similarity_hits |
GET /watch/hits |
Two differences of shape, because an MCP tool has no HTTP codes and no empty responses:
watch_applicationreturns the sameWatchedApplicationas REST and does not distinguish a new subscription from a repeated one (REST:201/200).unwatch_applicationreturns{ "applicationNumber": "N", "watched": false }(REST:204with no body).
A refusal arrives as an error result with the same RFC 9457 body as REST —same code, same
status, same applicationStatus / limit / resetsAt—, with an empty requestId.
The weekly_watch prompt ("which matches do the applications I watch have?") takes one argument,
applicationNumber, optional. With it, it reads list_similarity_hits of that application;
without it, it reads list_watched_applications (to know what is watched and whether its first
search finished) and list_similarity_hits of all of them.
See the MCP guide for the endpoint, transport, and authentication.
Errors
Every error carries an RFC 9457 body (application/problem+json: type, title, status, detail,
code, requestId and, on a validation failure, errors[]) — described in
getting started. Branch on code.
| HTTP | code |
When |
|---|---|---|
| 400 | validation_error |
Invalid input: malformed application number, an extra key or parameter. |
| 401 | unauthorized |
Missing, malformed, unknown, or revoked key. |
| 403 | forbidden |
Missing required watch:* scope (checked before the input is validated), or the key has no organisation. |
| 404 | not_found |
Watch: the application does not exist in the corpus (trademark N not found). Unwatch: your organisation does not watch it (application N is not watched). |
| 422 | application_terminal |
The application is in a terminal status and cannot be watched. Carries applicationStatus. |
| 422 | watch_limit_reached |
Plan cap: too many active watched applications. Carries limit. |
| 429 | watch_daily_limit_reached |
Daily additions cap used up. Carries limit and resetsAt; no Retry-After header. |
| 503 | service_unavailable |
The watch store is unavailable, or (on watch only) the database the plan cap is read from does not answer; retryable. |
applicationStatus, limit and resetsAt are top-level members of the body. Reading the matches of
an application your organisation does not watch is not an error: 200 with an empty page. Each
code has the same status and the same body over REST and MCP.
What was retired on 2026-10-04
The ten watchlist operations ceased to exist, on both transports and with no coexistence period: the
REST routes no longer exist and the tools are no longer in tools/list.
| Retired (MCP) | Retired (REST) | What to use now |
|---|---|---|
create_watchlist |
POST /watchlists |
watch_application, one call per application |
add_watchlist_item |
POST /watchlists/:id/items |
watch_application |
remove_watchlist_item |
DELETE /watchlists/:id/items/:itemId |
unwatch_application |
delete_watchlist |
DELETE /watchlists/:id |
unwatch_application, one per application |
list_watchlists |
GET /watchlists |
list_watched_applications |
get_watchlist |
GET /watchlists/:id |
list_watched_applications |
list_watchlist_items |
GET /watchlists/:id/items |
list_watched_applications |
list_watchlist_hits |
GET /watchlists/:id/hits |
list_similarity_hits |
update_watchlist |
PATCH /watchlists/:id |
— (there is nothing to configure) |
list_watchlist_deliveries |
GET /watchlists/:id/deliveries |
— (there is no webhook) |
Gone with them:
- The lists. There is no list
idorlabel: an organisation watches applications, ungrouped. - Items by denomination. Watching is by application number only.
- Per-client filters (
minScore,niceClass,allClasses,liveOnly) andbaseline: the threshold is 0.7 for everyone (between 0.7 and 0.8, with the word condition; for a watched mark of 1–2 characters, only short matches), the classes are the application's own, only live ones count and the first search always runs. - The per-watchlist webhook, its
signingSecret, the watchX-Tarno-Signatureheader and the delivery log. Idempotency-Keyandversionon these writes: repeating a subscription is harmless by itself.- The frozen snapshot of the hit (
snapshot,hitKind,triggerHash,watchItemId,watchlistId): the matching trademark is read from the corpus at query time (matched). - The error codes
watchlist_too_large,watchlist_retired,idempotency_conflictandconcurrent_modification.
Existing watchlists are not migrated: none was in use.
See also
- Authentication and scopes —
X-API-Key,watch:read/watch:write, key lifecycle. - Connect your AI agent (MCP) — the same Vigilancia tools over MCP.
- Field-scoped search — similarity search for a free-text name (
similarTo). - Getting started — base URL, keyset pagination, error envelope.
- The live OpenAPI reference at
/docs— the authoritative per-field schema.