{"openapi":"3.1.0","info":{"title":"Markbase","description":"USPTO Trademark Search API — search, filter, and retrieve data from 14M+ U.S. trademarks.","version":"2026.9.8"},"components":{"schemas":{},"parameters":{}},"paths":{"/health":{"get":{"tags":["System"],"summary":"Health check","responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"meilisearch":{"type":"string"},"documents":{"type":"number"},"indexing":{"type":"boolean"}},"required":["status","meilisearch","documents","indexing"]}}}},"503":{"description":"Service degraded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"}},"required":["status","error"]}}}}}}},"/status":{"get":{"tags":["System"],"summary":"Service status and uptime","responses":{"200":{"description":"Full service status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"uptime":{"type":"string"},"uptime_seconds":{"type":"number"},"started_at":{"type":"string"},"timestamp":{"type":"string"},"version":{"type":"string"},"services":{"type":"object","properties":{"api":{"type":"object","properties":{"status":{"type":"string"},"response_time_ms":{"type":"number"}},"required":["status","response_time_ms"]},"meilisearch":{"type":"object","properties":{"status":{"type":"string"},"response_time_ms":{"type":"number"},"documents":{"type":"number"},"indexing":{"type":"boolean"}},"required":["status","response_time_ms","documents","indexing"]}},"required":["api","meilisearch"]},"system":{"type":"object","properties":{"memory_mb":{"type":"number"},"platform":{"type":"string"}},"required":["memory_mb","platform"]}},"required":["status","uptime","uptime_seconds","started_at","timestamp","version","services","system"]}}}}}}},"/stats":{"get":{"tags":["System"],"summary":"Index statistics","responses":{"200":{"description":"Index stats","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"number"},"indexing":{"type":"boolean"},"field_distribution":{"type":"object","additionalProperties":{"type":"number"}}},"required":["documents","indexing","field_distribution"]}}}},"503":{"description":"Stats unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/info":{"get":{"tags":["System"],"summary":"Index coverage info","description":"Shows total documents, oldest/newest filing dates, and last update time","responses":{"200":{"description":"Index info","content":{"application/json":{"schema":{"type":"object","properties":{"total_documents":{"type":"number"},"requests_served":{"type":"number"},"indexing":{"type":"boolean"},"oldest_filing":{"type":"object","nullable":true,"properties":{"serial_number":{"type":"string"},"filing_date":{"type":"string","nullable":true},"word_mark":{"type":"string","nullable":true}},"required":["serial_number","filing_date","word_mark"]},"newest_filing":{"type":"object","nullable":true,"properties":{"serial_number":{"type":"string"},"filing_date":{"type":"string","nullable":true},"word_mark":{"type":"string","nullable":true}},"required":["serial_number","filing_date","word_mark"]},"last_updated":{"type":"string","nullable":true}},"required":["total_documents","requests_served","indexing","oldest_filing","newest_filing","last_updated"]}}}},"503":{"description":"Info unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/search":{"get":{"tags":["Search"],"summary":"Search trademarks","description":"Full-text fuzzy search with filters, facets, and pagination","parameters":[{"schema":{"type":"string","description":"Search query","example":"nike"},"required":false,"description":"Search query","name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by status code","example":"800"},"required":false,"description":"Filter by status code","name":"status_code","in":"query"},{"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"}],"description":"Filter by international classification code"},"required":false,"description":"Filter by international classification code","name":"international_code","in":"query"},{"schema":{"type":"string","description":"Filter filing date from (YYYYMMDD)","example":"20200101"},"required":false,"description":"Filter filing date from (YYYYMMDD)","name":"filing_date_from","in":"query"},{"schema":{"type":"string","description":"Filter filing date to (YYYYMMDD)","example":"20251231"},"required":false,"description":"Filter filing date to (YYYYMMDD)","name":"filing_date_to","in":"query"},{"schema":{"type":"string","description":"Filter by owner country","example":"US"},"required":false,"description":"Filter by owner country","name":"owner_country","in":"query"},{"schema":{"type":"string","description":"Filter by owner state","example":"CA"},"required":false,"description":"Filter by owner state","name":"owner_state","in":"query"},{"schema":{"type":"string","description":"Sort field (e.g. filing_date:asc)"},"required":false,"description":"Sort field (e.g. filing_date:asc)","name":"sort","in":"query"},{"schema":{"type":"string","description":"Page number","example":"1"},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"string","description":"Results per page (max 100)","example":"20"},"required":false,"description":"Results per page (max 100)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Set to 'true' to include facet distribution counts (slightly slower)","example":"true"},"required":false,"description":"Set to 'true' to include facet distribution counts (slightly slower)","name":"facets","in":"query"},{"schema":{"type":"string","description":"Set to 'full' to highlight matches in goods_services and owner_name too (slower for multi-word queries)","example":"full"},"required":false,"description":"Set to 'full' to highlight matches in goods_services and owner_name too (slower for multi-word queries)","name":"highlight","in":"query"},{"schema":{"type":"string","description":"Set to 'csv' to download results as CSV instead of JSON","example":"csv"},"required":false,"description":"Set to 'csv' to download results as CSV instead of JSON","name":"format","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"hits":{"type":"array","items":{"type":"object","properties":{"serial_number":{"type":"string"},"registration_number":{"type":"string","nullable":true},"transaction_date":{"type":"string","nullable":true},"filing_date":{"type":"string","nullable":true},"filing_date_num":{"type":"number","nullable":true},"filing_year":{"type":"number","nullable":true},"registration_date":{"type":"string","nullable":true},"status_code":{"type":"string","nullable":true},"status_date":{"type":"string","nullable":true},"word_mark":{"type":"string","nullable":true},"mark_drawing_code":{"type":"string","nullable":true},"attorney_name":{"type":"string","nullable":true},"renewal_date":{"type":"string","nullable":true},"published_for_opposition_date":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true},"owner_address":{"type":"string","nullable":true},"owner_city":{"type":"string","nullable":true},"owner_state":{"type":"string","nullable":true},"owner_country":{"type":"string","nullable":true},"legal_entity_type":{"type":"string","nullable":true},"goods_services":{"type":"string","nullable":true},"international_codes":{"type":"array","items":{"type":"string"}},"us_codes":{"type":"array","items":{"type":"string"}},"first_use_anywhere_date":{"type":"string","nullable":true},"first_use_in_commerce_date":{"type":"string","nullable":true},"design_search_codes":{"type":"array","items":{"type":"string"}}},"required":["serial_number","registration_number","transaction_date","filing_date","registration_date","status_code","status_date","word_mark","mark_drawing_code","attorney_name","renewal_date","published_for_opposition_date","owner_name","owner_address","owner_city","owner_state","owner_country","legal_entity_type","goods_services","international_codes","us_codes","first_use_anywhere_date","first_use_in_commerce_date","design_search_codes"]}},"total_hits":{"type":"number"},"facets":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"page":{"type":"number"},"limit":{"type":"number"},"processing_time_ms":{"type":"number"}},"required":["query","hits","total_hits","page","limit","processing_time_ms"]}}}},"400":{"description":"Missing query or filter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Search failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/suggest":{"get":{"tags":["Search"],"summary":"Autocomplete suggestions","description":"Lightweight autocomplete returning word_mark, owner_name, and status","parameters":[{"schema":{"type":"string","description":"Search query","example":"app"},"required":true,"description":"Search query","name":"q","in":"query"},{"schema":{"type":"string","description":"Max suggestions (max 10)","example":"5"},"required":false,"description":"Max suggestions (max 10)","name":"limit","in":"query"}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"suggestions":{"type":"array","items":{"type":"object","properties":{"serial_number":{"type":"string"},"word_mark":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true},"status_code":{"type":"string","nullable":true}},"required":["serial_number","word_mark","owner_name","status_code"]}},"processing_time_ms":{"type":"number"}},"required":["query","suggestions","processing_time_ms"]}}}},"400":{"description":"Missing query","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Suggest failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/trademark/batch":{"post":{"tags":["Trademarks"],"summary":"Look up multiple trademarks by serial number","description":"Fetch up to 50 trademarks in one request. Returns found marks and any serial numbers that were not found. **Requires the Scale plan** — serial numbers are sequential, so batch lookups are the one endpoint that can enumerate the whole register.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serial_numbers":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50,"example":["90792662","88888888"]}},"required":["serial_numbers"]}}}},"responses":{"200":{"description":"Batch lookup results","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"array","items":{"type":"object","properties":{"serial_number":{"type":"string"},"registration_number":{"type":"string","nullable":true},"transaction_date":{"type":"string","nullable":true},"filing_date":{"type":"string","nullable":true},"filing_date_num":{"type":"number","nullable":true},"filing_year":{"type":"number","nullable":true},"registration_date":{"type":"string","nullable":true},"status_code":{"type":"string","nullable":true},"status_date":{"type":"string","nullable":true},"word_mark":{"type":"string","nullable":true},"mark_drawing_code":{"type":"string","nullable":true},"attorney_name":{"type":"string","nullable":true},"renewal_date":{"type":"string","nullable":true},"published_for_opposition_date":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true},"owner_address":{"type":"string","nullable":true},"owner_city":{"type":"string","nullable":true},"owner_state":{"type":"string","nullable":true},"owner_country":{"type":"string","nullable":true},"legal_entity_type":{"type":"string","nullable":true},"goods_services":{"type":"string","nullable":true},"international_codes":{"type":"array","items":{"type":"string"}},"us_codes":{"type":"array","items":{"type":"string"}},"first_use_anywhere_date":{"type":"string","nullable":true},"first_use_in_commerce_date":{"type":"string","nullable":true},"design_search_codes":{"type":"array","items":{"type":"string"}}},"required":["serial_number","registration_number","transaction_date","filing_date","registration_date","status_code","status_date","word_mark","mark_drawing_code","attorney_name","renewal_date","published_for_opposition_date","owner_name","owner_address","owner_city","owner_state","owner_country","legal_entity_type","goods_services","international_codes","us_codes","first_use_anywhere_date","first_use_in_commerce_date","design_search_codes"]}},"not_found":{"type":"array","items":{"type":"string"}},"count":{"type":"number"}},"required":["found","not_found","count"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Plan does not include batch lookups","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Lookup failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/trademark/{serialNumber}/timeline":{"get":{"tags":["Trademarks"],"summary":"Prosecution timeline for a trademark","description":"Normalizes the mark's date fields into an ordered list of prosecution events.","parameters":[{"schema":{"type":"string","description":"USPTO serial number","example":"90792662"},"required":true,"description":"USPTO serial number","name":"serialNumber","in":"path"}],"responses":{"200":{"description":"Ordered timeline","content":{"application/json":{"schema":{"type":"object","properties":{"serial_number":{"type":"string"},"word_mark":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"}},"required":["date","label","type"]}}},"required":["serial_number","word_mark","events"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Lookup failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/trademark/{serialNumber}":{"get":{"tags":["Trademarks"],"summary":"Get trademark by serial number","parameters":[{"schema":{"type":"string","description":"USPTO serial number","example":"90792662"},"required":true,"description":"USPTO serial number","name":"serialNumber","in":"path"}],"responses":{"200":{"description":"Trademark document","content":{"application/json":{"schema":{"type":"object","properties":{"serial_number":{"type":"string"},"registration_number":{"type":"string","nullable":true},"transaction_date":{"type":"string","nullable":true},"filing_date":{"type":"string","nullable":true},"filing_date_num":{"type":"number","nullable":true},"filing_year":{"type":"number","nullable":true},"registration_date":{"type":"string","nullable":true},"status_code":{"type":"string","nullable":true},"status_date":{"type":"string","nullable":true},"word_mark":{"type":"string","nullable":true},"mark_drawing_code":{"type":"string","nullable":true},"attorney_name":{"type":"string","nullable":true},"renewal_date":{"type":"string","nullable":true},"published_for_opposition_date":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true},"owner_address":{"type":"string","nullable":true},"owner_city":{"type":"string","nullable":true},"owner_state":{"type":"string","nullable":true},"owner_country":{"type":"string","nullable":true},"legal_entity_type":{"type":"string","nullable":true},"goods_services":{"type":"string","nullable":true},"international_codes":{"type":"array","items":{"type":"string"}},"us_codes":{"type":"array","items":{"type":"string"}},"first_use_anywhere_date":{"type":"string","nullable":true},"first_use_in_commerce_date":{"type":"string","nullable":true},"design_search_codes":{"type":"array","items":{"type":"string"}}},"required":["serial_number","registration_number","transaction_date","filing_date","registration_date","status_code","status_date","word_mark","mark_drawing_code","attorney_name","renewal_date","published_for_opposition_date","owner_name","owner_address","owner_city","owner_state","owner_country","legal_entity_type","goods_services","international_codes","us_codes","first_use_anywhere_date","first_use_in_commerce_date","design_search_codes"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Lookup failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/owner":{"get":{"tags":["Search"],"summary":"All trademarks for an owner","description":"Search marks by owner name, with a class and status breakdown of the portfolio.","parameters":[{"schema":{"type":"string","description":"Owner name","example":"Nike, Inc."},"required":true,"description":"Owner name","name":"name","in":"query"},{"schema":{"type":"string","example":"1"},"required":false,"name":"page","in":"query"},{"schema":{"type":"string","example":"20"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Owner portfolio","content":{"application/json":{"schema":{"type":"object","properties":{"owner":{"type":"string"},"total_hits":{"type":"number"},"hits":{"type":"array","items":{"type":"object","properties":{"serial_number":{"type":"string"},"registration_number":{"type":"string","nullable":true},"transaction_date":{"type":"string","nullable":true},"filing_date":{"type":"string","nullable":true},"filing_date_num":{"type":"number","nullable":true},"filing_year":{"type":"number","nullable":true},"registration_date":{"type":"string","nullable":true},"status_code":{"type":"string","nullable":true},"status_date":{"type":"string","nullable":true},"word_mark":{"type":"string","nullable":true},"mark_drawing_code":{"type":"string","nullable":true},"attorney_name":{"type":"string","nullable":true},"renewal_date":{"type":"string","nullable":true},"published_for_opposition_date":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true},"owner_address":{"type":"string","nullable":true},"owner_city":{"type":"string","nullable":true},"owner_state":{"type":"string","nullable":true},"owner_country":{"type":"string","nullable":true},"legal_entity_type":{"type":"string","nullable":true},"goods_services":{"type":"string","nullable":true},"international_codes":{"type":"array","items":{"type":"string"}},"us_codes":{"type":"array","items":{"type":"string"}},"first_use_anywhere_date":{"type":"string","nullable":true},"first_use_in_commerce_date":{"type":"string","nullable":true},"design_search_codes":{"type":"array","items":{"type":"string"}}},"required":["serial_number","registration_number","transaction_date","filing_date","registration_date","status_code","status_date","word_mark","mark_drawing_code","attorney_name","renewal_date","published_for_opposition_date","owner_name","owner_address","owner_city","owner_state","owner_country","legal_entity_type","goods_services","international_codes","us_codes","first_use_anywhere_date","first_use_in_commerce_date","design_search_codes"]}},"by_class":{"type":"object","additionalProperties":{"type":"number"}},"by_status":{"type":"object","additionalProperties":{"type":"number"}},"page":{"type":"number"},"limit":{"type":"number"}},"required":["owner","total_hits","hits","by_class","by_status","page","limit"]}}}},"400":{"description":"Missing name","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Lookup failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/clearance":{"get":{"tags":["Search"],"summary":"Trademark clearance / similarity check","description":"Find existing marks similar to a proposed mark, ranked by similarity. Optionally scope to an international class. A first-pass signal, not legal advice.","parameters":[{"schema":{"type":"string","description":"Proposed mark","example":"nyke"},"required":true,"description":"Proposed mark","name":"mark","in":"query"},{"schema":{"type":"string","description":"International class to scope to","example":"25"},"required":false,"description":"International class to scope to","name":"class","in":"query"},{"schema":{"type":"string","example":"20"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Ranked similar marks","content":{"application/json":{"schema":{"type":"object","properties":{"mark":{"type":"string"},"class":{"type":"string","nullable":true},"highest_risk":{"type":"string"},"matches":{"type":"array","items":{"type":"object","properties":{"serial_number":{"type":"string"},"word_mark":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true},"status_code":{"type":"string","nullable":true},"international_codes":{"type":"array","items":{"type":"string"}},"similarity":{"type":"number"},"risk":{"type":"string"}},"required":["serial_number","word_mark","owner_name","status_code","international_codes","similarity","risk"]}}},"required":["mark","class","highest_risk","matches"]}}}},"400":{"description":"Missing mark","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Clearance failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/aggregate":{"get":{"tags":["System"],"summary":"Aggregate counts across the corpus","description":"Distribution counts by class, status, country, drawing type, or filing year.","parameters":[{"schema":{"type":"string","enum":["class","status","country","drawing","year"],"example":"class"},"required":true,"name":"by","in":"query"}],"responses":{"200":{"description":"Aggregation","content":{"application/json":{"schema":{"type":"object","properties":{"by":{"type":"string"},"buckets":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"count":{"type":"number"}},"required":["key","count"]}}},"required":["by","buckets"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Aggregate failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/classes":{"get":{"tags":["System"],"summary":"Nice classification reference","description":"The 45 international (Nice) classes of goods and services with short descriptions.","responses":{"200":{"description":"Class reference","content":{"application/json":{"schema":{"type":"object","properties":{"classes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"}},"required":["code","title"]}}},"required":["classes"]}}}}}}}}}