{"openapi":"3.1.0","info":{"title":"Pinakel Trademark Analytics API","description":"Aggregate trademark analytics — filing trends, Nice-class distribution, owner and representative leaderboards — for platforms building their own dashboards.\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\nEvery response carries a `coverage` block describing what the figures were computed over; while a register is still loading, `coverage.is_sample` is true and the numbers are indicative, not exhaustive.\n\nThe narrative guide is at [api.pinakelai.com/analytics](/analytics).","version":"1.0.0"},"paths":{"/v1/health":{"get":{"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/usage":{"get":{"tags":["account"],"summary":"My Usage","description":"Current month's usage for the presented key — so an integrator can\nwatch their own quota without asking us.\n\nOn common_router because metering is not a record-API feature: analytics\ncalls are counted against the same quota and invoiced from the same\ntable, so an analytics-only customer needs this as much as a record one.\nIt reports every product the key carries, whichever service answers.","operationId":"my_usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/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_jurisdictions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/kpis":{"get":{"tags":["analytics"],"summary":"Kpis","operationId":"kpis_v1_kpis_get","security":[{"APIKeyHeader":[]}],"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/filings-by-year":{"get":{"tags":["analytics"],"summary":"Filings By Year","description":"Filing volume per year, split live vs dead.","operationId":"filings_by_year_v1_filings_by_year_get","security":[{"APIKeyHeader":[]}],"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/nice-classes":{"get":{"tags":["analytics"],"summary":"Nice Classes","description":"Distribution of filings across Nice classes.","operationId":"nice_classes_v1_nice_classes_get","security":[{"APIKeyHeader":[]}],"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/top-owners":{"get":{"tags":["analytics"],"summary":"Top Owners","description":"Largest filers by volume, with their live ratio.","operationId":"top_owners_v1_top_owners_get","security":[{"APIKeyHeader":[]}],"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/law-firms":{"get":{"tags":["analytics"],"summary":"Law Firms","description":"Representative leaderboard: volume, success rate, median days to\nregistration, distinct clients.","operationId":"law_firms_v1_law_firms_get","security":[{"APIKeyHeader":[]}],"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/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_squatting_get","security":[{"APIKeyHeader":[]}],"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/collateral":{"get":{"tags":["analytics"],"summary":"Collateral","description":"Owners with security interests recorded against their marks.","operationId":"collateral_v1_collateral_get","security":[{"APIKeyHeader":[]}],"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"}}}}}}}},"components":{"schemas":{"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"},"KpiResponse":{"properties":{"kpis":{"additionalProperties":true,"type":"object","title":"Kpis"},"coverage":{"$ref":"#/components/schemas/Coverage"}},"type":"object","required":["kpis","coverage"],"title":"KpiResponse"},"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"}}},"servers":[{"url":"/analytics"}]}