> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinakelai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Search for a mark, retrieve the full record, and subscribe to changes, in about ten minutes.

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:

```bash theme={null}
export PINAKEL_API_KEY="pk_test_..."
```

Every request sends it as a Bearer token: `Authorization: Bearer $PINAKEL_API_KEY`. See [Authentication](https://docs.pinakelai.com/authentication.md) for the details.

**1. Search**

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

```bash cURL theme={null}
curl -G "https://api.pinakelai.com/v1/trademarks" \
  -H "Authorization: Bearer $PINAKEL_API_KEY" \
  --data-urlencode "jurisdiction=AD" \
  --data-urlencode "mark_text_phrase=noky"
```

```python Python theme={null}
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"])
```

```javascript JavaScript theme={null}
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:

```json Response (abridged) theme={null}
{
  "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](https://docs.pinakelai.com/guides/pagination.md)).

**2. Retrieve the full record**

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

```bash cURL theme={null}
curl "https://api.pinakelai.com/v1/trademarks/tm_AD_2376e41e-3d24-57e3-af6f-6a176f9985ba" \
  -H "Authorization: Bearer $PINAKEL_API_KEY"
```

```python Python theme={null}
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"])
```

```javascript JavaScript theme={null}
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);
```

```json Response theme={null}
{
  "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](https://docs.pinakelai.com/concepts/trademark-record.md) explains each field.

**3. 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.

```bash cURL theme={null}
curl -G "https://api.pinakelai.com/v1/changes" \
  -H "Authorization: Bearer $PINAKEL_API_KEY" \
  --data-urlencode "jurisdiction=AD"
```

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

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

```json Response theme={null}
{
  "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](https://docs.pinakelai.com/guides/syncing.md) shows the complete loop, including how to load your starting state.

## What's next

> [card] [Searching](https://docs.pinakelai.com/guides/searching.md)
>
> Every filter, how values combine, and sorting.

> [card] [Syncing](https://docs.pinakelai.com/guides/syncing.md)
>
> Initial load, the polling loop, bursts and reloads.

> [card] [Errors](https://docs.pinakelai.com/guides/errors.md)
>
> Which errors to fix, which to retry, and how.

> [card] [API reference](https://docs.pinakelai.com/api-reference/introduction.md)
>
> Endpoints, parameters and response schemas, with a playground.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.