Skip to content

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, /docs is 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 (consumerId null) 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 until watchEndsOn), repeating it answers 422 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:

  1. The subscription answers at once, with baselineStatus: "pending".
  2. When the search finishes, the application moves to baselineStatus: "done" and baselineAt carries the date. You see it in GET /watch/applications.
  3. From then on its matches are in GET /watch/hits. While it is pending, the list of matches of that application may be empty: empty and pending does 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 at score 1 («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.

  1. First read, with no cursor. Page by passing next back while hasMore is true.
  2. When hasMore is false, keep that next: it is your position.
  3. 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 and next is 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 id and a new visibleSince;
  • 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 score threshold: 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; null for 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 the score and 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 in matched is an additional series of the same registration as the watched one: matchedApplicationNumber is the base number of the watched application (its nine digits) + - + suffix, and it differs from watchedApplicationNumber. On an ordinary match the key does not exist. You do not need to compare the numbers: read relation.
  • score is null and signals is {} 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), with relation: "series" plus its real score and signals. There are never two items for the same series, whichever arrives first — the alert or the search.
  • origin says who wrote the item first, not whether it is a series alert nor whether it has a score: baseline if it was the first search of your watched application, series_load if it was the pass that follows a load of series, sync if it was the daily engine (the cross or the daily review). An alert can carry a score (the engine found the series too), and one that was closed and came back arrives with origin: "sync" and may still have score: null. Infer nothing from origin: use relation to know it is a series alert and score to 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 by next brings 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 to null).

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 when 991652209-3 appears.
  • One item per watched application. If your organisation watches both 991652209 and 991652209-2, when 991652209-3 appears you get two items: one with watchedApplicationNumber: "991652209" and one with "991652209-2". The same happens with a match that resembles two of your watched applications. The applicationNumber filter shows the items of one of them.
  • Never the series you already watch. Whoever watches 991652209-2 gets no alert for 991652209-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-2 gets no alert that 991652209 exists. If the engine finds it as a match (they share a class), it arrives as an ordinary match, with a score and no relation.

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 to baselineStatus: "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 is done at 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 the 429, is that instant (in UTC), and limit is the cap. There is no Retry-After header.
  • Repeating a subscription that already exists answers 200 and 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 a detectedAt earlier 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_application returns the same WatchedApplication as REST and does not distinguish a new subscription from a repeated one (REST: 201 / 200).
  • unwatch_application returns { "applicationNumber": "N", "watched": false } (REST: 204 with 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 id or label: an organisation watches applications, ungrouped.
  • Items by denomination. Watching is by application number only.
  • Per-client filters (minScore, niceClass, allClasses, liveOnly) and baseline: 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 watch X-Tarno-Signature header and the delivery log.
  • Idempotency-Key and version on 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_conflict and concurrent_modification.

Existing watchlists are not migrated: none was in use.

See also