Skip to content

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/docs is 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 /trademarks also accepts a combined field-scoped surface — denomination/holder/representative/taxId/applicationNumber/registrationNumber, multi-value, AND semantics, matchedFields[] and configurable sort=. 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 cursor query parameter.
  • next: null means end of results — stop.
  • One exception: GET /watch/hits is a feed and always returns next; there the end is hasMore: 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. 5xx responses use a generic text and never leak internal details.
  • requestId — correlates your report with the server log. It is the same value carried in the X-Correlation-ID header; you can supply your own via that same request header.
  • errors[] — on a 400, details which field failed and why. ⭐ A parameter the route does not declare is also a 400 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:

  1. Short-term burst limits — two rate caps, both returning HTTP 429 code: "rate_limited" with Retry-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.
  2. Monthly quota — a per-key monthly budget. When exhausted, the API returns HTTP 429 with code: "quota_exceeded" and a Retry-After header (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