{"openapi":"3.1.0","info":{"title":"Trademark Search API","description":"Search 13M+ USPTO trademark records by mark name, owner name, or combined criteria.\n\n**Home page**: https://tmsearchapi.com\n\n**Free tier**: 20 calls per day (no API key needed — tracked by IP).\n\n**Paid tier**: Generate an API key with `POST /api/keys`, then pay $20 in USDC/USDT/DAI on Base Mainnet to unlock 1,000 calls valid for 30 days. Submit payment proof via the `X-Payment` header.","version":"1.0.0"},"paths":{"/ping":{"get":{"summary":"Ping","operationId":"ping_ping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ping Ping Get"}}}}}}},"/api/keys":{"post":{"summary":"Create Api Key","description":"Generate a new API key (prefixed with `tm_`).\n\nThe key starts with 0 credits. Top up by making a search request with\nthe key and a valid `X-Payment` header, or see `GET /api/usage` for\npayment instructions.","operationId":"create_api_key_api_keys_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}}}}},"/api/keys/invoice/challenge":{"post":{"summary":"Create Invoice Challenge","description":"Issue a one-time challenge nonce that the caller must sign with their\npayer wallet (EIP-191 personal_sign) to prove wallet ownership before\ncreating a payment invoice.\n\n**Step 1 of 2 in the invoice flow.**\n\nReturns a `challenge_id` and the exact `message_to_sign`.  Sign the\nmessage with the wallet you will pay from (e.g. `personal_sign` in\nMetaMask / ethers.js / wagmi), then call `POST /api/keys/invoice` with\nthe `challenge_id`, your wallet address, and the hex signature.\n\nThe challenge expires in **15 minutes** and can only be used once.","operationId":"create_invoice_challenge_api_keys_invoice_challenge_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/keys/invoice":{"post":{"summary":"Create Invoice","description":"Create a payment invoice binding this API key to a specific payer wallet.\n\n**Step 2 of 2 in the invoice flow.** First obtain a challenge from\n`POST /api/keys/invoice/challenge`, sign it with your payer wallet, then\ncall this endpoint.\n\n**Required request body** (JSON):\n```json\n{\n  \"payer\":        \"0x<40 hex chars>\",\n  \"challenge_id\": \"<UUID from /api/keys/invoice/challenge>\",\n  \"signature\":    \"0x<EIP-191 personal_sign hex signature>\"\n}\n```\n\nReturns an `invoice_id` (valid 24 hours) that must be included as\n`invoiceId` in the `X-Payment` header when redeeming a payment.\n\nThe EIP-191 signature proves you control the declared payer wallet,\npreventing an attacker from creating an invoice with someone else's\nwallet address and front-running their on-chain payment.","operationId":"create_invoice_api_keys_invoice_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/keys/verify":{"get":{"summary":"Verify Key","description":"Check whether an API key is valid and return its current credit balance and expiry date.\n\nDoes **not** consume any credits.\nReturns 200 with `valid: true` if the key exists, `valid: false` if not.","operationId":"verify_key_api_keys_verify_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/usage":{"get":{"summary":"Get Usage","description":"Check remaining credits and payment instructions for an API key.\n\nPass your key in the `X-API-Key` header.","operationId":"get_usage_api_usage_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/search/mark":{"get":{"summary":"Search By Mark","description":"Search trademarks by mark (trademark name).\n\n- **q**: Search term (supports partial matching)\n- **limit**: Max results (default 100, max 1000)\n\nRequires free-tier IP quota (20/day) or a paid API key (`X-API-Key` header).","operationId":"search_by_mark_search_mark_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search term for trademark mark","title":"Q"},"description":"Search term for trademark mark"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of results to return","default":100,"title":"Limit"},"description":"Maximum number of results to return"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Payment"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/search/owner":{"get":{"summary":"Search By Owner","description":"Search trademarks by owner name.\n\n- **q**: Search term (supports partial matching)\n- **limit**: Max results (default 100, max 1000)\n\nRequires free-tier IP quota (20/day) or a paid API key (`X-API-Key` header).","operationId":"search_by_owner_search_owner_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search term for owner name","title":"Q"},"description":"Search term for owner name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of results to return","default":100,"title":"Limit"},"description":"Maximum number of results to return"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Payment"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/search/combined":{"get":{"summary":"Search Combined","description":"Search trademarks by both mark and owner name (AND logic).\n\n- **mark**: Trademark mark search term (optional)\n- **owner**: Owner name search term (optional)\n- **limit**: Max results (default 100, max 1000)\n\nAt least one parameter must be provided.\nRequires free-tier IP quota (20/day) or a paid API key (`X-API-Key` header).","operationId":"search_combined_search_combined_get","parameters":[{"name":"mark","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term for trademark mark","title":"Mark"},"description":"Search term for trademark mark"},{"name":"owner","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search term for owner name","title":"Owner"},"description":"Search term for owner name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of results to return","default":100,"title":"Limit"},"description":"Maximum number of results to return"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Payment"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health Check","description":"Liveness check endpoint.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Check Health Get"}}}}}}}},"components":{"schemas":{"ApiKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"credits":{"type":"integer","title":"Credits"},"message":{"type":"string","title":"Message"}},"type":"object","required":["api_key","credits","message"],"title":"ApiKeyResponse","description":"Response for POST /api/keys"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/TrademarkRecord"},"type":"array","title":"Results"},"total_count":{"type":"integer","title":"Total Count"},"query":{"type":"string","title":"Query"},"search_type":{"type":"string","title":"Search Type"}},"type":"object","required":["results","total_count","query","search_type"],"title":"SearchResponse","description":"Response model for search endpoints"},"TrademarkRecord":{"properties":{"serial_number":{"type":"string","title":"Serial Number"},"registration_number":{"type":"string","title":"Registration Number"},"status_code":{"type":"string","title":"Status Code"},"status_date":{"type":"string","title":"Status Date"},"mark":{"type":"string","title":"Mark"},"classes":{"type":"string","title":"Classes"},"descriptions":{"type":"string","title":"Descriptions"},"owner_name":{"type":"string","title":"Owner Name"},"owner_country":{"type":"string","title":"Owner Country"}},"type":"object","required":["serial_number","registration_number","status_code","status_date","mark","classes","descriptions","owner_name","owner_country"],"title":"TrademarkRecord","description":"Pydantic model for trademark record response"},"UsageResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"reset_date":{"type":"string","title":"Reset Date"},"plan":{"type":"string","title":"Plan"},"payment_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Address"},"payment_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Instructions"}},"type":"object","required":["api_key","credits_remaining","reset_date","plan"],"title":"UsageResponse","description":"Response for GET /api/usage"},"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"}}}}