{ "openapi": "3.1.0", "info": { "title": "Trademark Search Pro API", "version": "1.1.0", "description": "India's most complete Trademark Data API. Access 7.7M+ trademark records from IP India — word marks, proprietor & attorney details, oppositions, hearings, examination reports, cited marks, journals, logo (image) search, realtime IP-India lookups, PDF/Excel reports, and webhooks.\n\n## Base URL\n```\nhttps://api.trademarksearchpro.com/india\n```\n\n## Authentication\nMost endpoints require your API key in the **`X-API-Key`** header:\n```\nX-API-Key: tmsp_your_key_here\n```\nA legacy `Authorization: Api-Key tmsp_…` header is also accepted. Keys look like `tmsp_` followed by 32 characters and are created in the dashboard.\n\nDashboard/account endpoints under `/user/v1/` use a JWT **Bearer** token from `/user/v1/login/` instead.\n\n## Rate limits\nPer-second and per-minute limits apply per key (see your plan). Exceeding them returns `429`.", "contact": { "name": "TrademarkSearchPro Support", "email": "support@trademarksearchpro.com", "url": "https://trademarksearchpro.com" }, "license": { "name": "Proprietary", "url": "https://trademarksearchpro.com/terms" } }, "servers": [ { "url": "https://api.trademarksearchpro.com/india", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Auth", "description": "Signup and get your API key" }, { "name": "Trademark Search", "description": "Search and retrieve trademark data" }, { "name": "Proprietor & Attorney", "description": "Proprietor and attorney/agent details" }, { "name": "Oppositions", "description": "Opposition proceedings and documents" }, { "name": "Hearings", "description": "Hearing schedule and room links" }, { "name": "Documents & Reports", "description": "TM documents, examination reports, download links" }, { "name": "Logo Search", "description": "Search by logo text or image using CLIP AI + OCR" }, { "name": "Bulk Operations", "description": "Pro+ — batch search up to 100 application numbers per request" }, { "name": "Journals", "description": "Trademark journal metadata and downloads" }, { "name": "Reference Data", "description": "Well Known Marks, Prohibited Marks, WHO INN, Stamp Duty, TM Classes" }, { "name": "Webhooks", "description": "Real-time change notifications for monitored trademarks" }, { "name": "Realtime", "description": "Live IP-India lookups (add-on)" }, { "name": "Free / Public", "description": "Unauthenticated endpoints" }, { "name": "API Keys", "description": "Manage your API keys" } ], "paths": { "/user/v1/signup/": { "post": { "tags": [ "Auth" ], "summary": "Create account and get API key", "description": "Create a new API account. Returns a JWT token and your API key immediately. No credit card required for signup.", "operationId": "signup", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name", "last_name", "email", "password" ], "properties": { "first_name": { "type": "string", "example": "Rahul" }, "last_name": { "type": "string", "example": "Mehta" }, "organisation": { "type": "string", "example": "Mehta IP Associates" }, "email": { "type": "string", "format": "email", "example": "rahul@mehtaip.com" }, "phone": { "type": "string", "example": "+91 98765 43210" }, "password": { "type": "string", "minLength": 8, "example": "StrongPass@123" }, "plan": { "type": "string", "enum": [ "basic", "pro", "business" ], "default": "basic" } } } } } }, "responses": { "201": { "description": "Account created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "JWT token for dashboard access" }, "api_key": { "type": "string", "example": "tmsp_live_abc123..." }, "email": { "type": "string" }, "name": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/trademarks/": { "get": { "tags": [ "Trademark Search" ], "summary": "Search Trademarks", "description": "Search the 7.7M+ trademark database by word mark. Supports SMART search (fuzzy, phonetic, split-word patterns) and EXACT match.\n\n**SMART search** automatically generates multiple search patterns — prefix, suffix, split compound words, FULLTEXT — and merges results ranked by relevance score.\n\n**EXACT search** returns only exact word mark matches.", "operationId": "searchTrademarks", "parameters": [ { "name": "word_mark", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Word mark to search. E.g. `AMUL`, `RAM NIWAS`, `FROCKFIT`", "example": "AMUL" }, { "name": "match_type", "in": "query", "schema": { "type": "string", "enum": [ "SMART", "EXACT" ], "default": "SMART" }, "description": "`SMART` — intelligent multi-pattern search with relevance scoring. `EXACT` — exact word mark match only." }, { "name": "class_number", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 45 }, "description": "Filter by trademark class (1–45)" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by status. E.g. `Registered`, `Objected`, `Under Examination`" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "match_type": { "type": "string" }, "count": { "type": "integer" }, "response_ms": { "type": "integer" }, "from_cache": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TrademarkSummary" } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/v1/trademarks/{app_no}/": { "get": { "tags": [ "Trademark Search" ], "summary": "Trademark Full Detail", "description": "Returns complete trademark data for one application number — core data plus all linked tables enabled on your plan (status history, proprietor, attorney, oppositions, hearings, documents, exam reports).", "operationId": "trademarkDetail", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Full trademark detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrademarkDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/trademarks/{app_no}/status/": { "get": { "tags": [ "Trademark Search" ], "summary": "Status History", "description": "Full chronological status change history for a trademark. Requires `cat_status_history` on your plan.", "operationId": "statusHistory", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Status history", "content": { "application/json": { "schema": { "type": "object", "properties": { "application_number": { "type": "string" }, "count": { "type": "integer" }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "old_status": { "type": "string" }, "new_status": { "type": "string" }, "changed_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/trademarks/{app_no}/alerts/": { "get": { "tags": [ "Trademark Search" ], "summary": "Alert Changes", "description": "Alert change history for a trademark. Requires `cat_alert_changes` on your plan.", "operationId": "alertChanges", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Alert changes", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/trademarks/{app_no}/cited/": { "get": { "tags": [ "Trademark Search" ], "summary": "Cited Marks", "description": "Trademarks cited against this application in examination reports.", "operationId": "citedMarks", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Cited trademarks", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/trademarks/{app_no}/threats/": { "get": { "tags": [ "Trademark Search" ], "summary": "Trademark Threats / Similarity Analysis", "description": "Pre-computed similarity analysis — other trademarks that pose a risk to this one. Includes word similarity %, visual similarity %, soundex score, overall risk level (Low/Medium/High). Requires `cat_threats` add-on.", "operationId": "trademarkThreats", "parameters": [ { "$ref": "#/components/parameters/app_no" }, { "name": "risk_level", "in": "query", "schema": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "description": "Filter by risk level" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Threat analysis results", "content": { "application/json": { "schema": { "type": "object", "properties": { "application_number": { "type": "string" }, "count": { "type": "integer" }, "threats": { "type": "array", "items": { "type": "object", "properties": { "threat_application_number": { "type": "string" }, "threat_word_mark": { "type": "string" }, "word_similarity_percentage": { "type": "number" }, "visual_similarity_percentage": { "type": "number" }, "overall_similarity_score": { "type": "number" }, "risk_level": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "matching_criteria": { "type": "string", "enum": [ "exact", "word", "visual", "logo" ] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/trademarks/{app_no}/proprietor/": { "get": { "tags": [ "Proprietor & Attorney" ], "summary": "Proprietor Detail", "description": "Proprietor/owner details for a trademark. Requires `cat_proprietor` on your plan.", "operationId": "proprietorDetail", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Proprietor detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/trademarks/{app_no}/attorney/": { "get": { "tags": [ "Proprietor & Attorney" ], "summary": "Attorney / Agent Detail", "description": "Attorney or agent details for a trademark. Requires `cat_attorney` on your plan.", "operationId": "attorneyDetail", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Attorney detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/trademarks/{app_no}/oppositions/": { "get": { "tags": [ "Oppositions" ], "summary": "List Oppositions", "description": "All opposition proceedings filed against a trademark. Includes opponent details, opposition date, status and decision. Requires `cat_oppositions`.", "operationId": "listOppositions", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Opposition list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/trademarks/{app_no}/opp-docs/": { "get": { "tags": [ "Oppositions" ], "summary": "Opposition Documents", "description": "Documents filed in opposition proceedings. Returns pre-signed S3 URLs (valid 30 minutes). Requires `cat_opp_docs`.", "operationId": "oppositionDocs", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Opposition documents with pre-signed URLs", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/trademarks/{app_no}/hearings/": { "get": { "tags": [ "Hearings" ], "summary": "Hearing Details", "description": "Scheduled hearings for a trademark including date, type, virtual room link and time slot. Requires `cat_hearings`.", "operationId": "hearingDetails", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Hearing details", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/trademarks/{app_no}/documents/": { "get": { "tags": [ "Documents & Reports" ], "summary": "TM Documents", "description": "All documents associated with a trademark. Returns 30-minute pre-signed S3 URLs. Plan is checked at the moment of every request — if plan expires, access is denied immediately. Requires `cat_documents`.", "operationId": "tmDocuments", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "TM documents with 30-minute pre-signed URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": "string" }, "upload_date": { "type": "string" }, "presigned_url": { "type": "string", "description": "Expires in 30 minutes" }, "url_expires_in": { "type": "string", "example": "30 minutes" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanInactive" } } } }, "/v1/documents/{doc_id}/url/": { "get": { "tags": [ "Documents & Reports" ], "summary": "Document Download URL", "description": "Generate a fresh 30-minute pre-signed S3 download URL for a specific document. Plan is checked at request time — if plan is inactive, returns error: 'Session expired, please reopen document'.", "operationId": "documentUrl", "parameters": [ { "name": "doc_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Document ID from the documents endpoint" } ], "responses": { "200": { "description": "Pre-signed download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "presigned_url": { "type": "string" }, "expires_in": { "type": "string", "example": "30 minutes" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanInactive" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/trademarks/{app_no}/exam-report/": { "get": { "tags": [ "Documents & Reports" ], "summary": "Examination Report", "description": "Examination report data including objection reasons and cited application numbers. Requires `cat_exam_reports`.", "operationId": "examReport", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Examination reports", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/logo-search/text/": { "post": { "tags": [ "Logo Search" ], "summary": "Logo Text Search (OCR)", "description": "Search for trademark logos containing specific text using OCR (Optical Character Recognition). Returns similar logo images as 30-minute pre-signed URLs.", "operationId": "logoTextSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query_text" ], "properties": { "query_text": { "type": "string", "example": "AMUL" }, "similarity_level": { "type": "array", "items": { "type": "string", "enum": [ "high", "medium", "low" ] }, "default": [ "low" ] }, "max_results": { "type": "integer", "default": 50, "maximum": 500 } } } } } }, "responses": { "200": { "description": "Matching logo images", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/LogoQuotaExceeded" } } } }, "/v1/logo-search/image/": { "post": { "tags": [ "Logo Search" ], "summary": "Logo Image Search (CLIP AI)", "description": "Upload a JPEG or PNG image to find visually similar trademark logos using CLIP AI similarity model. Returns results sorted by clip_similarity score.", "operationId": "logoImageSearch", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "uploaded_file" ], "properties": { "uploaded_file": { "type": "string", "format": "binary", "description": "JPEG or PNG, max 5MB" }, "similarity_level": { "type": "string", "enum": [ "high", "medium", "low" ], "default": "high" }, "img_cnt": { "type": "integer", "default": 50, "maximum": 100 } } } } } }, "responses": { "200": { "description": "Similar logo images with clip_similarity scores", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/LogoQuotaExceeded" } } } }, "/v1/logo-search/image-url/": { "post": { "tags": [ "Logo Search" ], "summary": "Logo Image URL Search (CLIP AI)", "description": "Find visually similar trademark logos by providing an image URL. No file upload required. Uses CLIP AI similarity.", "operationId": "logoImageUrlSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_url" ], "properties": { "image_url": { "type": "string", "format": "uri", "example": "https://example.com/logo.png" }, "similarity_level": { "type": "string", "enum": [ "high", "medium", "low" ], "default": "high" }, "img_cnt": { "type": "integer", "default": 50, "maximum": 100 } } } } } }, "responses": { "200": { "description": "Similar logo images", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/logo-search/bulk-text/": { "post": { "tags": [ "Logo Search" ], "summary": "Bulk Logo Text Search (Pro+)", "description": "Search up to 100 text queries in a single API call. Each query counts as 1 logo search credit. Requires Pro+ plan with bulk_logo_limit > 0.", "operationId": "bulkLogoTextSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "queries" ], "properties": { "queries": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "query_text" ], "properties": { "query_text": { "type": "string" }, "similarity_level": { "type": "array", "items": { "type": "string", "enum": [ "high", "medium", "low" ] } } } } }, "max_results_per_query": { "type": "integer", "default": 50, "maximum": 500 } } } } } }, "responses": { "200": { "description": "Results for each query", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/BulkNotOnPlan" } } } }, "/v1/logo-search/bulk-image/": { "post": { "tags": [ "Logo Search" ], "summary": "Bulk Logo Image Search (Pro+)", "description": "Upload up to 100 images to find similar logos for each. Each image = 1 logo search credit. Requires Pro+ plan.", "operationId": "bulkLogoImageSearch", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "uploaded_files" ], "properties": { "uploaded_files": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 100 }, "similarity_level": { "type": "string", "enum": [ "high", "medium", "low" ], "default": "high" }, "img_cnt": { "type": "integer", "default": 50, "maximum": 100 } } } } } }, "responses": { "200": { "description": "Results per image", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/BulkNotOnPlan" } } } }, "/v1/logo-search/bulk-image-url/": { "post": { "tags": [ "Logo Search" ], "summary": "Bulk Logo URL Search (Pro+)", "description": "Provide up to 100 image URLs to find similar logos for each. Each URL = 1 logo search credit. Requires Pro+ plan.", "operationId": "bulkLogoImageUrlSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_urls" ], "properties": { "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 100 }, "similarity_level": { "type": "string", "enum": [ "high", "medium", "low" ], "default": "high" }, "img_cnt": { "type": "integer", "default": 50, "maximum": 100 } } } } } }, "responses": { "200": { "description": "Results per URL", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/BulkNotOnPlan" } } } }, "/v1/trademarks/bulk/": { "post": { "tags": [ "Bulk Operations" ], "summary": "Bulk Trademark Search (Pro+)", "description": "Search up to 100 **application numbers** (comma-separated or array) in one request. Returns core trademark data for each. Requires Pro+ plan with `bulk_search_limit > 0`.\n\n**Important:** This endpoint accepts application numbers only — not word marks.", "operationId": "bulkTrademarkSearch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "application_numbers" ], "properties": { "application_numbers": { "oneOf": [ { "type": "string", "description": "Comma-separated application numbers", "example": "1234567,2345678,3456789" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100, "example": [ "1234567", "2345678" ] } ] } } } } } }, "responses": { "200": { "description": "Trademark data for each application number", "content": { "application/json": { "schema": { "type": "object", "properties": { "requested": { "type": "integer" }, "found": { "type": "integer" }, "not_found": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TrademarkSummary" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/BulkNotOnPlan" } } } }, "/v1/journals/": { "get": { "tags": [ "Journals" ], "summary": "Journal List", "description": "List trademark journals with publication dates. Requires `cat_journal`.", "operationId": "journalList", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Journal list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/journals/{journal_id}/": { "get": { "tags": [ "Journals" ], "summary": "Journal Detail", "description": "Journal metadata for a specific journal ID.", "operationId": "journalDetail", "parameters": [ { "name": "journal_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Journal detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/journals/{journal_id}/download/": { "get": { "tags": [ "Journals" ], "summary": "Journal Download", "description": "Generate a 30-minute pre-signed S3 URL to download the journal PDF.", "operationId": "journalDownload", "parameters": [ { "name": "journal_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Pre-signed download URL", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/PlanInactive" } } } }, "/v1/reference/well-known-marks/": { "get": { "tags": [ "Reference Data" ], "summary": "Well Known Marks", "description": "List of well-known marks recognised by IP India. Requires `cat_well_known` add-on.", "operationId": "wellKnownMarks", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Well known marks", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/reference/prohibited-marks/": { "get": { "tags": [ "Reference Data" ], "summary": "Prohibited Marks", "description": "Marks prohibited from registration under the Trade Marks Act. Requires `cat_prohibited` add-on.", "operationId": "prohibitedMarks", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Prohibited marks", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/reference/non-proprietary-names/": { "get": { "tags": [ "Reference Data" ], "summary": "Non-Proprietary Names (WHO INN)", "description": "WHO International Non-proprietary Names for pharmaceutical substances. Requires `cat_inn_names` add-on.", "operationId": "nonProprietaryNames", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "WHO INN names", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/reference/stamp-duty/": { "get": { "tags": [ "Reference Data" ], "summary": "Stamp Duty by State", "description": "Stamp duty rates for trademark affidavits across all Indian states and UTs. Requires `cat_stamp_duty` add-on.", "operationId": "stampDuty", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Filter by state name" } ], "responses": { "200": { "description": "Stamp duty data for all states", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/tm-classes/": { "get": { "tags": [ "Reference Data" ], "summary": "List All 45 TM Classes", "description": "List all 45 trademark classes with item counts. Requires `cat_tm_class` add-on.", "operationId": "tmClassesList", "responses": { "200": { "description": "All 45 classes", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "example": 45 }, "classes": { "type": "array", "items": { "type": "object", "properties": { "class": { "type": "integer" }, "item_count": { "type": "integer" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/tm-classes/{class_number}/": { "get": { "tags": [ "Reference Data" ], "summary": "TM Class Items", "description": "Get all goods and services in a specific trademark class (1–45). Returns Nice Classification (item_a) and Indian TM Classification (item_b).", "operationId": "tmClassDetail", "parameters": [ { "name": "class_number", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 45 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "nice", "tm", "both" ], "default": "both" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Class items", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/v1/tm-classes/search/": { "get": { "tags": [ "Reference Data" ], "summary": "TM Class Search", "description": "Search goods and services across all 45 classes using FULLTEXT keyword search. Find which class covers your product or service.", "operationId": "tmClassSearch", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "software" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "nice", "tm", "both" ], "default": "both" } }, { "name": "class", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 45 }, "description": "Restrict search to one class" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Matching class items", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/user/v1/webhooks/": { "post": { "tags": [ "Webhooks" ], "summary": "Register Webhook", "description": "Register a webhook endpoint to receive real-time change notifications for monitored trademarks.\n\nEvents available:\n- `trademark.status_changed`\n- `trademark.alert_changed`\n- `trademark.opposition_filed`\n- `trademark.hearing_scheduled`\n- `trademark.document_added`\n- `trademark.proprietor_changed`\n- `trademark.exam_report_added`\n- `*` — subscribe to all events", "operationId": "registerWebhook", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "monitored_applications" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Must be HTTPS", "example": "https://your-server.com/webhook" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "trademark.status_changed", "trademark.alert_changed", "trademark.expiry_changed", "trademark.journal_published", "trademark.opposition_filed", "trademark.opposition_updated", "trademark.opposition_document_added", "trademark.hearing_scheduled", "trademark.hearing_updated", "trademark.exam_report_added", "trademark.document_added", "trademark.proprietor_changed", "trademark.attorney_changed", "trademark.cited_mark_added", "trademark.renewal_due", "*" ] }, "description": "Subscribe to specific events, or [\"*\"] for all. Unknown events are rejected with 400." }, "monitored_applications": { "type": "array", "items": { "type": "string" }, "description": "Application numbers to monitor", "example": [ "1234567", "2345678" ] }, "secret": { "type": "string", "description": "Used to verify HMAC-SHA256 signature on deliveries" } } } } } }, "responses": { "201": { "description": "Webhook registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/WebhooksNotOnPlan" } } } }, "/user/v1/webhooks/list/": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "List all registered webhook endpoints with status and delivery stats.", "operationId": "listWebhooks", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/user/v1/webhooks/{webhook_id}/": { "put": { "tags": [ "Webhooks" ], "summary": "Update Webhook", "description": "Update URL, events, monitored applications, or active status of an existing webhook.", "operationId": "updateWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "trademark.status_changed", "trademark.alert_changed", "trademark.expiry_changed", "trademark.journal_published", "trademark.opposition_filed", "trademark.opposition_updated", "trademark.opposition_document_added", "trademark.hearing_scheduled", "trademark.hearing_updated", "trademark.exam_report_added", "trademark.document_added", "trademark.proprietor_changed", "trademark.attorney_changed", "trademark.cited_mark_added", "trademark.renewal_due", "*" ] }, "description": "Subscribe to specific events, or [\"*\"] for all. Unknown events are rejected with 400." }, "monitored_applications": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Webhook", "description": "Permanently delete a webhook registration.", "operationId": "deleteWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/user/v1/webhooks/{webhook_id}/test/": { "post": { "tags": [ "Webhooks" ], "summary": "Test Webhook", "description": "Send a test ping to verify your endpoint is reachable and responding correctly.", "operationId": "testWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "response_status": { "type": "integer" }, "response_time_ms": { "type": "integer" }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/user/v1/webhooks/{webhook_id}/logs/": { "get": { "tags": [ "Webhooks" ], "summary": "Webhook Delivery Logs", "description": "History of all delivery attempts for a webhook — event type, response status, timing, retry count.", "operationId": "webhookLogs", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Delivery logs", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v3/trademarks/": { "get": { "tags": [ "Trademark Search" ], "summary": "TM Search V3 — Advanced Multi-Search & Export", "description": "Advanced trademark search with image search support, multi-field filtering, bulk exports (Excel/PDF), and aggregated result buckets. Includes phonetic and visual similarity options.", "operationId": "searchV3", "parameters": [ { "name": "word_mark", "in": "query", "schema": { "type": "string" }, "description": "Word mark to search" }, { "name": "match_type", "in": "query", "schema": { "type": "string", "enum": [ "SMART", "EXACT" ], "default": "SMART" } }, { "name": "class_number", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 45 } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "export", "in": "query", "schema": { "type": "string", "enum": [ "json", "excel", "pdf" ] }, "description": "Export format — omit for JSON response" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Search results or file download", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/v1/trademarks/bulk/detail/": { "post": { "tags": [ "Bulk Operations" ], "summary": "Bulk Detail Retrieval (Pro+)", "description": "Get full trademark details (all linked tables based on your plan) for up to 100 application numbers in one request. Requires Pro+ plan.", "operationId": "bulkDetail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "application_numbers" ], "properties": { "application_numbers": { "oneOf": [ { "type": "string", "description": "Comma-separated", "example": "1234567,2345678" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 } ] } } } } } }, "responses": { "200": { "description": "Full detail for each application number", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/BulkNotOnPlan" } } } }, "/v1/trademarks/bulk/documents/": { "post": { "tags": [ "Bulk Operations" ], "summary": "Bulk Document View (Pro+)", "description": "Get document lists with 30-minute pre-signed S3 URLs for up to 100 application numbers. Requires Pro+ plan with `cat_documents` enabled.", "operationId": "bulkDocumentView", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "application_numbers" ], "properties": { "application_numbers": { "oneOf": [ { "type": "string", "example": "1234567,2345678" }, { "type": "array", "items": { "type": "string" }, "maxItems": 100 } ] } } } } } }, "responses": { "200": { "description": "Documents with pre-signed URLs for each application number", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/BulkNotOnPlan" } } } }, "/v1/trademarks/{app_no}/phonetic/": { "get": { "tags": [ "Trademark Search" ], "summary": "TM Phonetic Details (Add-on)", "description": "Phonetic data for a trademark — Soundex code, Metaphone code, cleaned mark text. Used for fuzzy/phonetic conflict search. Requires `cat_phonetic` add-on (₹1,200/mo).", "operationId": "phoneticDetails", "parameters": [ { "$ref": "#/components/parameters/app_no" } ], "responses": { "200": { "description": "Phonetic data", "content": { "application/json": { "schema": { "type": "object", "properties": { "application_number": { "type": "string" }, "word_mark": { "type": "string" }, "soundex_code": { "type": "string" }, "metaphone_code": { "type": "string" }, "cleaned_mark": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CategoryBlocked" } } } }, "/user/v1/verify-email/": { "post": { "tags": [ "Auth" ], "summary": "Verify email", "operationId": "postUserV1VerifyEmail", "description": "Confirm a signup email with the emailed token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Verify email", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/login/": { "post": { "tags": [ "Auth" ], "summary": "Log in", "operationId": "postUserV1Login", "description": "Exchange email + password for a JWT access/refresh pair.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Log in", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/refresh/": { "post": { "tags": [ "Auth" ], "summary": "Refresh token", "operationId": "postUserV1Refresh", "description": "Exchange a refresh token for a new access token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ] } } } }, "responses": { "200": { "description": "Refresh token", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/logout/": { "post": { "tags": [ "Auth" ], "summary": "Log out", "operationId": "postUserV1Logout", "description": "Revoke the current refresh token.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Log out", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/forgot-password/": { "post": { "tags": [ "Auth" ], "summary": "Request password reset", "operationId": "postUserV1ForgotPassword", "description": "Email a password-reset link.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Request password reset", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/reset-password/": { "post": { "tags": [ "Auth" ], "summary": "Reset password", "operationId": "postUserV1ResetPassword", "description": "Set a new password using the emailed token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "new_password": { "type": "string" } }, "required": [ "token", "new_password" ] } } } }, "responses": { "200": { "description": "Reset password", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/me/": { "get": { "tags": [ "Auth" ], "summary": "Current account", "operationId": "getUserV1Me", "description": "Profile, plan, and quota snapshot for the authenticated user.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current account", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/change-password/": { "post": { "tags": [ "Auth" ], "summary": "Change password", "operationId": "postUserV1ChangePassword", "description": "Change password for the logged-in user.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } }, "required": [ "current_password", "new_password" ] } } } }, "responses": { "200": { "description": "Change password", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/usage/": { "get": { "tags": [ "Auth" ], "summary": "Usage summary", "operationId": "getUserV1Usage", "description": "Current-period usage across all quota categories.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/api-keys/": { "get": { "tags": [ "API Keys" ], "summary": "List API keys", "operationId": "getUserV1ApiKeys", "description": "List your API keys (hashes are never returned).", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List API keys", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "API Keys" ], "summary": "Create API key", "operationId": "postUserV1ApiKeys", "description": "Create a new API key. The full key is shown once on creation.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } } } } } }, "responses": { "200": { "description": "Create API key", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user/v1/api-keys/{key_id}/": { "delete": { "tags": [ "API Keys" ], "summary": "Revoke API key", "operationId": "deleteUserV1ApiKeysKeyId", "description": "Permanently revoke an API key.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "API key id" } ], "responses": { "200": { "description": "Revoke API key", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/proprietor/": { "get": { "tags": [ "Proprietor & Attorney" ], "summary": "Search by proprietor", "operationId": "getV1Proprietor", "description": "Find trademarks by proprietor (owner) name.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Name to search (partial allowed)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Max results (default 50, max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Search by proprietor", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/attorney/": { "get": { "tags": [ "Proprietor & Attorney" ], "summary": "Search by attorney", "operationId": "getV1Attorney", "description": "Find trademarks by attorney / agent name.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Name to search (partial allowed)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Max results (default 50, max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Search by attorney", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oppositions/{opp_no}/": { "get": { "tags": [ "Oppositions" ], "summary": "Opposition by number", "operationId": "getV1OppositionsOppNo", "description": "Fetch an opposition by its opposition number (not the application number).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "opp_no", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opposition number" } ], "responses": { "200": { "description": "Opposition by number", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oppositions/{opp_no}/documents/": { "get": { "tags": [ "Oppositions" ], "summary": "Opposition documents by number", "operationId": "getV1OppositionsOppNoDocuments", "description": "List documents filed in an opposition, by opposition number.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "opp_no", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opposition number" } ], "responses": { "200": { "description": "Opposition documents by number", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/journals/by-number/{journal_number}/download/": { "get": { "tags": [ "Journals" ], "summary": "Download journal by number", "operationId": "getV1JournalsByNumberJournalNumberDownload", "description": "Download a journal issue PDF by its printed journal number.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "journal_number", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Journal number (as printed)" } ], "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/journals/{journal_id}/download/{part_idx}/": { "get": { "tags": [ "Journals" ], "summary": "Download journal part", "operationId": "getV1JournalsJournalIdDownloadPartIdx", "description": "Download one part of a multi-part journal file.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "journal_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Internal journal id" }, { "name": "part_idx", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Multi-part file index" } ], "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/journals/{journal_number}/trademarks/": { "get": { "tags": [ "Journals" ], "summary": "Trademarks in a journal", "operationId": "getV1JournalsJournalNumberTrademarks", "description": "List trademarks published in a given journal number.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "journal_number", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Journal number (as printed)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Max results (default 50, max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Trademarks in a journal", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{token}/": { "get": { "tags": [ "Documents & Reports" ], "summary": "Download a file", "operationId": "getV1FilesToken", "description": "Fetch a document/report using an opaque, capability-scoped download token returned by other endpoints.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opaque download token" } ], "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/realtime/trademark/{app_no}/": { "get": { "tags": [ "Realtime" ], "summary": "Realtime trademark", "operationId": "getV1RealtimeTrademarkAppNo", "description": "Live fetch of a single trademark direct from IP-India (realtime add-on).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "app_no", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Application number" } ], "responses": { "200": { "description": "Realtime trademark", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/realtime/trademark/{app_no}/status/": { "get": { "tags": [ "Realtime" ], "summary": "Realtime status", "operationId": "getV1RealtimeTrademarkAppNoStatus", "description": "Live status of a single trademark from IP-India.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "app_no", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Application number" } ], "responses": { "200": { "description": "Realtime status", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/realtime/trademark/bulk/": { "get": { "tags": [ "Realtime" ], "summary": "Realtime bulk", "operationId": "getV1RealtimeTrademarkBulk", "description": "Live fetch of multiple trademarks from IP-India.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "application_numbers", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Comma-separated application numbers" } ], "responses": { "200": { "description": "Realtime bulk", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/realtime/trademark/bulk/status/": { "get": { "tags": [ "Realtime" ], "summary": "Realtime bulk status", "operationId": "getV1RealtimeTrademarkBulkStatus", "description": "Status of a realtime bulk job.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "query", "schema": { "type": "string" }, "description": "Bulk job id" } ], "responses": { "200": { "description": "Realtime bulk status", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports/search-results/": { "post": { "tags": [ "Documents & Reports" ], "summary": "Search-results report", "operationId": "postV1ReportsSearchResults", "description": "Generate a PDF/Excel report from a set of search results. Charges report quota.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "word_mark": { "type": "string" }, "format": { "type": "string", "enum": [ "pdf", "excel" ] } } } } } }, "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports/trademark-detail/": { "post": { "tags": [ "Documents & Reports" ], "summary": "Trademark detail report", "operationId": "postV1ReportsTrademarkDetail", "description": "Generate a detailed PDF report for one trademark. Charges report quota.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "application_number": { "type": "string" }, "format": { "type": "string", "enum": [ "pdf", "excel" ] } }, "required": [ "application_number" ] } } } }, "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/trademarks/export/excel/": { "get": { "tags": [ "Documents & Reports" ], "summary": "Export search results (Excel)", "operationId": "getV1TrademarksExportExcel", "description": "GET-style Excel export of a search. Charges excel_reports quota.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "word_mark", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Word mark to export" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Max results (default 50, max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/trademarks/export/pdf/": { "get": { "tags": [ "Documents & Reports" ], "summary": "Export search results (PDF)", "operationId": "getV1TrademarksExportPdf", "description": "GET-style PDF export of a search. Charges pdf_reports quota.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "word_mark", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Word mark to export" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Max results (default 50, max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v3/documents/bulk/download/": { "post": { "tags": [ "Documents & Reports" ], "summary": "Bulk document ZIP", "operationId": "postV3DocumentsBulkDownload", "description": "Download many trademark documents as a single ZIP.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "application_numbers": { "type": "array", "items": { "type": "string" } } }, "required": [ "application_numbers" ] } } } }, "responses": { "200": { "description": "Binary file (PDF/XLSX/ZIP) or a JSON download link", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/v1/trademarks/search/": { "get": { "tags": [ "Free / Public" ], "summary": "Free trademark search", "operationId": "getPublicV1TrademarksSearch", "description": "Unauthenticated word-mark search (rate-limited per IP). Drives the free search page.", "security": [], "parameters": [ { "name": "word_mark", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Word mark" }, { "name": "class_number", "in": "query", "schema": { "type": "integer" }, "description": "TM class 1–45" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Max results (default 50, max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Free trademark search", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public/v1/landing-config/": { "get": { "tags": [ "Free / Public" ], "summary": "Landing config", "operationId": "getPublicV1LandingConfig", "description": "Public landing-page stats/config.", "security": [], "responses": { "200": { "description": "Landing config", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks (API-key)", "operationId": "getV1Webhooks", "description": "List webhook subscriptions (X-API-Key alias of /user/v1/webhooks/).", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List webhooks (API-key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook (API-key)", "operationId": "postV1Webhooks", "description": "Create a webhook subscription (X-API-Key alias).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "trademark.status_changed", "trademark.alert_changed", "trademark.expiry_changed", "trademark.journal_published", "trademark.opposition_filed", "trademark.opposition_updated", "trademark.opposition_document_added", "trademark.hearing_scheduled", "trademark.hearing_updated", "trademark.exam_report_added", "trademark.document_added", "trademark.proprietor_changed", "trademark.attorney_changed", "trademark.cited_mark_added", "trademark.renewal_due", "*" ] }, "description": "Subscribe to specific events, or [\"*\"] for all. Unknown events are rejected with 400." }, "monitored_applications": { "type": "array", "items": { "type": "string" }, "description": "Application numbers to monitor (empty = all your accessible TMs)." } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Create webhook (API-key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{webhook_id}/": { "put": { "tags": [ "Webhooks" ], "summary": "Update webhook (API-key)", "operationId": "putV1WebhooksWebhookId", "description": "Update a webhook subscription.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Update webhook (API-key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook (API-key)", "operationId": "deleteV1WebhooksWebhookId", "description": "Delete a webhook subscription.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "responses": { "200": { "description": "Delete webhook (API-key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{webhook_id}/ping/": { "post": { "tags": [ "Webhooks" ], "summary": "Ping webhook (API-key)", "operationId": "postV1WebhooksWebhookIdPing", "description": "Send a test event to the webhook.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "responses": { "200": { "description": "Ping webhook (API-key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{webhook_id}/logs/": { "get": { "tags": [ "Webhooks" ], "summary": "Webhook deliveries (API-key)", "operationId": "getV1WebhooksWebhookIdLogs", "description": "Recent delivery attempts for a webhook.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Max results (default 50, max 100)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Webhook deliveries (API-key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Format: `X-API-Key: tmsp_your_key_here` (legacy `Authorization: Api-Key tmsp_…` also accepted)." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT from POST /user/v1/login/ — for /user/v1/* dashboard & account endpoints." } }, "parameters": { "app_no": { "name": "app_no", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Trademark application number (numeric only)", "example": "1234567" } }, "schemas": { "TrademarkSummary": { "type": "object", "properties": { "application_number": { "type": "string" }, "word_mark": { "type": "string" }, "class_number": { "type": "string" }, "status": { "type": "string" }, "application_date": { "type": "string" }, "tm_type": { "type": "string" }, "state": { "type": "string" }, "relevance_score": { "type": "number", "description": "SMART search relevance (0–1)" }, "match_method": { "type": "string", "description": "How this result was matched — exact, prefix, fulltext, suffix, etc." } } }, "TrademarkDetail": { "type": "object", "properties": { "trademark": { "$ref": "#/components/schemas/TrademarkSummary" }, "status_history": { "type": "array", "items": { "type": "object" } }, "proprietors": { "type": "array", "items": { "type": "object" } }, "attorneys": { "type": "array", "items": { "type": "object" } }, "oppositions": { "type": "array", "items": { "type": "object" } }, "hearings": { "type": "array", "items": { "type": "object" } }, "exam_reports": { "type": "array", "items": { "type": "object" } }, "documents": { "type": "array", "items": { "type": "object" } }, "threats": { "type": "array", "items": { "type": "object" } } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing API key. Add header: Authorization: Api-Key your_key", "code": "auth_required" } } } }, "ValidationError": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "word_mark parameter is required", "code": "validation_error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Trademark not found", "code": "not_found" } } } }, "CategoryBlocked": { "description": "Data category not on your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Oppositions data is not included in your plan.", "code": "category_blocked" } } } }, "PlanInactive": { "description": "Plan is inactive or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Your subscription is inactive, please renew your plan to again access document", "code": "plan_inactive" } } } }, "QuotaExceeded": { "description": "Monthly API call quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "You have used all your API calls for this month.", "code": "quota_exceeded", "used": 25000, "limit": 25000 } } } }, "LogoQuotaExceeded": { "description": "Monthly logo search quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "You have used all your logo searches for this month.", "code": "logo_quota_exceeded" } } } }, "BulkNotOnPlan": { "description": "Bulk search not available on your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Bulk trademark search is a premium feature not included in your plan.", "code": "bulk_not_on_plan" } } } }, "WebhooksNotOnPlan": { "description": "Webhooks not available on your plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Webhooks are not included in your plan.", "code": "webhooks_not_on_plan" } } } } } } }