> ## 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.

# API reference

> Base URL, authentication, request and response conventions, status codes and headers.

## Base URL

```
https://api.pinakelai.com/v1
```

All endpoints are under `/v1`. v1 changes only by addition; see [Versioning](https://docs.pinakelai.com/guides/versioning.md).

## Authentication

Send your key as a Bearer token on every request except `GET /v1/health` and `GET /v1/openapi.json`:

```http theme={null}
Authorization: Bearer pk_live_...
```

See [Authentication](https://docs.pinakelai.com/authentication.md) for key types, rotation and the errors you can get.

## Endpoints

| Method and path | Operation | Summary |
| - | - | - |
| `GET /v1/trademarks` | `searchTrademarks` | [Search trademarks](https://docs.pinakelai.com/api-reference/trademarks/search.md) |
| `GET /v1/trademarks/{id}` | `retrieveTrademark` | [Retrieve a trademark](https://docs.pinakelai.com/api-reference/trademarks/retrieve.md) |
| `POST /v1/trademarks/batch` | `batchRetrieveTrademarks` | [Retrieve up to 100 trademarks](https://docs.pinakelai.com/api-reference/trademarks/batch.md) |
| `GET /v1/changes` | `listChanges` | [List changed trademarks](https://docs.pinakelai.com/api-reference/changes/list.md) |
| `GET /v1/jurisdictions` | `listJurisdictions` | [List jurisdictions](https://docs.pinakelai.com/api-reference/jurisdictions/list.md) |
| `GET /v1/jurisdictions/{code}` | `retrieveJurisdiction` | [Retrieve a jurisdiction](https://docs.pinakelai.com/api-reference/jurisdictions/retrieve.md) |
| `GET /v1/usage` | `retrieveUsage` | [Retrieve your usage](https://docs.pinakelai.com/api-reference/account/usage.md) |
| `GET /v1/health` | `getHealth` | [Service health](https://docs.pinakelai.com/api-reference/account/health.md) |

The operation ids are stable, so they are safe to use as method names in generated clients. The OpenAPI 3.1 document is at [`https://api.pinakelai.com/v1/openapi.json`](https://api.pinakelai.com/v1/openapi.json).

## Requests

* **Query parameters** are `snake_case`.
* **Several values** of one parameter are combined with OR: repeat the parameter (`status=registered&status=pending`), or, for codes, enumerations and classes, separate them with commas (`status=registered,pending`). Different parameters are combined with AND.
* **Date ranges** are `<field>_date_from` and `<field>_date_to`, inclusive, as `YYYY-MM-DD`.
* **Timestamps** (the feed's `since`) are RFC 3339 with `Z` or an offset.
* **Booleans** are `true` or `false`; anything else is a 400.
* **Unknown parameters are rejected** with 400, with a did-you-mean hint. They are never ignored.
* **Request bodies** (batch retrieve only) are `application/json`, at most 64 KB.

## Responses

Responses are JSON (`application/json`), UTF-8.

* **A single resource** is a top-level object with an `object` field, such as `"object": "trademark"`.
* **A list** is an envelope:

```json theme={null}
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null,
  "unavailable_jurisdictions": []
}
```

* **Every field is always present.** `null` means the value is not stated; arrays are never `null`.
* **Dates** are `YYYY-MM-DD`; **timestamps** are UTC with microseconds and `Z`, such as `2026-11-10T09:02:13.512000Z`.
* **Errors** are `application/problem+json` documents; see [Errors](https://docs.pinakelai.com/api-reference/errors.md).

## Status codes

| Code | Meaning |
| - | - |
| 200 | Success |
| 301, 302 | Redirect from a retired path |
| 304 | Not modified (retrieve with `If-None-Match`) |
| 400 | The request is invalid; nothing was done |
| 401 | Missing, unknown or revoked key |
| 403 | The key does not include the Data API |
| 404 | No such record, register or endpoint |
| 405 | Method not allowed on this path |
| 410 | A retired path |
| 413, 415 | Batch body too large, or not JSON |
| 422 | The query is too broad or took too long; narrow it |
| 429 | Rate limit or monthly quota exceeded |
| 500 | Unexpected error |
| 503 | Temporarily unavailable; retry after `Retry-After` |

The API never returns 504.

## Headers

**Request headers**

| Header | Use |
| - | - |
| `Authorization` | `Bearer <key>` |
| `Content-Type` | `application/json`, for batch retrieve |
| `If-None-Match` | An `ETag` from a previous retrieve |
| `Accept-Encoding` | `gzip` to receive compressed responses of 1 KB or more |

**Response headers**

| Header | When | Meaning |
| - | - | - |
| `X-Request-Id` | Always | `req_` + a ULID. Equals `request_id` in errors. Quote it to support. |
| `RateLimit-Policy`, `RateLimit` | Authenticated requests | Your key's limits and what remains (see [Rate limits & usage](https://docs.pinakelai.com/api-reference/rate-limits.md)) |
| `Retry-After` | 429 and 503 | Seconds to wait before retrying |
| `ETag` | Retrieve, and its 304 | Weak validator of the response body |
| `Cache-Control` | Always | See [Caching](https://docs.pinakelai.com/guides/caching.md) |
| `WWW-Authenticate` | 401, 403 | The Bearer challenge |
| `Deprecation`, `Sunset`, `Link` | Deprecated endpoints | See [Versioning](https://docs.pinakelai.com/guides/versioning.md#deprecation) |
| `Strict-Transport-Security` | Always | HTTPS only |

## CORS

Browsers may call the API only from `https://docs.pinakelai.com`, for this site's playground. Call the API from your servers. `GET /v1/health` allows any origin.


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