Skip to content

2026-09-23 migration guide — the contract cut

⭐ This is the guide for the CURRENT contract. On the day of the cut, the /v1 prefix stops responding and no old URL survives: not in the server, not in the parity harness, not in the load scripts, not in the documentation. Every endpoint changes URL at once, with no redirect and no grace period.

What is NOT repeated here is the schema. The authoritative field-by-field inventory is the OpenAPI reference generated from the schemas the server actually uses: https://docs.tarno.cl (in the repo, contract/openapi.generated.yaml). Duplicating it here would create a second source that drifts — which is exactly what this whole phase exists to fix. This page describes the migration (the old → new map), not the schema.

The record of every change, with its [BREAK]/[BEH]/[ADD], is in the contract changelog. The notice to the single consumer — the Tarno app — is one letter, not several.

In one sentence

On the day of the cut, /v1 stops responding and the whole contract moves at once to: unprefixed routes in English, field names in English, one envelope shape, one pagination, one error body, one sort vocabulary — and labels stop being header-negotiated and arrive as a three-language object. Event collapse becomes the default.

No redirect, no version header, no grace period. What breaks is done once and announced once (the single letter).

The three maps, complete

The three maps are copied from the contract register (CHANGELOG-CONTRACT.md, entries 38-04..38-14 and their retouches) — not reconstructed from the diff.


1 · Route map — REST (old → new)

The ones that disappear have no direct replacement: they fall into a filter or an expansion, noted on each row.

old (stops responding) new disappearance
GET /v1/brands GET /trademarks —
POST /v1/brands/batch GET /trademarks?applicationNumber=a,b,c (up to 100) the batch becomes a filter
GET /v1/brands/similar?q= POST /trademarks/search with similarTo similarity becomes a search engine
GET /v1/brands/{n}/similar POST /trademarks/search with similarToTrademark ídem
GET /v1/oppositions/open POST /trademarks/search with oppositionWindow: "open" the opposition window is a filter, not a route
GET /v1/brands/{n} GET /trademarks/{applicationNumber} —
GET /v1/brands/{n}/report GET /trademarks/{applicationNumber}?expand=… ⭐ the report stops being a route: it is the detail with expand=
GET /v1/brands/{n}/opposition GET /trademarks/{n}/annotations?family=opposition ⭐ the opposition timeline was always a filter over annotations
(only inline in the mark) GET /annotations/{id} · POST /annotations/search · GET /trademarks/{n}/annotations ⭐ the annotation becomes its own resource
GET /v1/personas GET /parties (+ GET /parties/{id}, GET /parties/{id}/trademarks) —
GET /v1/insights/filings-over-time GET /insights/trademarks?groupBy=filedMonth the 5 routes fuse into one with groupBy
GET /v1/insights/by-estado GET /insights/trademarks?groupBy=status ídem
GET /v1/insights/by-class GET /insights/trademarks?groupBy=niceClass ídem
GET /v1/insights/by-holder GET /insights/trademarks?groupBy=holder ídem
GET /v1/insights/by-representante GET /insights/trademarks?groupBy=representative (+ POST /insights/trademarks/search) ídem
GET /v1/feriados · GET /v1/feriados/cobertura GET /holidays coverage always travels in meta.coverage
GET /v1/freshness GET /system/freshness operational stuff moves under /system
GET /v1/sync-runs GET /system/sync-runs ídem
GET /v1/watch* /watchlists · /watchlists/{id} · /watchlists/{id}/items · /watchlists/{id}/hits · /watchlists/{id}/deliveries the old style is retired entirely. ⚠ The /watchlists routes were retired too, on 2026-10-04: watching is now /watch/applications and /watch/hits (guide)

NEW routes (replace nothing; nothing to migrate): GET /sections · GET /sections/{code} · GET /legal-norms · GET /legal-norms/{id} · GET /nice-classes · GET /system/coverage · GET /system/vigilance-horizon · GET /system/me · GET /health (root, no API key).

Filters. A single English set, the same shape in /trademarks, /trademarks/search and /insights: q, applicationNumber, niceClass, status, signType, holder, representative, taxId, filedFrom/filedTo, expiresFrom/expiresTo, registeredFrom/registeredTo, publishedFrom/publishedTo, relation=current|former|all, similarTo, similarToTrademark, oppositionWindow, facets, and since 2026-09-23 goodsAndServices (citedNorm/article/letter belong to annotations: on trademarks, 400). expand=parties,annotations,encumbrances,classes,norms only on GET /trademarks/{n} (⛔ no fields=). holder/representative/taxId are lists (OR inside the parameter).


2 · Field map — (old → new)

Copied from the [BREAK] entry of 38-07 (the wire-vocabulary layer), plus the parties fields of 38-06.

