Quickstart

This guide makes three calls: a search, a retrieve, and a subscription to the changes feed. The examples use the Andorran register (AD), which is small, so results are easy to check.

Before you start

You need an API key. Pinakel issues keys when your agreement is set up; use the Request API key button at the top of this page if you do not have one. A pk_test_ key returns the same data as a live key, is not billed, and is the right key for trying things out. Put the key in an environment variable so it stays out of your code and your shell history:

export PINAKEL_API_KEY="pk_test_..."

Every request sends it as a Bearer token: Authorization: Bearer $PINAKEL_API_KEY. See Authentication for the details.

Search for marks containing the word “noky” in the Andorran register. Filters are query parameters; different parameters are combined with AND.

curl -G "https://api.pinakelai.com/v1/trademarks" \
  -H "Authorization: Bearer $PINAKEL_API_KEY" \
  --data-urlencode "jurisdiction=AD" \
  --data-urlencode "mark_text_phrase=noky"

import os

import requests

API = "https://api.pinakelai.com/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['PINAKEL_API_KEY']}"

resp = session.get(f"{API}/trademarks",
                   params={"jurisdiction": "AD", "mark_text_phrase": "noky"},
                   timeout=30)
resp.raise_for_status()
for tm in resp.json()["data"]:
    print(tm["id"], tm["mark"]["text"], tm["status"]["value"])

const API = "https://api.pinakelai.com/v1";
const headers = { Authorization: `Bearer ${process.env.PINAKEL_API_KEY}` };

const params = new URLSearchParams({ jurisdiction: "AD", mark_text_phrase: "noky" });
const res = await fetch(`${API}/trademarks?${params}`, { headers });
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const page = await res.json();
for (const tm of page.data) console.log(tm.id, tm.mark.text, tm.status.value);

The response is a list of trademark_summary objects:

Response (abridged)

{
  "object": "list",
  "data": [
    {
      "object": "trademark_summary",
      "id": "tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba",
      "jurisdiction": "AD",
      "mark": { "text": "NOKY", "translation": null, "transliteration": null, "feature": "word", "kind": "individual" },
      "status": { "value": "registered", "category": "live", "date": "2009-06-05" },
      "primary_owner": { "name": "ESSITY PLD FRANCE SAS", "country": null },
      "links": { "self": "https://api.pinakelai.com/v1/trademarks/tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba" }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "unavailable_jurisdictions": []
}

has_more: false means this is the only page. When it is true, send the same request again with cursor set to next_cursor (see Pagination).

Retrieve the full record

Store the id. It is the record’s permanent identifier, and it fetches the full record:

curl "https://api.pinakelai.com/v1/trademarks/tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba" \
  -H "Authorization: Bearer $PINAKEL_API_KEY"

tm_id = "tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba"
resp = session.get(f"{API}/trademarks/{tm_id}", timeout=30)
resp.raise_for_status()
record = resp.json()
print(record["parties"]["owners"][0]["name"], record["classification"]["nice_classes"])

const id = "tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba";
const rec = await (await fetch(`${API}/trademarks/${id}`, { headers })).json();
console.log(rec.parties.owners[0].name, rec.classification.nice_classes);

Response

{
  "object": "trademark",
  "id": "tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba",
  "jurisdiction": "AD",
  "office": "AD",
  "origin_office": null,
  "identifiers": {
    "application_number": "48000",
    "registration_number": "48000",
    "international_registration_numbers": [],
    "priority_claims": []
  },
  "mark": {
    "text": "NOKY",
    "translation": null,
    "transliteration": null,
    "feature": "word",
    "kind": "individual"
  },
  "status": {
    "value": "registered",
    "category": "live",
    "date": "2009-06-05",
    "office_status": null,
    "office_status_code": null
  },
  "dates": {
    "application": "2009-06-05",
    "registration": "2009-06-05",
    "publication": "2025-07-28",
    "expiry": "2029-06-05",
    "renewal": null,
    "termination": null,
    "opposition_period_end": null
  },
  "classification": {
    "nice_classes": [8, 16, 21],
    "national_classes": [],
    "similar_group_codes": [],
    "vienna_codes": []
  },
  "parties": {
    "owners": [
      {
        "name": "ESSITY PLD FRANCE SAS",
        "name_translated": null,
        "name_key": "ESSITY PLD FRANCE",
        "country": null,
        "address": "BOULEVARD VICTOR-HUGO, CS 80047, 151, POSTAL CODE: 93400, CITY: SAINT-OUEN, FRANCE",
        "entity": "SAS",
        "roles": ["owner", "applicant"]
      }
    ],
    "representatives": [
      {
        "name": "JOSEP CARBONELL GIMENO",
        "name_translated": null,
        "name_key": "JOSEP CARBONELL GIMENO",
        "country": "AD",
        "address": "C. Bonaventura Riberaygua, 39, 4t - 3a Andorra la Vella",
        "entity": null,
        "roles": ["representative"]
      }
    ]
  },
  "designated_countries": [],
  "media": {
    "has_image": false
  },
  "updated_at": "2026-11-10T09:02:13.512000Z",
  "source": {
    "processed_on": "2026-11-10"
  },
  "links": {
    "self": "https://api.pinakelai.com/v1/trademarks/tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba"
  }
}

Every field is always present. null means the office did not state the value, so "country": null above means the Andorran record gives the owner’s address but no country code. The trademark record explains each field.

Subscribe to changes

The changes feed lists every record that changed, in publication order. The first call, without since or cursor, subscribes from now: it returns an empty page and a cursor.

curl -G "https://api.pinakelai.com/v1/changes" \
  -H "Authorization: Bearer $PINAKEL_API_KEY" \
  --data-urlencode "jurisdiction=AD"

resp = session.get(f"{API}/changes", params={"jurisdiction": "AD"}, timeout=30)
resp.raise_for_status()
cursor = resp.json()["next_cursor"]   # store this durably

const sub = await (await fetch(`${API}/changes?jurisdiction=AD`, { headers })).json();
const cursor = sub.next_cursor; // store this durably

Response

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": "eJxtjUEKgzAQRf9l1lnEJJhkrgO9QKHrXqC4K0VbJbSE0g1dZxZmnN7_v8xqmkAEpSv4E1Hqr8n2Ng.Mq4yGbF7tRk",
  "unavailable_jurisdictions": [],
  "feed_start": "2026-11-30T02:41:09.000000Z",
  "complete_through": "2026-12-01T08:15:00.204118Z"
}

Store next_cursor. At most every 15 minutes, call the feed again with the same jurisdiction and the stored cursor, upsert each trademark by its id, and store the new next_cursor after every page. Syncing shows the complete loop, including how to load your starting state.

What’s next

Searching

Every filter, how values combine, and sorting.

Syncing

Initial load, the polling loop, bursts and reloads.

Errors

Which errors to fix, which to retry, and how.

API reference

Endpoints, parameters and response schemas, with a playground.

Get started

Concepts

Data

Use cases

Working with the API

Before you start

What’s next

Searching

Syncing

Errors

API reference

​Before you start

​What’s next

Searching

Syncing

Errors

API reference

Before you start

What’s next