{"openapi":"3.1.0","info":{"title":"Patent77 API","version":"1.0.0","description":"Patent77 is an AI prior-art search engine. Describe an invention in plain English and it searches the live patent record the way a professional searcher does — synonym expansion, classification guesses, iterative queries — then reads the closest references and returns a patentability report: every reference cited by publication number, mapped element-by-element against your invention, with an examiner-style novelty and obviousness read and honest confidence flags. Search firms charge $1,000–$3,000 and take two weeks; Patent77 is self-serve and takes minutes. The same engine is a single-key JSON API and a hosted MCP server, so patent-drafting and research agents can run prior-art searches as a native tool.","contact":{"name":"Patent77","url":"https://www.patent77.com","email":"hello@patent77.com"}},"servers":[{"url":"https://www.patent77.com"}],"security":[{},{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"p77_live_*"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]},"ClaimElement":{"type":"object","description":"A claim-style element extracted from the invention description - the unit references are compared against.","properties":{"id":{"type":"string","description":"Element id, e.g. \"e1\"."},"label":{"type":"string","description":"Short handle for the element."},"text":{"type":"string","description":"The full element phrasing."}},"required":["id","text"]},"PatentRef":{"type":"object","description":"One prior-art reference. Always a real document retrieved from the corpus this run - never invented.","properties":{"pub_number":{"type":"string","description":"Publication number, e.g. US10123456B2."},"title":{"type":"string"},"abstract":{"type":["string","null"]},"assignee":{"type":["string","null"]},"pub_date":{"type":["string","null"],"description":"YYYY-MM-DD when parseable, otherwise as printed."},"url":{"type":"string","format":"uri","description":"Canonical public source URL - every reference is verifiable."},"score":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Relevance 0..1."},"overlap":{"type":["string","null"],"description":"One line: what this reference teaches that overlaps the invention."},"elements_hit":{"type":"array","items":{"type":"string"},"description":"Ids of the claim elements this reference reads on. Omitted on anonymous (truncated) responses."}},"required":["pub_number","title","url"]},"Search":{"type":"object","description":"A prior-art search. Anonymous callers get a truncated view: top 3 references, no element mapping.","properties":{"id":{"type":["string","null"],"description":"Null on anonymous calls (nothing is persisted)."},"status":{"type":"string","enum":["processing","completed","failed"]},"invention_title":{"type":"string"},"risk":{"type":"string","enum":["high","medium","low","unclear"],"description":"Headline knockout risk."},"risk_note":{"type":"string","description":"One-paragraph plain-English summary of the risk read."},"elements":{"type":"array","items":{"type":"object","description":"A claim-style element extracted from the invention description - the unit references are compared against.","properties":{"id":{"type":"string","description":"Element id, e.g. \"e1\"."},"label":{"type":"string","description":"Short handle for the element."},"text":{"type":"string","description":"The full element phrasing."}},"required":["id","text"]}},"queries":{"type":"array","items":{"type":"string"},"description":"The corpus queries actually executed (transparency)."},"refs":{"type":"array","items":{"type":"object","description":"One prior-art reference. Always a real document retrieved from the corpus this run - never invented.","properties":{"pub_number":{"type":"string","description":"Publication number, e.g. US10123456B2."},"title":{"type":"string"},"abstract":{"type":["string","null"]},"assignee":{"type":["string","null"]},"pub_date":{"type":["string","null"],"description":"YYYY-MM-DD when parseable, otherwise as printed."},"url":{"type":"string","format":"uri","description":"Canonical public source URL - every reference is verifiable."},"score":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Relevance 0..1."},"overlap":{"type":["string","null"],"description":"One line: what this reference teaches that overlaps the invention."},"elements_hit":{"type":"array","items":{"type":"string"},"description":"Ids of the claim elements this reference reads on. Omitted on anonymous (truncated) responses."}},"required":["pub_number","title","url"]},"description":"Ranked, deduped, scored references."},"candidates_considered":{"type":"integer","description":"Raw corpus hits before rerank (honesty stat)."},"engine":{"type":"string","description":"LLM backend that produced the result."},"corpus":{"type":"string","description":"Corpus searched, e.g. \"google-patents\"."},"created_at":{"type":"string","format":"date-time"}},"required":["status","risk","refs"]},"MatrixRow":{"type":"object","description":"One row of the element-by-reference matrix: how each cited reference reads on one claim element.","properties":{"element_id":{"type":"string"},"cells":{"type":"array","items":{"type":"object","properties":{"pub_number":{"type":"string"},"reads":{"type":"string","enum":["yes","partial","no"]},"note":{"type":["string","null"],"description":"What the reference discloses for this element."}},"required":["pub_number","reads"]}}},"required":["element_id","cells"]},"Report":{"type":"object","description":"A full patentability report over a search. Paid plans only.","properties":{"id":{"type":"string"},"search_id":{"type":"string"},"status":{"type":"string","enum":["processing","completed","failed"]},"verdict":{"type":"string","enum":["significant-overlap","partial-overlap","white-space","unclear"]},"headline":{"type":"string","description":"One-sentence bottom line."},"narrative":{"type":"string","description":"Examiner-style novelty/obviousness discussion (markdown)."},"matrix":{"type":"array","items":{"type":"object","description":"One row of the element-by-reference matrix: how each cited reference reads on one claim element.","properties":{"element_id":{"type":"string"},"cells":{"type":"array","items":{"type":"object","properties":{"pub_number":{"type":"string"},"reads":{"type":"string","enum":["yes","partial","no"]},"note":{"type":["string","null"],"description":"What the reference discloses for this element."}},"required":["pub_number","reads"]}}},"required":["element_id","cells"]}},"limitations":{"type":"string","description":"What this search did NOT cover. Always present."}},"required":["id","search_id","status"]},"Patent":{"type":"object","description":"One patent looked up by publication number.","properties":{"pub_number":{"type":"string"},"title":{"type":"string"},"abstract":{"type":["string","null"]},"assignee":{"type":["string","null"]},"pub_date":{"type":["string","null"]},"claims":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri","description":"Canonical public source URL."}},"required":["pub_number","title","url"]},"Usage":{"type":"object","description":"Current billing-period usage vs quota for the calling key's owner.","properties":{"plan":{"type":"string","enum":["free","pro","scale"]},"period":{"type":"string","description":"Metering window, e.g. \"calendar_month_utc\"."},"searches":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"}}},"reports":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"overage_usd":{"type":"number"}}},"rate_limit_per_minute":{"type":"integer"}},"required":["plan"]}}},"paths":{"/api/v1":{"get":{"summary":"Self-describing index: every endpoint, the MCP server, OpenAPI, pricing and docs URLs in one JSON response.","operationId":"get_api_v1","security":[{},{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/pricing":{"get":{"summary":"Machine-readable pricing - plans, included searches and reports, per-report overage, rate limits and features.","operationId":"get_api_v1_pricing","security":[{},{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"units":{"type":"object","properties":{"search":{"type":"string"},"report":{"type":"string"}},"description":"Plain-English definition of each metered unit."},"currency":{"type":"string"},"anonymous":{"type":"object","description":"The keyless trial tier: rate limits and truncation rules."},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["free","pro","scale"]},"name":{"type":"string"},"price_usd_per_month":{"type":"number"},"included_searches_per_month":{"type":"integer"},"included_reports_per_month":{"type":"integer"},"overage_usd_per_report":{"type":"number"},"rate_limit_per_minute":{"type":"integer"},"monitors":{"type":"integer"},"api_access":{"type":"boolean"}}}}}}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/searches":{"post":{"summary":"Run an AI prior-art search: plan claim elements + corpus queries from a plain-English description, search the live Google Patents corpus, return scored references with a headline risk. Anonymous calls work but are truncated (top 3 references, no element mapping); an API key gets plan quota and full references.","operationId":"post_api_v1_searches","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Retries with the same key return the original result instead of running (and billing) a second search.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"A prior-art search. Anonymous callers get a truncated view: top 3 references, no element mapping.","properties":{"id":{"type":["string","null"],"description":"Null on anonymous calls (nothing is persisted)."},"status":{"type":"string","enum":["processing","completed","failed"]},"invention_title":{"type":"string"},"risk":{"type":"string","enum":["high","medium","low","unclear"],"description":"Headline knockout risk."},"risk_note":{"type":"string","description":"One-paragraph plain-English summary of the risk read."},"elements":{"type":"array","items":{"type":"object","description":"A claim-style element extracted from the invention description - the unit references are compared against.","properties":{"id":{"type":"string","description":"Element id, e.g. \"e1\"."},"label":{"type":"string","description":"Short handle for the element."},"text":{"type":"string","description":"The full element phrasing."}},"required":["id","text"]}},"queries":{"type":"array","items":{"type":"string"},"description":"The corpus queries actually executed (transparency)."},"refs":{"type":"array","items":{"type":"object","description":"One prior-art reference. Always a real document retrieved from the corpus this run - never invented.","properties":{"pub_number":{"type":"string","description":"Publication number, e.g. US10123456B2."},"title":{"type":"string"},"abstract":{"type":["string","null"]},"assignee":{"type":["string","null"]},"pub_date":{"type":["string","null"],"description":"YYYY-MM-DD when parseable, otherwise as printed."},"url":{"type":"string","format":"uri","description":"Canonical public source URL - every reference is verifiable."},"score":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Relevance 0..1."},"overlap":{"type":["string","null"],"description":"One line: what this reference teaches that overlaps the invention."},"elements_hit":{"type":"array","items":{"type":"string"},"description":"Ids of the claim elements this reference reads on. Omitted on anonymous (truncated) responses."}},"required":["pub_number","title","url"]},"description":"Ranked, deduped, scored references."},"candidates_considered":{"type":"integer","description":"Raw corpus hits before rerank (honesty stat)."},"engine":{"type":"string","description":"LLM backend that produced the result."},"corpus":{"type":"string","description":"Corpus searched, e.g. \"google-patents\"."},"created_at":{"type":"string","format":"date-time"}},"required":["status","risk","refs"]}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"Plain-English description of the invention - what it is, what it does, what makes it different. At least a sentence or two."},"title":{"type":"string","description":"Optional short title to store with the search."}},"required":["description"]}}}}},"get":{"summary":"List the caller's own saved searches, newest first.","operationId":"get_api_v1_searches","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"searches":{"type":"array","items":{"type":"object","description":"A prior-art search. Anonymous callers get a truncated view: top 3 references, no element mapping.","properties":{"id":{"type":["string","null"],"description":"Null on anonymous calls (nothing is persisted)."},"status":{"type":"string","enum":["processing","completed","failed"]},"invention_title":{"type":"string"},"risk":{"type":"string","enum":["high","medium","low","unclear"],"description":"Headline knockout risk."},"risk_note":{"type":"string","description":"One-paragraph plain-English summary of the risk read."},"elements":{"type":"array","items":{"type":"object","description":"A claim-style element extracted from the invention description - the unit references are compared against.","properties":{"id":{"type":"string","description":"Element id, e.g. \"e1\"."},"label":{"type":"string","description":"Short handle for the element."},"text":{"type":"string","description":"The full element phrasing."}},"required":["id","text"]}},"queries":{"type":"array","items":{"type":"string"},"description":"The corpus queries actually executed (transparency)."},"refs":{"type":"array","items":{"type":"object","description":"One prior-art reference. Always a real document retrieved from the corpus this run - never invented.","properties":{"pub_number":{"type":"string","description":"Publication number, e.g. US10123456B2."},"title":{"type":"string"},"abstract":{"type":["string","null"]},"assignee":{"type":["string","null"]},"pub_date":{"type":["string","null"],"description":"YYYY-MM-DD when parseable, otherwise as printed."},"url":{"type":"string","format":"uri","description":"Canonical public source URL - every reference is verifiable."},"score":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Relevance 0..1."},"overlap":{"type":["string","null"],"description":"One line: what this reference teaches that overlaps the invention."},"elements_hit":{"type":"array","items":{"type":"string"},"description":"Ids of the claim elements this reference reads on. Omitted on anonymous (truncated) responses."}},"required":["pub_number","title","url"]},"description":"Ranked, deduped, scored references."},"candidates_considered":{"type":"integer","description":"Raw corpus hits before rerank (honesty stat)."},"engine":{"type":"string","description":"LLM backend that produced the result."},"corpus":{"type":"string","description":"Corpus searched, e.g. \"google-patents\"."},"created_at":{"type":"string","format":"date-time"}},"required":["status","risk","refs"]}},"request_id":{"type":"string"}}}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/searches/{id}":{"get":{"summary":"Get one search with its full reference list, elements and executed queries.","operationId":"get_api_v1_searches_id","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Search id returned by POST /searches.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"A prior-art search. Anonymous callers get a truncated view: top 3 references, no element mapping.","properties":{"id":{"type":["string","null"],"description":"Null on anonymous calls (nothing is persisted)."},"status":{"type":"string","enum":["processing","completed","failed"]},"invention_title":{"type":"string"},"risk":{"type":"string","enum":["high","medium","low","unclear"],"description":"Headline knockout risk."},"risk_note":{"type":"string","description":"One-paragraph plain-English summary of the risk read."},"elements":{"type":"array","items":{"type":"object","description":"A claim-style element extracted from the invention description - the unit references are compared against.","properties":{"id":{"type":"string","description":"Element id, e.g. \"e1\"."},"label":{"type":"string","description":"Short handle for the element."},"text":{"type":"string","description":"The full element phrasing."}},"required":["id","text"]}},"queries":{"type":"array","items":{"type":"string"},"description":"The corpus queries actually executed (transparency)."},"refs":{"type":"array","items":{"type":"object","description":"One prior-art reference. Always a real document retrieved from the corpus this run - never invented.","properties":{"pub_number":{"type":"string","description":"Publication number, e.g. US10123456B2."},"title":{"type":"string"},"abstract":{"type":["string","null"]},"assignee":{"type":["string","null"]},"pub_date":{"type":["string","null"],"description":"YYYY-MM-DD when parseable, otherwise as printed."},"url":{"type":"string","format":"uri","description":"Canonical public source URL - every reference is verifiable."},"score":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Relevance 0..1."},"overlap":{"type":["string","null"],"description":"One line: what this reference teaches that overlaps the invention."},"elements_hit":{"type":"array","items":{"type":"string"},"description":"Ids of the claim elements this reference reads on. Omitted on anonymous (truncated) responses."}},"required":["pub_number","title","url"]},"description":"Ranked, deduped, scored references."},"candidates_considered":{"type":"integer","description":"Raw corpus hits before rerank (honesty stat)."},"engine":{"type":"string","description":"LLM backend that produced the result."},"corpus":{"type":"string","description":"Corpus searched, e.g. \"google-patents\"."},"created_at":{"type":"string","format":"date-time"}},"required":["status","risk","refs"]}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/reports":{"post":{"summary":"Build a full patentability report over a search: verdict, examiner-style novelty/obviousness narrative, element-by-reference matrix and a limitations section. Pass a prior search_id, or a description to run search + report in one call. Paid plans only (402 upgrade_required otherwise); counts toward the monthly report quota, then billed per report.","operationId":"post_api_v1_reports","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional. Retries with the same key return the original report instead of building (and billing) a second one.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"A full patentability report over a search. Paid plans only.","properties":{"id":{"type":"string"},"search_id":{"type":"string"},"status":{"type":"string","enum":["processing","completed","failed"]},"verdict":{"type":"string","enum":["significant-overlap","partial-overlap","white-space","unclear"]},"headline":{"type":"string","description":"One-sentence bottom line."},"narrative":{"type":"string","description":"Examiner-style novelty/obviousness discussion (markdown)."},"matrix":{"type":"array","items":{"type":"object","description":"One row of the element-by-reference matrix: how each cited reference reads on one claim element.","properties":{"element_id":{"type":"string"},"cells":{"type":"array","items":{"type":"object","properties":{"pub_number":{"type":"string"},"reads":{"type":"string","enum":["yes","partial","no"]},"note":{"type":["string","null"],"description":"What the reference discloses for this element."}},"required":["pub_number","reads"]}}},"required":["element_id","cells"]}},"limitations":{"type":"string","description":"What this search did NOT cover. Always present."}},"required":["id","search_id","status"]}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"search_id":{"type":"string","description":"Id of a completed search to report on."},"description":{"type":"string","description":"Plain-English invention description - runs a new search and a report in one call."}},"description":"Provide exactly one of search_id or description."}}}}}},"/api/v1/reports/{id}":{"get":{"summary":"Get one patentability report - verdict, narrative, matrix and limitations.","operationId":"get_api_v1_reports_id","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Report id returned by POST /reports.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"A full patentability report over a search. Paid plans only.","properties":{"id":{"type":"string"},"search_id":{"type":"string"},"status":{"type":"string","enum":["processing","completed","failed"]},"verdict":{"type":"string","enum":["significant-overlap","partial-overlap","white-space","unclear"]},"headline":{"type":"string","description":"One-sentence bottom line."},"narrative":{"type":"string","description":"Examiner-style novelty/obviousness discussion (markdown)."},"matrix":{"type":"array","items":{"type":"object","description":"One row of the element-by-reference matrix: how each cited reference reads on one claim element.","properties":{"element_id":{"type":"string"},"cells":{"type":"array","items":{"type":"object","properties":{"pub_number":{"type":"string"},"reads":{"type":"string","enum":["yes","partial","no"]},"note":{"type":["string","null"],"description":"What the reference discloses for this element."}},"required":["pub_number","reads"]}}},"required":["element_id","cells"]}},"limitations":{"type":"string","description":"What this search did NOT cover. Always present."}},"required":["id","search_id","status"]}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/patents/{pub_number}":{"get":{"summary":"Look up one patent by publication number - title, abstract, assignee, publication date, claims and the canonical source URL. Anonymous allowed, rate-limited.","operationId":"get_api_v1_patents_pub_number","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"pub_number","in":"path","required":true,"description":"Publication number, e.g. US10123456B2.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"One patent looked up by publication number.","properties":{"pub_number":{"type":"string"},"title":{"type":"string"},"abstract":{"type":["string","null"]},"assignee":{"type":["string","null"]},"pub_date":{"type":["string","null"]},"claims":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri","description":"Canonical public source URL."}},"required":["pub_number","title","url"]}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/usage":{"get":{"summary":"Current billing-period usage vs quota - searches and reports used, remaining, and the caller's rate limit.","operationId":"get_api_v1_usage","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Current billing-period usage vs quota for the calling key's owner.","properties":{"plan":{"type":"string","enum":["free","pro","scale"]},"period":{"type":"string","description":"Metering window, e.g. \"calendar_month_utc\"."},"searches":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"}}},"reports":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"overage_usd":{"type":"number"}}},"rate_limit_per_minute":{"type":"integer"}},"required":["plan"]}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Upgrade required (reports need a Pro/Scale plan)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"422":{"description":"Unprocessable (e.g. the description is not a searchable invention)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["error"]}}}}}}}}}