today (retired) from the cut
nroSolicitud / nroRegistro applicationNumber / registrationNumber
denominacion denomination
estado / tipoSigno status / signType
fechaPresentacion / fechaPublicacion / fechaRegistro / fechaVencimiento filedOn / publishedOn / registeredOn / expiresOn
seccion / seccionNombre / seccionEtiqueta / seccionTipo section / sectionName / sectionLabel / sectionFamily
seccionActo / seccionActoNombre / seccionActoEtiqueta act / actName / actLabel
observacion / observacionCompleta observation / observationDerived
personas / personasHistoricas / anotaciones / gravamenes parties / formerParties / annotations / encumbrances
clases / clasesHistoricas / clase / descripcion classes / formerClasses / number / goodsAndServices
titulares / representantes holders / representatives
renovaciones / ultimaRenovacion renewals / lastRenewalOn
ventanaOposicion oppositionWindow
estadoDerivado / estadoDesactualizado ⚠ since 2026-09-23 (D11): the derived state travels in status (derivedStatus was withdrawn); INAPI's literal in statusInapi, only when it differs; the flag in statusStale, in every view
fecha / nombre / pais / rol / identificador date / name / country / role / taxId
variantes duplicates
vigencia / soloVigentes relation / liveOnly
traduccion / descripcionEtiqueta / imagenUrl translation / imageDescription / imageUrl
holiday fecha / nombre / tipo / origen date / name / type / origin

parties (the person becomes an entity with a role — 38-06):

today from the cut
tipo / tipoOrigen kind (natural|legal|unknown) / kindSource (tax_id|suffix|manual, now nullable)
nombre name
identificador taxId
pais country
observacion jurisdictionClause
nombrePublicado publishedName
revision (boolean) review ({ reason }, the reason in code)
region / comuna / regionNombre / comunaNombre territory ({ regionCode, regionName, communeCode, communeName, unknownCommune })
marcasTotal trademarkCount

