{"openapi":"3.1.0","info":{"title":"Markbase","description":"USPTO Trademark Search API — search, filter, and retrieve data from 14M+ U.S. trademarks.","version":"1.15.16"},"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"},"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","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"}],"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},"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/{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},"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"]}}}}}}}}}