{"openapi":"3.1.0","info":{"title":"Pinakel Trademark Data API","description":"Structured trademark search, lookup and change tracking for docketing integrators.\n\n**To try these endpoints here:** click **Authorize**, paste your API key, then use *Try it out* on any endpoint. Keyless calls return 401.\n\nThe narrative guide, the full filter-parameter table and live coverage are at [api.pinakelai.com](/).","version":"1.0.0"},"paths":{"/v1/analytics/jurisdictions":{"get":{"tags":["analytics"],"summary":"List Jurisdictions","description":"Every register we hold analytics for, with counts and the year range.\n\nThe machine-readable coverage table — poll it to discover what is\navailable as the corpus loads.","operationId":"list_jurisdictions_v1_analytics_jurisdictions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}}},"/v1/analytics/kpis":{"get":{"tags":["analytics"],"summary":"Kpis","operationId":"kpis_v1_analytics_kpis_get","parameters":[{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Register code, e.g. US. Omit for all registers combined.","title":"Jurisdiction"},"description":"Register code, e.g. US. Omit for all registers combined."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KpiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/filings-by-year":{"get":{"tags":["analytics"],"summary":"Filings By Year","description":"Filing volume per year, split live vs dead.","operationId":"filings_by_year_v1_analytics_filings_by_year_get","parameters":[{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"}},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":1800},{"type":"null"}],"title":"Year From"}},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":1800},{"type":"null"}],"title":"Year To"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/nice-classes":{"get":{"tags":["analytics"],"summary":"Nice Classes","description":"Distribution of filings across Nice classes.","operationId":"nice_classes_v1_analytics_nice_classes_get","parameters":[{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/top-owners":{"get":{"tags":["analytics"],"summary":"Top Owners","description":"Largest filers by volume, with their live ratio.","operationId":"top_owners_v1_analytics_top_owners_get","parameters":[{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1-500","default":50,"title":"Limit"},"description":"1-500"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/law-firms":{"get":{"tags":["analytics"],"summary":"Law Firms","description":"Representative leaderboard: volume, success rate, median days to\nregistration, distinct clients.","operationId":"law_firms_v1_analytics_law_firms_get","parameters":[{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1-500","default":100,"title":"Limit"},"description":"1-500"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/squatting":{"get":{"tags":["analytics"],"summary":"Squatting","description":"Owners matching the squatting heuristic — high volume, low registration\nrate, filings scattered across unrelated classes.","operationId":"squatting_v1_analytics_squatting_get","parameters":[{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1-500","default":100,"title":"Limit"},"description":"1-500"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/analytics/collateral":{"get":{"tags":["analytics"],"summary":"Collateral","description":"Owners with security interests recorded against their marks.","operationId":"collateral_v1_analytics_collateral_get","parameters":[{"name":"jurisdiction","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1-500","default":100,"title":"Limit"},"description":"1-500"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"summary":"My Usage","description":"Current month's usage for the presented key — so an integrator can\nwatch their own quota without asking us.","operationId":"my_usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/health":{"get":{"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/jurisdictions":{"get":{"summary":"Jurisdictions","description":"Every register the API currently serves, with cached record counts.\nA jurisdiction absent from this list 404s on every lookup.","operationId":"jurisdictions_v1_jurisdictions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JurisdictionsPage"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/trademarks":{"get":{"summary":"Search Global","description":"Global structured search across every covered jurisdiction. All\nfilters are AND-combined; at least one is required. See the docs page\nfor the full parameter table and the broad-query guardrails.","operationId":"search_global_v1_trademarks_get","security":[{"APIKeyHeader":[]}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPage"}}}}},"parameters":[{"name":"application_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact application_date (YYYY-MM-DD). Mutually exclusive with application_date_from/application_date_to."},{"name":"application_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on application_date (YYYY-MM-DD)."},{"name":"application_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on application_date (YYYY-MM-DD)."},{"name":"application_number","in":"query","required":false,"schema":{"type":"string"},"description":"Exact office application number. Offices reuse numbers across series and re-filings, so results are a list."},{"name":"designated_country","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated ISO codes; records designating ANY of them."},{"name":"expiry_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact expiry_date (YYYY-MM-DD). Mutually exclusive with expiry_date_from/expiry_date_to."},{"name":"expiry_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on expiry_date (YYYY-MM-DD)."},{"name":"expiry_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on expiry_date (YYYY-MM-DD)."},{"name":"international_registration_number","in":"query","required":false,"schema":{"type":"string"},"description":"Madrid IR number — finds the national parts of one international registration."},{"name":"kind_of_mark","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated, any-of. Values: Certificate, Collective, Common right, Defensive, Geographical, Guarantee, Individual, Logotype, Other, Service, Trademark, Denomination."},{"name":"mark_feature","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated, any-of. Values: Word, Figurative, Combined, Three-dimensional, Colour, Sound, Hologram, Olfactory, Motion, Touch, Taste, Position, Other, Chimney, Combination of colours, Multimedia, Stylized characters, Pattern, Undefined."},{"name":"mark_name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact, case-insensitive. Also matches translations/transliterations we hold."},{"name":"mark_name_contains","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring of mark_name (min 3 chars). Requires a jurisdiction scope of at most 10 codes."},{"name":"mark_name_startswith","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive prefix of mark_name (min 3 chars). Requires a jurisdiction scope."},{"name":"nice_class","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated Nice classes; matches records in ANY listed class."},{"name":"nice_class_all","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated Nice classes; the record must carry ALL of them."},{"name":"office","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated registering-office codes. Differs from the register for international records: `office=WO&jurisdiction=CH` finds Madrid designations inside the Swiss register."},{"name":"opposition_period_end","in":"query","required":false,"schema":{"type":"string"},"description":"Exact opposition_period_end (YYYY-MM-DD). Mutually exclusive with opposition_period_end_from/opposition_period_end_to."},{"name":"opposition_period_end_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on opposition_period_end (YYYY-MM-DD)."},{"name":"opposition_period_end_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on opposition_period_end (YYYY-MM-DD)."},{"name":"owner_country","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated ISO codes of the proprietor's country."},{"name":"owner_name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact, case-insensitive. Matches applicant, owner or holder."},{"name":"owner_name_contains","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring of owner_name (min 3 chars). Requires a jurisdiction scope of at most 10 codes."},{"name":"owner_name_startswith","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive prefix of owner_name (min 3 chars). Requires a jurisdiction scope."},{"name":"priority_number","in":"query","required":false,"schema":{"type":"string"},"description":"Priority claim number — links a family across offices."},{"name":"publication_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact publication_date (YYYY-MM-DD). Mutually exclusive with publication_date_from/publication_date_to."},{"name":"publication_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on publication_date (YYYY-MM-DD)."},{"name":"publication_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on publication_date (YYYY-MM-DD)."},{"name":"registration_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact registration_date (YYYY-MM-DD). Mutually exclusive with registration_date_from/registration_date_to."},{"name":"registration_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on registration_date (YYYY-MM-DD)."},{"name":"registration_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on registration_date (YYYY-MM-DD)."},{"name":"registration_number","in":"query","required":false,"schema":{"type":"string"},"description":"Exact office registration number. Offices reuse numbers, so results are a list."},{"name":"representative_name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact, case-insensitive. Matches representative, agent or correspondent."},{"name":"representative_name_contains","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring of representative_name (min 3 chars). Requires a jurisdiction scope of at most 10 codes."},{"name":"representative_name_startswith","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive prefix of representative_name (min 3 chars). Requires a jurisdiction scope."},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated, any-of. Values: Registered, Pending, Abandoned, Cancelled, Unknown."},{"name":"status_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact status_date (YYYY-MM-DD). Mutually exclusive with status_date_from/status_date_to."},{"name":"status_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on status_date (YYYY-MM-DD)."},{"name":"status_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on status_date (YYYY-MM-DD)."},{"name":"termination_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact termination_date (YYYY-MM-DD). Mutually exclusive with termination_date_from/termination_date_to."},{"name":"termination_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on termination_date (YYYY-MM-DD)."},{"name":"termination_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on termination_date (YYYY-MM-DD)."},{"name":"updated_before","in":"query","required":false,"schema":{"type":"string"},"description":"ISO timestamp; exclusive upper bound on the change time."},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"},"description":"ISO timestamp; records whose content changed at/after this instant."},{"name":"vienna_code","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated Vienna codes: full (`27.05.01`) or a hierarchical prefix (`27.05`, `27`). A short prefix needs a companion filter (jurisdiction, nice_class or owner_country)."},{"name":"jurisdiction","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated register codes (up to 20), e.g. `CA,US,EM`. Omit to search every covered jurisdiction; see GET /v1/jurisdictions."},{"name":"count","in":"query","required":false,"schema":{"type":"string","enum":["capped"]},"description":"Set to `capped` to also return `matched_count` (bounded at 10,000) and `matched_count_capped`. Exact totals over the corpus are deliberately not offered."},{"name":"expand","in":"query","required":false,"schema":{"type":"string","enum":["payload"]},"description":"Set to `payload` to additionally return the full normalized source document per item (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Lowers the max limit to 50."},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction: `asc` or `desc` (default `desc`)."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["updated_at","application_date","registration_date"]},"description":"Sort field. Indexed fields only: updated_at, application_date, registration_date."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from a previous page's `next_cursor`. Bound to the exact filters/sort that produced it — reusing it with a different query returns 400 cursor_query_mismatch."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"Page size, 1-500 (max 50 with expand=payload). Default 50."}]}},"/v1/{jurisdiction_code}/trademarks":{"get":{"summary":"Search Scoped","description":"Search within one jurisdiction — identical grammar to /v1/trademarks\nminus the `jurisdiction` parameter (the path already pins it).","operationId":"search_scoped_v1__jurisdiction_code__trademarks_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"jurisdiction_code","in":"path","required":true,"schema":{"type":"string","title":"Jurisdiction Code"}},{"name":"application_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact application_date (YYYY-MM-DD). Mutually exclusive with application_date_from/application_date_to."},{"name":"application_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on application_date (YYYY-MM-DD)."},{"name":"application_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on application_date (YYYY-MM-DD)."},{"name":"application_number","in":"query","required":false,"schema":{"type":"string"},"description":"Exact office application number. Offices reuse numbers across series and re-filings, so results are a list."},{"name":"designated_country","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated ISO codes; records designating ANY of them."},{"name":"expiry_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact expiry_date (YYYY-MM-DD). Mutually exclusive with expiry_date_from/expiry_date_to."},{"name":"expiry_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on expiry_date (YYYY-MM-DD)."},{"name":"expiry_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on expiry_date (YYYY-MM-DD)."},{"name":"international_registration_number","in":"query","required":false,"schema":{"type":"string"},"description":"Madrid IR number — finds the national parts of one international registration."},{"name":"kind_of_mark","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated, any-of. Values: Certificate, Collective, Common right, Defensive, Geographical, Guarantee, Individual, Logotype, Other, Service, Trademark, Denomination."},{"name":"mark_feature","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated, any-of. Values: Word, Figurative, Combined, Three-dimensional, Colour, Sound, Hologram, Olfactory, Motion, Touch, Taste, Position, Other, Chimney, Combination of colours, Multimedia, Stylized characters, Pattern, Undefined."},{"name":"mark_name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact, case-insensitive. Also matches translations/transliterations we hold."},{"name":"mark_name_contains","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring of mark_name (min 3 chars). Requires a jurisdiction scope of at most 10 codes."},{"name":"mark_name_startswith","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive prefix of mark_name (min 3 chars). Requires a jurisdiction scope."},{"name":"nice_class","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated Nice classes; matches records in ANY listed class."},{"name":"nice_class_all","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated Nice classes; the record must carry ALL of them."},{"name":"office","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated registering-office codes. Differs from the register for international records: `office=WO&jurisdiction=CH` finds Madrid designations inside the Swiss register."},{"name":"opposition_period_end","in":"query","required":false,"schema":{"type":"string"},"description":"Exact opposition_period_end (YYYY-MM-DD). Mutually exclusive with opposition_period_end_from/opposition_period_end_to."},{"name":"opposition_period_end_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on opposition_period_end (YYYY-MM-DD)."},{"name":"opposition_period_end_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on opposition_period_end (YYYY-MM-DD)."},{"name":"owner_country","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated ISO codes of the proprietor's country."},{"name":"owner_name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact, case-insensitive. Matches applicant, owner or holder."},{"name":"owner_name_contains","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring of owner_name (min 3 chars). Requires a jurisdiction scope of at most 10 codes."},{"name":"owner_name_startswith","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive prefix of owner_name (min 3 chars). Requires a jurisdiction scope."},{"name":"priority_number","in":"query","required":false,"schema":{"type":"string"},"description":"Priority claim number — links a family across offices."},{"name":"publication_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact publication_date (YYYY-MM-DD). Mutually exclusive with publication_date_from/publication_date_to."},{"name":"publication_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on publication_date (YYYY-MM-DD)."},{"name":"publication_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on publication_date (YYYY-MM-DD)."},{"name":"registration_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact registration_date (YYYY-MM-DD). Mutually exclusive with registration_date_from/registration_date_to."},{"name":"registration_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on registration_date (YYYY-MM-DD)."},{"name":"registration_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on registration_date (YYYY-MM-DD)."},{"name":"registration_number","in":"query","required":false,"schema":{"type":"string"},"description":"Exact office registration number. Offices reuse numbers, so results are a list."},{"name":"representative_name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact, case-insensitive. Matches representative, agent or correspondent."},{"name":"representative_name_contains","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring of representative_name (min 3 chars). Requires a jurisdiction scope of at most 10 codes."},{"name":"representative_name_startswith","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive prefix of representative_name (min 3 chars). Requires a jurisdiction scope."},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated, any-of. Values: Registered, Pending, Abandoned, Cancelled, Unknown."},{"name":"status_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact status_date (YYYY-MM-DD). Mutually exclusive with status_date_from/status_date_to."},{"name":"status_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on status_date (YYYY-MM-DD)."},{"name":"status_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on status_date (YYYY-MM-DD)."},{"name":"termination_date","in":"query","required":false,"schema":{"type":"string"},"description":"Exact termination_date (YYYY-MM-DD). Mutually exclusive with termination_date_from/termination_date_to."},{"name":"termination_date_from","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive lower bound on termination_date (YYYY-MM-DD)."},{"name":"termination_date_to","in":"query","required":false,"schema":{"type":"string"},"description":"Inclusive upper bound on termination_date (YYYY-MM-DD)."},{"name":"updated_before","in":"query","required":false,"schema":{"type":"string"},"description":"ISO timestamp; exclusive upper bound on the change time."},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string"},"description":"ISO timestamp; records whose content changed at/after this instant."},{"name":"vienna_code","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated Vienna codes: full (`27.05.01`) or a hierarchical prefix (`27.05`, `27`). A short prefix needs a companion filter (jurisdiction, nice_class or owner_country)."},{"name":"count","in":"query","required":false,"schema":{"type":"string","enum":["capped"]},"description":"Set to `capped` to also return `matched_count` (bounded at 10,000) and `matched_count_capped`. Exact totals over the corpus are deliberately not offered."},{"name":"expand","in":"query","required":false,"schema":{"type":"string","enum":["payload"]},"description":"Set to `payload` to additionally return the full normalized source document per item (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Lowers the max limit to 50."},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction: `asc` or `desc` (default `desc`)."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["updated_at","application_date","registration_date"]},"description":"Sort field. Indexed fields only: updated_at, application_date, registration_date."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque keyset cursor from a previous page's `next_cursor`. Bound to the exact filters/sort that produced it — reusing it with a different query returns 400 cursor_query_mismatch."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"Page size, 1-500 (max 50 with expand=payload). Default 50."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{jurisdiction_code}/trademarks/{uid}":{"get":{"summary":"By Uid","description":"Primary-key fetch: (jurisdiction_code, uid) is the stable identity of\na record across updates.","operationId":"by_uid_v1__jurisdiction_code__trademarks__uid__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"jurisdiction_code","in":"path","required":true,"schema":{"type":"string","title":"Jurisdiction Code"}},{"name":"uid","in":"path","required":true,"schema":{"type":"string","title":"Uid"}},{"name":"expand","in":"query","required":false,"schema":{"description":"Set to `payload` to additionally return the full normalized source document (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Documents can reach ~1 MB.","title":"Expand","type":"string","enum":["payload"]},"description":"Set to `payload` to additionally return the full normalized source document (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Documents can reach ~1 MB."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/changes":{"get":{"summary":"Changes Global","operationId":"changes_global_v1_changes_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Return records whose content changed at/after this instant (date or ISO timestamp)","title":"Since"},"description":"Return records whose content changed at/after this instant (date or ISO timestamp)"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Durable frontier cursor from a previous page/session","title":"Cursor"},"description":"Durable frontier cursor from a previous page/session"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"Page size, 1-5000 (max 200 with expand=payload).","default":500,"title":"Limit"},"description":"Page size, 1-5000 (max 200 with expand=payload)."},{"name":"expand","in":"query","required":false,"schema":{"description":"Set to `payload` to additionally return the full normalized source document (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Documents can reach ~1 MB.","title":"Expand","type":"string","enum":["payload"]},"description":"Set to `payload` to additionally return the full normalized source document (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Documents can reach ~1 MB."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{jurisdiction_code}/changes":{"get":{"summary":"Changes Scoped","operationId":"changes_scoped_v1__jurisdiction_code__changes_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"jurisdiction_code","in":"path","required":true,"schema":{"type":"string","title":"Jurisdiction Code"}},{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Return records whose content changed at/after this instant (date or ISO timestamp)","title":"Since"},"description":"Return records whose content changed at/after this instant (date or ISO timestamp)"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Durable frontier cursor from a previous page/session","title":"Cursor"},"description":"Durable frontier cursor from a previous page/session"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"Page size, 1-5000 (max 200 with expand=payload).","default":500,"title":"Limit"},"description":"Page size, 1-5000 (max 200 with expand=payload)."},{"name":"expand","in":"query","required":false,"schema":{"description":"Set to `payload` to additionally return the full normalized source document (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Documents can reach ~1 MB.","title":"Expand","type":"string","enum":["payload"]},"description":"Set to `payload` to additionally return the full normalized source document (all parties with addresses, goods/services text, publications, priorities, event history, images). Omitted entirely when not requested — never null. Documents can reach ~1 MB."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesPage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ChangesPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TrademarkDetail"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Durable frontier cursor, present on every non-empty page: persist the latest one and resume from it in a later session. null only on an empty page = caught up."}},"type":"object","required":["items"],"title":"ChangesPage"},"Coverage":{"properties":{"jurisdiction":{"type":"string","title":"Jurisdiction","description":"Register the figures cover, or ALL"},"rows_loaded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rows Loaded","description":"Records held for this register"},"backfill_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backfill Status","description":"Pipeline lifecycle: in_progress | complete | paused | not_started"},"is_sample":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Sample","description":"True while this register is a partial load — treat figures as indicative, not exhaustive"},"last_ingested_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Ingested Date"}},"type":"object","required":["jurisdiction"],"title":"Coverage","description":"What the numbers in this response were computed over.\n\nPresent on every response by design. The corpus is being loaded\ngradually, so an analytics figure without its basis invites a consumer to\nrender it as complete — which is the one failure mode a third party\nbuilding their own UI cannot detect for themselves."},"Envelope":{"properties":{"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items"},"coverage":{"$ref":"#/components/schemas/Coverage"}},"type":"object","required":["items","coverage"],"title":"Envelope"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"JurisdictionInfo":{"properties":{"jurisdiction_code":{"type":"string","title":"Jurisdiction Code"},"record_count":{"type":"integer","title":"Record Count"},"data_current_through":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Data Current Through","description":"The daily pipeline frontier for this register"}},"type":"object","required":["jurisdiction_code","record_count"],"title":"JurisdictionInfo"},"JurisdictionsPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/JurisdictionInfo"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"JurisdictionsPage"},"KpiResponse":{"properties":{"kpis":{"additionalProperties":true,"type":"object","title":"Kpis"},"coverage":{"$ref":"#/components/schemas/Coverage"}},"type":"object","required":["kpis","coverage"],"title":"KpiResponse"},"SearchPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TrademarkDetail"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque keyset cursor for the next page; null = no more results. Bound to this exact query."},"matched_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matched Count","description":"Only with count=capped: matches, capped at 10000"},"matched_count_capped":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Matched Count Capped","description":"Only with count=capped: true when the cap was hit"}},"type":"object","required":["items"],"title":"SearchPage"},"TrademarkDetail":{"properties":{"jurisdiction_code":{"type":"string","title":"Jurisdiction Code","description":"Register this record came from, e.g. CA"},"uid":{"type":"string","title":"Uid","description":"Stable Pinakel identifier, opaque text; unique within jurisdiction_code"},"office":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Office","description":"Registering office per the source record; differs from jurisdiction_code for international (e.g. Madrid 'WO') records"},"application_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Application Number"},"registration_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registration Number"},"mark_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mark Name"},"status":{"type":"string","title":"Status","description":"Normalized: Registered/Pending/Abandoned/Cancelled/Unknown"},"tm5_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tm5 Status","description":"TM5 status string where the office provides one"},"kind_of_mark":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind Of Mark"},"mark_feature":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mark Feature"},"application_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Application Date"},"registration_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Registration Date"},"publication_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Publication Date"},"expiry_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Expiry Date"},"renewal_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Renewal Date"},"termination_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Termination Date"},"opposition_period_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Opposition Period End"},"status_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Status Date","description":"When the office last changed the status — the office-side change signal"},"external_update_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"External Update Date","description":"Office-side record timestamp, where the office publishes one"},"record_update_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Record Update Date","description":"Pinakel pipeline batch date (attribute only — sync on /changes, not this)"},"nice_classes":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Nice Classes"},"vienna_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Vienna Codes"},"owner_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Owner Names","description":"Normalized applicant/owner/holder names (search form, lowercased)"},"owner_countries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Owner Countries"},"representative_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Representative Names","description":"Normalized representative/agent/correspondent-of-record names (search form, lowercased) — offices disagree where the responsible agent is recorded, so all such roles are merged"},"international_registration_numbers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"International Registration Numbers","description":"Madrid IR number(s) linked to this record — the cross-register family key"},"priority_numbers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Priority Numbers","description":"Priority claim numbers — how a family is linked across offices"},"designated_countries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Designated Countries","description":"Madrid designated country codes, where the record carries designations"},"first_seen_at":{"type":"string","format":"date-time","title":"First Seen At","description":"When Pinakel first ingested this record"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the record content last changed in Pinakel — the /changes sync key"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload","description":"Full normalized document (expand=payload)"}},"type":"object","required":["jurisdiction_code","uid","status","first_seen_at","updated_at"],"title":"TrademarkDetail"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"Your API key, e.g. pk_live_… . A Bearer token in the Authorization header is accepted too.","in":"header","name":"X-API-Key"}}}}