⚠ What does NOT change name, now or in a later pass:

  • ~~categoria / ambito (37D) keep their name~~ — ⛔ no longer: [BREAK] of 2026-09-23. The rule of the cut is that contract LABELS (field names) are English while VALUES may stay Spanish; seven Spanish labels were left and were renamed at once, on REST and MCP: categoria/categoriaEtiqueta → category/categoryLabel, ambito/ambitoEtiqueta → scope/scopeLabel, eventoId → eventId (annotations), titular → holders (each item of the trademark list and search), observacion → observation (in the mark's parties[]) and filters.clase → filters.niceClass (watchlists). And the mark's parties[].kind now publishes the /parties vocabulary (natural|legal|unknown), not juridica/desconocido. Exact table in CHANGELOG-CONTRACT.md.
  • protectionDescription keeps its name.
  • Code VALUES stay in Spanish. status is still "en_tramite", signType "mixta", classes[].status "concedida". Translating the codes to English (pending, word, granted…) is a later pass, not done yet.
  • INAPI literals (section codes M5/A07T, the annotation text, the published spelling, the jurisdiction clause, the RUT) are not translated: the field name is translated, never the value.

3 · Tool map — MCP (old → new)

Copied from the [BREAK] entry of 38-11 (names aligned with the manifest, no alias and no window) and from plans 38-05/38-06.

today (retired) from the cut
search_brands / get_brands_batch list_trademarks (the batch is a filtered collection)
find_similar_brands search_trademarks with similarTo / similarToTrademark
get_open_oppositions search_trademarks with oppositionWindow: "open"
get_brand_detail get_trademark
get_brand_report get_trademark with expand=
get_brand_opposition list_trademark_annotations (family=opposition)
search_personas list_parties + get_party + list_party_trademarks
insights_filings_over_time get_trademark_insights (groupBy=filedMonth)
insights_by_estado get_trademark_insights (groupBy=status)
insights_by_class get_trademark_insights (groupBy=niceClass)
insights_by_holder get_trademark_insights (groupBy=holder)
insights_by_representante get_trademark_insights (groupBy=representative)
get_feriados / get_feriados_cobertura list_holidays
get_freshness / get_sync_runs get_system_freshness / list_sync_runs
watch_register create_watchlist
watch_list list_watchlists
watch_get get_watchlist
watch_patch update_watchlist
watch_delete delete_watchlist
watch_list_hits list_watchlist_hits
watch_list_deliveries list_watchlist_deliveries
watch_list_items list_watchlist_items
watch_add_item add_watchlist_item
watch_remove_item remove_watchlist_item

⚠ 2026-10-04: the ten *_watchlist* tools in the right-hand column were retired in turn. They are replaced by watch_application, unwatch_application, list_watched_applications and list_similarity_hits; the map is in the Vigilancia guide.

NEW tools (nothing to migrate) — there are 14: explain_section_code · get_annotation · get_legal_norm · get_party · get_section · get_system_coverage · get_system_me · get_vigilance_horizon · list_legal_norms · list_nice_classes · list_party_trademarks · list_sections · search_annotations · search_trademark_insights.

⚠ get_system_coverage was listed here as a rename of a list_system_coverage that never existed. It is new: day-by-day ingest coverage arrived with the cut.

Additive: the catalogs become MCP resources (iris://catalogs/states, sections, nice-classes, holidays/{year}), plus three prompts (availability_check, case_history, weekly_watch) and a real version (2026-09-23) with the four rules in the server instructions.


The minor maps, also copied

Error codes (38-04)

old new where
fuera_de_cobertura out_of_coverage 422 on the calendar
cobertura_no_declarada coverage_not_declared 503 on the calendar
invalid_input validation_error MCP, all tools
invalid_input batch_too_large the batch cap (now a 422, not a validation failure)

Headers (38-04)

old new note
X-Request-Id X-Correlation-ID accepted from the client and returned on EVERY response
X-Quota-Limit RateLimit-Limit —
X-Quota-Remaining RateLimit-Remaining —
X-Quota-Reset RateLimit-Reset ⛔ also changes its VALUE: from an absolute instant to seconds remaining

Retry-After is kept. ETag + If-None-Match (304) on every individual object; catalogs declare Cache-Control.

sort tokens (38-12 + the 38-07 retouch)

⭐ Sort tokens are published ONLY in English. The retouch retired the Spanish aliases and renamed the status family.

retired token replacement
relevancia relevance
recientes filedOn:desc
antiguas filedOn:asc
estado / estado:asc / estado:desc status / status:asc / status:desc
fechaActualizacion:asc / fechaActualizacion:desc retired with no replacement (it sorted by OUR pipeline's date, not an INAPI fact)

The six fields that survive, each asc|desc: status, filedOn, denomination, expiresOn, registeredOn, publishedOn — plus relevance. A token not listed is a 400 validation_error.


The SHAPE changes — what is not migrated by renaming

These are not name equivalences: they are shape changes a consumer has to wire up afresh.

(a) The envelope — ONE shape for every collection

📌 HISTORY — from 2026-09-20 to 2026-09-23 there were TWO envelopes. The trademark collections (GET /trademarks, POST /trademarks/search, the batch, GET /parties/{id}/trademarks) used { items, nextCursor, dataAsOf, estimatedTotal } (the batch, { items, notFound, dataAsOf }). Since the 2026-09-23 evening [BREAK] there is one envelope, no exception — see § «2026-09-23 · single envelope».

{ "results": [ /* … */ ], "limit": 20, "next": "eyJvIjoyMH0", "hasMore": true, "total": 14,
  "meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" } }

It replaces ten envelopes, six paginations and three limit defaults in EVERY collection. The names data, items, nextCursor and the bare array cease to exist. An individual resource responds as a flat object, no wrapper, with freshness in headers (Iris-Data-As-Of, Iris-Coverage-Through).

  • total only travels when it is exact and cheap; where counting costs a scan, the key is absent. The search estimate travels as meta.estimatedTotal (a lower bound), never as total.
  • ⛔ No parameter changes the TYPE of a response. ?envelope= is retired: the four endpoints that returned a bare array by default now always return the envelope, just like MCP. This is the first time REST and MCP agree on this.

(b) Pagination — a single cursor

limit (default 20, max 100) + an opaque keyset cursor. offset is retired. A stray ?offset= is a 400 validation_error that names the replacement. Over 10 M annotations the offset is slow and lies about the total; the cursor is cut at the cap instead of offering a page nobody can defend. A cursor issued for a different sort degrades to page one, not to a false page.

(c) The label — from negotiated string to a THREE-language object

seccionEtiqueta/seccionActoEtiqueta/categoriaEtiqueta (now categoryLabel)/ambitoEtiqueta (now scopeLabel)/renovacion.etiqueta were a string negotiated by Accept-Language. Now each label is a LocalizedString with the three languages at once, null where there is no translation:

{ "code": "registered",
  "label": { "es-CL": "Registrada", "en": "Registered", "pt-BR": "Registrada" },
  "source": { "label": "(R) Registrada" } }
  • Header negotiation (Accept-Language) is retired (an MCP agent sends no headers, and a response that depends on a header cannot be cached).
  • The response is identical with any Accept-Language and with none.

(d) Event collapse — becomes the DEFAULT (38-08)

Before, an annotation with copies of the same fact (Estado Diario and the record page publishing the same thing) was returned one per row unless you asked ?dedupe=true. Now collapse is the default: each fact is returned once, and whoever wants the copies asks with dedupe=false. Collapse is logical: it never deletes a row — the copies stay published in duplicates[].

Each annotation gains two always-present fields: versionsOfFact (how many rows describe this SAME fact) and versionsDiffer (true when another version exists that is neither identical nor contained). The notice is neutral: it says THAT another version exists and HOW to ask for it, never WHICH one says it (provenance leaves the contract). Guarantee: renewals/lastRenewalOn are identical with dedupe=true and with dedupe=false.

(e) Errors — RFC 9457, a single body

Content-Type: application/problem+json, the same body in REST, in the jobs service and in MCP:

{ "type": "https://api.tarno.cl/problems/validation_error",
  "title": "Request validation failed", "status": 400,
  "detail": "`offset` was retired from the contract…", "code": "validation_error",
  "requestId": "74c953c7-…", "errors": [ { "field": "offset", "code": "custom", "detail": "…" } ] }

code is what a client compares, and it is always in English. title/detail are for humans and can change without being a [BREAK]; changing a code is one. requestId is the same value as X-Correlation-ID. A 5xx does not carry internal detail to the client.

status means
400 validation — the request is malformed or a parameter is out of range
404 does not exist — the resource is not there, or is not yours (uniform across tenants)
422 business rule — the request is VALID and still cannot be served

(f) The "no value" semantics on the mark (38-05)

The detail and the report declared the same fields with two null semantics (one omitted them, the other gave them null). null wins: the eleven application scalars (registrationNumber, status, signType, filedOn, expiresOn, publishedOn, registeredOn, translation, imageDescription, protectionDescription, imageUrl) are always present, null when they have no value. ⚠ The exception is kept: category/scope (formerly categoria/ambito, and their labels) keep being omitted when "we don't know" (5.5 % of marks).

What to do: if you distinguished "nroRegistro" in obj from obj.nroRegistro === null, now only the latter happens for those eleven. ?? defaultValue keeps working; Object.hasOwn(...) on them is now always true. INAPI's '0' sentinel is still not published (before omitted, now null).

(g) The person becomes parties — one entity with a role (38-06)

Holder, applicant, representative and opponent are the same entity with a role where it intervenes — and the same party stops appearing three times. territory is typed (codes WITH their names, unknownCommune as its own field; null = foreign party). trademarkCount does not filter: people with no marks keep showing up with their zero.


2026-09-23 · single envelope — the [BREAK] that closes the contract's loose ends

One incompatible change, dated 2026-09-23 (evening), recorded in CHANGELOG-CONTRACT.md:

before after
trademarks: { items, nextCursor, dataAsOf, estimatedTotal, facets, mode } the common envelope: { results, limit, next, hasMore, meta } — meta.dataAsOf, meta.coverageThrough, meta.estimatedTotal, meta.facets, meta.mode
batch: { items, notFound, dataAsOf } the same envelope, meta.notFound, exact total, next: null
facets.clase · facets.estado meta.facets.niceClass · meta.facets.status
matchedFields[].field: nombre/titular/representante/rut denomination/holder/representative/taxId
highlight.field: "nombre" highlight.field: "denomination"
kindSource on the trademark: rut/sufijo tax_id/suffix (as in /parties)
an unknown parameter was ignored (200) 400 validation_error, one errors[] entry per key; MCP: input error
?envelope=, expand on the trademark list: ignored 400
GET /trademarks/{n}: dedupe default false default true (also on GET /trademarks/{n}/annotations, which now accepts it)
the batch ignored the other filters it APPLIES them; meta.notFound = only what does not exist; limit/cursor/sort/minScore/q/denomination/facets with the batch → 400
catalogs without Cache-Control (except /holidays) catalog Cache-Control on /nice-classes, /sections, /legal-norms and their objects
— new goodsAndServices filter (goods-and-services text)
sort=status by INAPI's literal by the published (derived) status

Action for the consumer (checklist)

  1. Change the URL base: drop the /v1 prefix and apply the route map (§1). No redirect: an old URL responds with absence, not a 301.
  2. Apply the field map (§2) to everything you deserialize, and the tool map (§3) to every MCP call.
  3. Rewrite collection reads against the results[] envelope (§a) and the cursor (§b): out with data, items, nextCursor, the bare array and offset — in EVERY collection, trademarks included.
  4. Stop negotiating Accept-Language: labels come in a three-language object (§c).
  5. Assume collapse by default (§d): if you need the copies, ask with dedupe=false.
  6. Migrate error bodies to RFC 9457 and the codes/headers of the minor maps.
  7. Fix sort literals to the six English fields (§sort).
  8. Verify against the generated reference: https://docs.tarno.cl.

To run it with an assistant step by step, use migracion-38-prompt.md.


Map sources: CHANGELOG-CONTRACT.md 38-04..38-14 + retouches · contract/openapi.generated.yaml (the generated reference, not duplicated here).