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.

​

Authentication

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

Authorization: Bearer pk_live_...

See Authentication for key types, rotation and the errors you can get.

​

Endpoints

Method and path	Operation	Summary
GET /v1/trademarks	searchTrademarks	Search trademarks
GET /v1/trademarks/{id}	retrieveTrademark	Retrieve a trademark
POST /v1/trademarks/batch	batchRetrieveTrademarks	Retrieve up to 100 trademarks
GET /v1/changes	listChanges	List changed trademarks
GET /v1/jurisdictions	listJurisdictions	List jurisdictions
GET /v1/jurisdictions/{code}	retrieveJurisdiction	Retrieve a jurisdiction
GET /v1/usage	retrieveUsage	Retrieve your usage
GET /v1/health	getHealth	Service health

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.

​

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:

{
  "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.

​

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)
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
WWW-Authenticate	401, 403	The Bearer challenge
Deprecation, Sunset, Link	Deprecated endpoints	See Versioning
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.