Getting started
Tarno exposes a neutral read contract over the INAPI trademark corpus: a REST API (no version prefix) plus an MCP server, both backed by the same query layer and the same data. This guide takes you from zero to a first authenticated call against the REST API.
The complete, always-current per-field schema lives in the interactive OpenAPI reference at
https://api.tarno.cl/docs(Scalar). This guide explains how to onboard and links to that reference — it does not restate the schema. When a field is not documented here,https://api.tarno.cl/docsis authoritative.
1. Base URL
The REST API is served over HTTPS at https://api.tarno.cl. The contract no longer uses a version
prefix: every resource lives directly at the root, e.g. https://api.tarno.cl/trademarks. The interactive
(Scalar) reference is at https://api.tarno.cl/docs.
A handful of routes are intentionally public (no key required):
| Path | Purpose |
|---|---|
/health |
Liveness/readiness probe (200 ok / 503 degraded) |
/docs |
Interactive OpenAPI (Scalar) reference — https://api.tarno.cl/docs |
/metrics |
Prometheus metrics (internal network only) |
Every business route (e.g. /trademarks) is protected and requires an API key (see below and the
authentication guide).
2. Get an API key
API keys are issued by the operator, out of band, from the operator portal. There is no self-service sign-up endpoint — you don't create your own key. Ask your operator for a read key; they hand you an opaque key string and tell you which scopes it carries (the full list is in the scopes table). See the authentication guide for scopes, the lifecycle (rotate / revoke / expiry), and the exact error semantics.
Store the key as an environment variable and never commit it:
export TARNO_API_KEY="<API_KEY>" # the opaque key string your operator issued
Every example in this portal uses the obvious
<API_KEY>placeholder. Replace it with your real key at runtime; never hardcode a key in a versioned file.
3. Your first authenticated call: GET /trademarks
Send the key in the X-API-Key request header. GET /trademarks searches or lists trademark summaries.
curl
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=5" \
-H "X-API-Key: $TARNO_API_KEY"
TypeScript (fetch)
const baseUrl = "https://api.tarno.cl";
const apiKey = process.env.TARNO_API_KEY!; // "<API_KEY>"
const res = await fetch(`${baseUrl}/trademarks?q=cafe&limit=5`, {
headers: {
"X-API-Key": apiKey,
"X-Correlation-ID": "<your-correlation-id>", // optional; echoed on every response
},
});
if (!res.ok) {
// application/problem+json (RFC 9457)
const problem = await res.json();
throw new Error(`${problem.status} ${problem.code}: ${problem.detail} (requestId=${problem.requestId})`);
}
const page = await res.json(); // { results: Trademark[], limit, next, hasMore, total, meta }
console.log(page.results.length, "results; next =", page.next);
A successful response is a keyset page:
{
"results": [
{
"applicationNumber": "123456",
"registrationNumber": null,
"denomination": "CAFE EXAMPLE",
"status": "en_tramite",
"statusInapi": null,
"statusStale": false,
"signType": "mixta",
"filedOn": "2023-01-15",
"expiresOn": null,
"publishedOn": "2023-02-01",
"registeredOn": null,
"renewalStatus": null,
"milestones": [],
"score": 0.87
}
],
"limit": 20,
"next": "eyJvIjoyMH0",
"hasMore": true,
"meta": { "dataAsOf": "2026-09-20T19:05:06Z", "coverageThrough": "2026-09-17" }
}
score is an absolute 0–1 confidence (the highest per-channel signal, not the internal RRF value, which only orders the list; so it may not decrease monotonically) and is present only on the free-text search path (q=); it
is omitted on a plain filtered listing. ⭐ Free-text search omits total: the key only travels in
the batch (applicationNumber=), in the unfiltered listing, and in filtered listings with a count ≤
10,000. status and signType are strings
holding the code (e.g. "en_tramite", "mixta"), or null. statusInapi and statusStale are always present:
statusInapi is INAPI's raw status only when it differs from status (otherwise null), and statusStale is
true exactly when they differ ("INAPI has not flipped it yet").
For the exact set of trademark fields, see the reference at https://api.tarno.cl/docs.
4. Filtering and keyset pagination
GET /trademarks accepts these query parameters:
| Param | Type | Notes |
|---|---|---|
q |
string | Free-text search (full-text + fuzzy). When present, results are ranked and carry score. Omit it for a plain filtered listing. |
niceClass |
integer[] | Nice class filter, 1–45; accepts several. |
status |
string[] | Status codes (controlled catalog); accepts several. |
signType |
string[] | Sign-type codes (controlled catalog); accepts several. |
filedFrom |
YYYY-MM-DD |
Lower bound on filing date (filedOn >=). |
filedTo |
YYYY-MM-DD |
Upper bound on filing date (filedOn <=). |
limit |
integer | Page size. Default 20, max 100. |
cursor |
string | Opaque keyset cursor (see below). Treat it as a black box. |
Field-scoped search.
GET /trademarksalso accepts a combined field-scoped surface —denomination/holder/representative/taxId/applicationNumber/registrationNumber, multi-value,ANDsemantics,matchedFields[]and configurablesort=. See the field-scoped search guide.
Pagination is keyset-based, not offset. Each response carries an opaque next cursor:
- To get the next page, pass it back unchanged as the
cursorquery parameter. next: nullmeans end of results — stop.- One exception:
GET /watch/hitsis a feed and always returnsnext; there the end ishasMore: false(Similarity watch).
# page 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20" -H "X-API-Key: $TARNO_API_KEY"
# page 2 — pass the `next` cursor from page 1
curl -sS "https://api.tarno.cl/trademarks?q=cafe&limit=20&cursor=<next>" -H "X-API-Key: $TARNO_API_KEY"
To get a trademark with its full sections (parties + annotations + encumbrances + classes + norms), call
GET /trademarks/{applicationNumber}?expand=parties,annotations,encumbrances,classes,norms
(norms also requires the legal:read scope; without it, drop it from expand):
curl -sS "https://api.tarno.cl/trademarks/123456?expand=parties,annotations,encumbrances,classes,norms" \
-H "X-API-Key: $TARNO_API_KEY"
An unknown application number returns 404 not_found.
The insights:read family (GET /system/freshness, GET /system/sync-runs) is documented in the
authentication guide and in the reference at https://api.tarno.cl/docs.
5. Errors (RFC 9457)
Every error — validation, authentication, not-found, rate limit and unexpected server errors — is
returned with the RFC 9457 application/problem+json body, with the same shape in REST and MCP:
{
"type": "https://api.tarno.cl/problems/validation_error",
"title": "Request validation failed",
"status": 400,
"detail": "`offset` was withdrawn from the contract: paginate with `limit` + `cursor`",
"code": "validation_error",
"requestId": "74c953c7-24fc-492d-80ed-c6e1b18327fe",
"errors": [ { "field": "offset", "code": "unrecognized_keys", "detail": "…" } ]
}
code— a stable, neutral token to branch on (see the table below). It is the contract.title/detail— human-readable; their wording may change without being a break.5xxresponses use a generic text and never leak internal details.requestId— correlates your report with the server log. It is the same value carried in theX-Correlation-IDheader; you can supply your own via that same request header.errors[]— on a400, details which field failed and why. ⭐ A parameter the route does not declare is also a400 validation_error, with one entry per key (field= the key,code: "unrecognized_keys"): the API never silently ignores what it does not understand.
| HTTP | code |
When |
|---|---|---|
| 400 | validation_error |
Invalid query/parameters (schema validation failed). |
| 401 | unauthorized |
API key absent, malformed, unknown or revoked. |
| 403 | forbidden |
Valid key, but missing the scope the route requires. |
| 404 | not_found |
Unknown application number, or an unknown route. |
| 409 | ambiguous_selector |
The reference (to an INAPI document or a statute) matches more than one resource. |
| 409 | cursor_stale |
The cursor of GET /trademarks/application-numbers belongs to an earlier corpus (a sync started or finished between pages): restart without cursor. |
| 405 | method_not_allowed |
HTTP method not allowed (the MCP only accepts POST). |
| 413 | payload_too_large |
The request body exceeds the accepted size. |
| 422 | business rule (e.g. out_of_coverage) |
The request is valid yet cannot be served: e.g. a range the holiday calendar does not claim to cover. Never answered with an empty/partial list — see Holiday calendar. |
| 429 | rate_limited |
Short-term burst limit exceeded (see below). |
| 422 | application_terminal · watch_limit_reached |
Watch: the application is in a terminal status, or your organisation reached its plan cap — see Similarity watch. |
| 429 | quota_exceeded |
Monthly quota exhausted (see below). Carries Retry-After. |
| 429 | watch_daily_limit_reached |
Daily cap of watch additions. Carries limit and resetsAt; no Retry-After: wait until resetsAt. |
| 500 | internal_error |
Unexpected service error; generic text, no internal details. |
| 502 | logo_analysis_invalid_output |
The model that describes a logo returned an invalid output. |
| 503 | service_unavailable |
A dependency is unavailable right now (the database out of resources, the watch store, the meaning channel of a semantic search, the trademark search with every channel down…); retryable. |
| 503 | coverage_not_declared |
The holiday calendar declares no covered year; retryable. |
| 504 | query_timeout |
Query/upstream timeout; retryable. Like every 5xx, it does not leak internal details. |
⭐ A code has exactly one status, the same over REST and MCP (since 2026-09-30, ERR-1). The table
lives in the service code and both transports read it. Until that date a
database resource error (disk, memory) was 500 internal_error over REST; it is now 503 service_unavailable.
6. Rate limits and quota
Two independent limits protect the read contract:
- Short-term burst limits — two rate caps, both returning HTTP 429
code: "rate_limited"withRetry-After: one per key (default 300 requests per 60 s, identical on REST and MCP) and one per client IP (default 100 requests / minute on REST and 30 per second on the MCP). Details in the authentication guide. - Monthly quota — a per-key monthly budget. When exhausted, the API returns HTTP 429 with
code: "quota_exceeded"and aRetry-Afterheader (seconds until the quota window resets at month-end). This same quota applies identically in REST and MCP — see the MCP guide.
Every served authenticated response carries the standard RateLimit-Limit, RateLimit-Remaining and
RateLimit-Reset headers, which describe the key's monthly quota (Reset = seconds until the month-end
reset; an unlimited key only carries RateLimit-Limit: unlimited). The burst and quota 429s carry Retry-After (the watch one, watch_daily_limit_reached, carries resetsAt in the body):
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1209600
{ "type": "https://api.tarno.cl/problems/quota_exceeded", "title": "Rate limit exceeded", "status": 429,
"detail": "Monthly quota exceeded", "code": "quota_exceeded", "requestId": "…" }
Respect Retry-After: wait the indicated number of seconds before retrying.
Next steps
- Authentication and scopes —
X-API-Key, the scopes table, key lifecycle and the full401/403/429semantics. - Connect your AI agent (MCP) — the
mcp.tarno.clendpoint and thesearch_trademarks/get_trademarktools. - Code samples — copy-paste REST and MCP clients.
- The live OpenAPI reference at
https://api.tarno.cl/docs— the authoritative per-field schema.