This is the full developer documentation for Patents & Trademarks MCP # Patents & Trademarks MCP > Ask your AI assistant real questions about U.S. patents and trademarks. The answers come from the official USPTO APIs. ## Connect in one step Each button starts the server on your computer. It needs your free [USPTO keys](/docs/keys/). [Claude Desktop](https://github.com/blen-labs/uspto-mcp-server/releases/latest/download/uspto-mcp-server.mcpb)Download the extension. Open the file, and Claude asks for your keys. [Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=uspto\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBibGVuL3VzcHRvLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7IlVTUFRPX0FQSV9LRVkiOiIiLCJVU1BUT19UU0RSX0FQSV9LRVkiOiIifX0%3D)Add to Cursor. Cursor opens with the server filled in. [VS Code](vscode:mcp/install?%7B%22name%22%3A%22uspto%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40blen%2Fuspto-mcp-server%22%5D%2C%22env%22%3A%7B%22USPTO_API_KEY%22%3A%22%22%2C%22USPTO_TSDR_API_KEY%22%3A%22%22%7D%7D)Add to VS Code. VS Code shows the server for review. [Other clients](/docs/connect/)Claude Code, Gemini CLI, ChatGPT, and manual setup. ## Ask in plain language * “Which IPRs have been filed against patent 10,169,987, and how did they end?” * “Show the office actions and rejection grounds for application 17/248,024.” * “What’s the status of trademark serial number 97123456?” ## What it covers Patents Search applications and grants by title, applicant, inventor, CPC class, dates, or status. Read one application’s continuity, assignments, term adjustment, transactions, and documents. PTAB Trials (IPR, PGR, CBM, DER), decisions, papers, ex parte appeals, and interferences. Office actions Full text, rejection grounds, and citations. Petition decisions Decisions with their documents. Trademarks Status for 1 to 25 cases in one call, and the document list of a case. Bulk datasets The catalog and its file lists. ## How it works 1. **Find the call.** `search_api` searches the SDK documentation for the methods that fit the question. 2. **Read its shape.** `describe_schema` returns a method’s signature and a ready-to-run example. 3. **Run a program.** Your assistant writes a short JavaScript program, and `execute` runs it in a sandbox with no network, file, or environment access. Your keys stay in the server process and never enter the sandbox. The server sends one request at a time for each key, as USPTO requires. [How it works](/docs/how-it-works/) ## Made for assistants too One file for the site [llms.txt](/docs/llms.txt) lists every page. [llms-full.txt](/docs/llms-full.txt) is the whole site in one file. Markdown for every page **Copy page** at the top of a page copies it as Markdown, ready to paste. Ask about a page The **Open** menu sends a page to ChatGPT or Claude. *** Open source under Apache-2.0. This is an independent project. It calls public USPTO APIs and is not affiliated with or endorsed by the USPTO or the U.S. government. # Connect your assistant > Add the server to Claude Desktop, Claude Code, Cursor, VS Code, or Gemini CLI, and what ChatGPT and other remote clients need. The server runs on your computer, and your assistant starts it. Before you connect: * Install [Node.js](https://nodejs.org/) 24.11 or later, or 26. * [Get your keys](/docs/keys/). ## Claude Desktop [Download the extension](https://github.com/blen-labs/uspto-mcp-server/releases/latest/download/uspto-mcp-server.mcpb) Open the downloaded `.mcpb` file, or drag it into the Claude Desktop window. Claude Desktop asks for your keys during the install. To set it up by hand, open **Settings → Developer → Edit Config**, add the server, and restart Claude Desktop: claude_desktop_config.json ```json { "mcpServers": { "uspto": { "command": "npx", "args": [ "-y", "@blen/uspto-mcp-server" ], "env": { "USPTO_API_KEY": "your-odp-key", "USPTO_TSDR_API_KEY": "your-tsdr-key" } } } } ``` ## Claude Code Run this command with your keys in place of the two example values: ```bash claude mcp add uspto \ -e USPTO_API_KEY=your-odp-key \ -e USPTO_TSDR_API_KEY=your-tsdr-key \ -- npx -y @blen/uspto-mcp-server ``` ## Cursor [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=uspto\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBibGVuL3VzcHRvLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7IlVTUFRPX0FQSV9LRVkiOiIiLCJVU1BUT19UU0RSX0FQSV9LRVkiOiIifX0%3D) Cursor opens with the server filled in and the two key fields empty. Add your keys, then install. To set it up by hand, add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in one project: mcp.json ```json { "mcpServers": { "uspto": { "command": "npx", "args": [ "-y", "@blen/uspto-mcp-server" ], "env": { "USPTO_API_KEY": "your-odp-key", "USPTO_TSDR_API_KEY": "your-tsdr-key" } } } } ``` ## VS Code [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22uspto%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40blen%2Fuspto-mcp-server%22%5D%2C%22env%22%3A%7B%22USPTO_API_KEY%22%3A%22%22%2C%22USPTO_TSDR_API_KEY%22%3A%22%22%7D%7D) VS Code shows the server for review, with the two key fields empty. Add your keys, then install. To set it up by hand, see [MCP configuration](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration) in the VS Code documentation. ## Gemini CLI Add the server to `~/.gemini/settings.json`, or to `.gemini/settings.json` in one project: settings.json ```json { "mcpServers": { "uspto": { "command": "npx", "args": [ "-y", "@blen/uspto-mcp-server" ], "env": { "USPTO_API_KEY": "your-odp-key", "USPTO_TSDR_API_KEY": "your-tsdr-key" } } } } ``` ## ChatGPT and other remote clients ChatGPT, Claude custom connectors, and Gemini Enterprise connect to a remote server over HTTPS. They do not start a server on your computer. BLEN hosts one at `https://uspto.mcp.blenlabs.com/mcp/account`. Add that URL as a custom connector and sign in with Google when your client asks. Then save your own ODP key, and your TSDR key if you have one, on the [account page](https://uspto.mcp.blenlabs.com/account). Each key is stored encrypted and used only for your requests. Without signing in, `https://uspto.mcp.blenlabs.com/mcp` offers the search and schema tools but cannot run code. To run your own instance instead, see [Self-host](/docs/self-host/). ## Check that it works Ask your assistant: > Has anyone challenged patent 10,169,987 at the PTAB? The assistant calls `search_api` to find the right methods, then `execute` to run them. | Message | Cause | Fix | | ---------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- | | `SourceUnavailable` | The key for that source is missing or blank. | Add the key to your client’s configuration. See [Get your keys](/docs/keys/). | | `Unauthorized` | USPTO refused the ODP key. | Check the key, and see [Keep a key working](/docs/keys/#keep-a-key-working). | | `NotFound` on every trademark call | TSDR reports a key that it refuses as not found. | Check the TSDR key. | | `SandboxUnavailable` | No sandbox runtime is available for `execute`. | Install [Deno](https://docs.deno.com/runtime/getting_started/installation/). | Note The built-in sandbox needs no install on Node.js 24 and 26 on macOS (Apple silicon), Linux (x64 and arm64), and Windows (x64). On other systems the server uses Deno. # How it works > The three tools, the sandbox that runs your assistant's code, and how the server stays inside USPTO's limits. The server gives your assistant a small JavaScript SDK in place of dozens of narrow tools. The assistant writes the exact query it needs, and the server runs that code in a sandbox. 1. **Your assistant**Calls execute with a short program. 2. **Sandbox**Runs the program with no network, file, or environment access. 3. **odp and tsdr SDK**Each call crosses to the server process. 4. **Server process**Adds your key, queues the call, and caches the response. 5. **USPTO**api.uspto.gov and tsdrapi.uspto.gov ## Three tools The assistant uses them in this order. | Tool | What it does | | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | | `search_api` | Searches the SDK method documentation and a dictionary of response fields. Returns signatures and ready-to-run examples. | | `describe_schema` | Looks up one entry, such as `odp.patents.search`, or lists a namespace, such as `odp.ptab.`. | | `execute` | Runs JavaScript in the sandbox, with `odp` and `tsdr` as globals. | All three are read-only. [Tools](/docs/reference/tools/) has their inputs and limits. ## What the assistant writes For “Has anyone challenged patent 10,169,987 at the PTAB?”, the assistant can run a program like this one: ```js // PTAB: every AIA trial (IPR/PGR/CBM) filed against one patent, then the // decisions in the first trial. Calls run one at a time per API key, so keep // the fan-out small. const patentNumber = '10169987'; const trials = await odp.ptab.proceedings.search({ q: `patentOwnerData.patentNumber:${patentNumber}`, fields: [ 'trialNumber', 'trialMetaData.trialTypeCode', 'trialMetaData.trialStatusCategory', 'trialMetaData.petitionFilingDate', 'regularPetitionerData.realPartyInInterestName', ], limit: 50, }); const list = trials.patentTrialProceedingDataBag ?? []; const first = list[0]?.trialNumber; const decisions = first ? await odp.ptab.decisions.byTrial(first) : { patentTrialDocumentDataBag: [] }; return { trials: list.map((t) => ({ trial: t.trialNumber, type: t.trialMetaData?.trialTypeCode, status: t.trialMetaData?.trialStatusCategory, petitioner: t.regularPetitionerData?.realPartyInInterestName, })), firstTrialDecisions: (decisions.patentTrialDocumentDataBag ?? []).map( (d) => ({ date: d.decisionData?.decisionIssueDate, type: d.decisionData?.decisionTypeCategory, outcome: d.decisionData?.trialOutcomeCategory, title: d.documentData?.documentTitleText, }), ), }; ``` It then answers in plain English, and names the trials and decisions that it found. ## The sandbox * The program has no network, file system, environment, or subprocess access. * The only way out is the `odp` and `tsdr` SDK. Each call goes to the server process, which adds your key and calls USPTO. * Each run has a time limit, 30 seconds by default, and size limits for code, results, and logs. [Security](/docs/security/) has more. ## USPTO’s limits USPTO allows one request in flight for each API key, 4 to 15 requests each second, and a weekly quota. It asks clients to wait at least 5 seconds after a `429` response. So the server: * Sends one call at a time for each key. By default it starts at most 4 each second for ODP and 1 for TSDR. * Pauses a key for at least 5 seconds after a `429`, then retries that call once if the pause is 30 seconds or less. * Caps the USPTO calls in one `execute` run, by default at 50 for ODP and 25 for TSDR. * Caches responses, for 10 minutes by default, so a repeated question does not spend quota. `Promise.all` in a program is not faster: the calls still go out one at a time. A program can have at most 16 calls pending at once. # Get your keys > The two free USPTO keys the server uses, where to get each one, and how to keep a key active. The server calls USPTO with your own keys. Both are free. USPTO issues a key to one person, so do not share yours. | Key | What it unlocks | Where to get it | Setting | | -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------- | | Open Data Portal (ODP) key | Patents, PTAB, petition decisions, office actions, bulk dataset catalog | [data.uspto.gov/myodp](https://data.uspto.gov/myodp), **Manage API Key** | `USPTO_API_KEY` | | TSDR key | Trademark status and documents | [USPTO API Key Manager](https://account.uspto.gov/api-manager) | `USPTO_TSDR_API_KEY` | * The two keys are separate. The ODP key does not work on TSDR. * With one key only, the other source is off. Its calls return `SourceUnavailable` with instructions, and the rest still works. ## Get the ODP key 1. Sign in to your USPTO.gov account, or create one, and turn on multi-factor authentication. 2. Link the account to a verified ID.me identity. You do this once. 3. Sign in at [data.uspto.gov/myodp](https://data.uspto.gov/myodp) and select **Manage API Key**. USPTO describes each step in [Register for ODP access](https://data.uspto.gov/support/universal-registration). ## Get the TSDR key Get it in the [USPTO API Key Manager](https://account.uspto.gov/api-manager). You need it only for trademark questions. ## Keep a key working * **Use it.** USPTO’s [Getting Started](https://data.uspto.gov/apis/getting-started) page says a key “shouldn’t expire if it is used at least one time per year”. The same page says an ODP key that stays unused for 90 days is deleted. One call every 90 days satisfies both. * **Keep it private.** USPTO says: “Do not share it with others. It is an identifier unique to you.” * **Check your profile if every call returns `403`.** USPTO may have deactivated the key. Complete the Open Data Portal fields in your USPTO.gov account settings, then select **Activate API Key** on the Manage API Key page. ## Where the key goes You give the keys to the server when you [connect your assistant](/docs/connect/). They stay in the server process on your computer. They never enter the sandbox, and the server removes a key from results and errors. # Recipes > Four programs that your assistant can run with execute, and tips for programs of your own. Each program runs as written in `execute`. They are plain JavaScript with top-level `await` and `return`, and the repository tests each one. ## An applicant’s recent patents `odp.patents.search` with `q`, `filters`, `rangeFilters`, `sort`, `fields`, and `facets`. ```js // Patent File Wrapper: an applicant's recent granted utility patents, newest // first, with only the fields needed (full records are large), plus a status // breakdown via facets. const applicant = 'PolyPlus Battery Company'; const r = await odp.patents.search({ q: `applicationMetaData.firstApplicantName:"${applicant}"`, filters: { 'applicationMetaData.applicationTypeLabelName': 'Utility' }, rangeFilters: { 'applicationMetaData.grantDate': ['2020-01-01', '2026-12-31'], }, sort: 'applicationMetaData.grantDate desc', fields: [ 'applicationNumberText', 'applicationMetaData.inventionTitle', 'applicationMetaData.patentNumber', 'applicationMetaData.grantDate', 'applicationMetaData.applicationStatusDescriptionText', ], facets: ['applicationMetaData.applicationStatusDescriptionText'], limit: 25, }); return { total: r.count, patents: (r.patentFileWrapperDataBag ?? []).map((p) => ({ application: p.applicationNumberText, patent: p.applicationMetaData?.patentNumber, granted: p.applicationMetaData?.grantDate, title: p.applicationMetaData?.inventionTitle, })), byStatus: r.facets, }; ``` ## PTAB challenges against a patent Every trial filed against one patent, then the decisions in the first trial. ```js // PTAB: every AIA trial (IPR/PGR/CBM) filed against one patent, then the // decisions in the first trial. Calls run one at a time per API key, so keep // the fan-out small. const patentNumber = '10169987'; const trials = await odp.ptab.proceedings.search({ q: `patentOwnerData.patentNumber:${patentNumber}`, fields: [ 'trialNumber', 'trialMetaData.trialTypeCode', 'trialMetaData.trialStatusCategory', 'trialMetaData.petitionFilingDate', 'regularPetitionerData.realPartyInInterestName', ], limit: 50, }); const list = trials.patentTrialProceedingDataBag ?? []; const first = list[0]?.trialNumber; const decisions = first ? await odp.ptab.decisions.byTrial(first) : { patentTrialDocumentDataBag: [] }; return { trials: list.map((t) => ({ trial: t.trialNumber, type: t.trialMetaData?.trialTypeCode, status: t.trialMetaData?.trialStatusCategory, petitioner: t.regularPetitionerData?.realPartyInInterestName, })), firstTrialDecisions: (decisions.patentTrialDocumentDataBag ?? []).map( (d) => ({ date: d.decisionData?.decisionIssueDate, type: d.decisionData?.decisionTypeCategory, outcome: d.decisionData?.trialOutcomeCategory, title: d.documentData?.documentTitleText, }), ), }; ``` ## Prosecution history From a patent number to its application, then its office actions and rejection grounds. ```js // One application's prosecution story: resolve a patent number, then pull its // office actions (current Office Action Search API) and the rejection grounds // raised in each. const found = await odp.patents.byPatentNumber('11,646,472', { fields: ['applicationNumberText', 'applicationMetaData.inventionTitle'], }); const app = found.patentFileWrapperDataBag?.[0]; if (!app) return { error: 'patent not found' }; const actions = await odp.officeActions.search({ q: `applicationNumberText:${app.applicationNumberText}`, fields: [ 'officeActionRecordIdentifier', 'documentCode', 'documentCodeDescriptionText', 'submissionDate', 'rejectionTypeBag', ], sort: 'submissionDate asc', limit: 50, }); return { application: app.applicationNumberText, title: app.applicationMetaData?.inventionTitle, officeActions: (actions.officeActionDataBag ?? []).map((a) => ({ date: a.submissionDate, code: a.documentCode, what: a.documentCodeDescriptionText, grounds: a.rejectionTypeBag, })), }; ``` ## Trademark status The status of several trademark cases in one request. ```js // TSDR: status of a few trademark applications in one request (multiStatus // takes up to 25). const r = await tsdr.multiStatus('sn', ['97123456', '97123457']); const marks = (r.transactionList ?? []).flatMap((t) => t.trademarks ?? []); return marks.map((t) => ({ serial: t.status?.serialNumber, mark: t.status?.markElement, status: t.status?.tm5StatusDesc, filed: t.status?.filingDate, registration: t.status?.usRegistrationNumber || null, classes: (t.gsList ?? []).map((g) => g.primeClassCode), })); ``` ## Tips * **Filter first.** USPTO serves one request at a time for each key, so calls queue. One well-filtered search is better than many lookups. * **Pass `fields` on every search.** Full patent and PTAB records are large. * **Start with a small `limit`**, 5 to 25. `count` gives the total. * **Use `facets`** to get counts without a page through the records. * **Return less.** A returned value over 256 KiB fails with `ResultTooLarge`. * **No matches is not an error.** A search with no matches returns `{ count: 0, …Bag: [] }`. The [SDK reference](/docs/reference/sdk/) lists every method. # SDK reference > Search parameters, identifiers, errors, limits, and every odp and tsdr method. Two globals are available inside `execute`: `odp` (USPTO Open Data Portal, `api.uspto.gov`) and `tsdr` (Trademark Status & Document Retrieval, `tsdrapi.uspto.gov`). Every method is async and returns the upstream JSON (or text, where noted) unchanged, except that an ODP search or list with no matches returns `{ count: 0, : [] }` (USPTO itself answers those with HTTP 404). The method reference at the end of this page is generated from the endpoint entries in `schema/odp.json` and `schema/tsdr.json`; `search_api` and `describe_schema` serve the same text plus a response-field dictionary (`odp.fields.*`, `tsdr.fields.*`). Each source needs its own key (`USPTO_API_KEY`, `USPTO_TSDR_API_KEY`). Without one, its calls throw `SourceUnavailable`. ## ODP search parameters Every `*.search` method in `odp.patents`, `odp.ptab`, `odp.petitions`, `odp.officeActions` and `odp.bulk` takes the same params object (or a bare query string, treated as `q`): | Param | Form | Sent as | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `q` | Lucene-style query over dotted field paths: `term`, `field:value`, `"exact phrase"`, `AND`/`OR`/`NOT`, wildcard `*`, range `[A TO B]` | `q` | | `filters` | `{ field: value \| [values] }` or `[{ name, value }]` — exact match | `filters: [{ name, value: [...] }]` | | `rangeFilters` | `{ field: [from, to] }` or `[{ field, valueFrom, valueTo }]` | `rangeFilters` | | `sort` | `'field desc'`, `['field asc', ...]`, or `[{ field, order }]` | `sort: [{ field, order }]` | | `fields` | `[paths]` — return only these (records are large; use it) | `fields` | | `facets` | `[fields]` — value counts across all matches | `facets` | | `limit` / `offset` (or `pagination`) | page size / start | `pagination: { offset, limit }` | Searches are POSTed as JSON (except `odp.bulk.search`, which the API only accepts as GET query params and which therefore takes at most one filter and one range filter — put further conditions in `q`). Responses carry `count` (total matches), a `*DataBag` array of records, and `facets` when requested. Field paths are relative to the record: for patents, `applicationNumberText`, `applicationMetaData.inventionTitle`, `applicationMetaData.filingDate`, `applicationMetaData.patentNumber`, … ```js await odp.patents.search({ q: 'applicationMetaData.inventionTitle:"solid state battery"', rangeFilters: { 'applicationMetaData.filingDate': ['2023-01-01', '2024-12-31'], }, sort: 'applicationMetaData.filingDate desc', fields: [ 'applicationNumberText', 'applicationMetaData.inventionTitle', 'applicationMetaData.filingDate', ], limit: 25, }); ``` ## Identifiers * **Application numbers** accept display forms — `'17248024'`, `'17/248,024'`, `'US 17/248,024'` — and PCT numbers (`'PCT/US2024/012345'` → `'PCTUS2024012345'`). Anything else throws `TypeError` before any request. * **Patent numbers** are different identifiers: resolve them with `odp.patents.byPatentNumber` (accepts `'11,000,000'`, `'US11000000B2'`, `'D987654'`). * **PTAB** trial numbers look like `'IPR2021-01599'`; appeal numbers like `'2023001234'`; interference numbers are 6 digits. * **TSDR case ids**: `'sn'` + 8-digit serial (`'sn97123456'`), `'rn'` + registration number (`'rn6123456'`), `'ref'` + Madrid reference number (letters and digits, case kept: `'refZ1231384'`), or `'ir'` + international registration number. A bare 8-digit number is a serial number; 7 or fewer digits a registration number. * **Other ids** (document and record identifiers, product ids) must be letters, digits, `-`, `_` and `.`, starting with a letter or digit — exactly as the API returns them. Anything else (for example `..`) throws `TypeError` before any request. * **Office-action rejection grounds** (`rejectionTypeBag`) are statute sections as strings: `'101'`, `'102'`, `'103'`, `'112'`. ## Errors An SDK call that fails throws an `Error` whose `name` is below and whose `status` carries the HTTP code where there is one. Uncaught, it ends the execution: the `execute` result is `{ ok: false, error: { name, message, status? }, logs }`, sent with `isError: true`. Use `try/catch` to handle it inline. | `name` | Meaning | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SourceUnavailable` | The source has no API key (or, in account mode, you haven’t saved one). | | `TypeError` | Bad argument (malformed application number, unknown method) — no request was made. | | `NotFound` | Upstream `404`. | | `Unauthorized` | Upstream `401`/`403`: key missing, invalid, or not allowed. | | `RateLimited` | Upstream `429` (every caller of the key is paused for at least 5 s, or `Retry-After`), the key’s queue is full, or the hourly budget is used up. Don’t retry immediately. | | `CallBudgetExceeded` | This `execute()` hit its per-source call budget (ODP 50, TSDR 25). | | `SubjectQuotaExceeded` | Your hourly per-subject quota on this server is used up. | | `ResponseTooLarge` | An upstream response exceeded 8 MiB — use `fields` and a smaller `limit`. | | `ArgumentsTooLarge` / `TooManyPendingCalls` | One SDK call’s arguments exceeded 64 KiB / more than 16 calls were pending at once. | | `HttpError` | Any other upstream error; `status` carries the HTTP code, and the message includes USPTO’s error detail. | Execution-level errors (in the `execute` result, not thrown by SDK calls): `ResultTooLarge` (the returned value is over 256 KiB — return less), `CodeTooLarge` (over 256 KiB of code), `TimeoutError`, `AbortError` (the client cancelled or the server is shutting down), `Busy` (too many executions running), `PolicyError` (the code uses a banned construct, or TypeScript syntax), and `SandboxUnavailable`. Logs are capped at 64 KiB / 1,000 lines (`[logs truncated]`). ## Limits USPTO serves **one request at a time per API key**, so calls queue (ODP at most 4/s, TSDR 1/s) and `Promise.all` does not speed things up. Fetch fewer, larger pages with `fields`, and return only what you need. See [architecture.md](https://github.com/blen-labs/uspto-mcp-server/blob/main/docs/architecture.md#rate-limits-and-guardrails). Not available from the sandbox: document PDFs, bulk files, PTAB file downloads and `search/download` CSV exports. Methods return their URLs. ## Method reference *Generated from `schema/odp.json` and `schema/tsdr.json`; edit those, then run `node scripts/gen-sdk-reference.mjs`.* ### `odp.patents` #### `odp.patents.search` `odp.patents.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search patent applications and granted patents (Patent File Wrapper) by keyword, invention title, inventor, applicant, filing or grant date, CPC class, examiner, art unit, status or patent number. Each record holds applicationMetaData plus continuity, assignments, PTA, attorneys and transactions; use fields to return only what you need. Returns { count, patentFileWrapperDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js await odp.patents.search({ q: 'applicationMetaData.inventionTitle:battery', rangeFilters: { 'applicationMetaData.filingDate': ['2024-01-01', '2024-03-31'], }, sort: 'applicationMetaData.filingDate desc', fields: [ 'applicationNumberText', 'applicationMetaData.inventionTitle', 'applicationMetaData.filingDate', 'applicationMetaData.patentNumber', 'applicationMetaData.applicationStatusDescriptionText', ], facets: ['applicationMetaData.applicationTypeLabelName'], limit: 5, }); ``` #### `odp.patents.get` `odp.patents.get(applicationNumber)` Full Patent File Wrapper record for one application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’): applicationMetaData (title, status, dates, patentNumber, inventors, applicants, CPC, examiner, art unit), continuity, assignments, attorney, PTA, transactions (eventDataBag), pgpub/grant document metadata. Large: prefer patents.search with fields when you need a few attributes. ```js const r = await odp.patents.get('17/248,024'); return r.patentFileWrapperDataBag[0].applicationMetaData; ``` #### `odp.patents.byPatentNumber` `odp.patents.byPatentNumber(patentNumber, { fields? })` Find the application behind a granted patent number (‘11,000,000’, ‘US11000000B2’, ‘D987654’, ‘RE49999’). Runs patents.search on applicationMetaData.patentNumber and returns the same shape (count 0 if not found). Use the returned applicationNumberText with the other patents.\* methods. ```js const r = await odp.patents.byPatentNumber('US 11,234,567 B2', { fields: ['applicationNumberText', 'applicationMetaData.inventionTitle'], }); return r.patentFileWrapperDataBag[0]; ``` #### `odp.patents.metaData` `odp.patents.metaData(applicationNumber)` Application metadata only (applicationMetaData: title, status, filing/grant dates, inventors, applicants, CPC, examiner, art unit, entity status) for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.metaData('17248024'); ``` #### `odp.patents.adjustment` `odp.patents.adjustment(applicationNumber)` Patent Term Adjustment data (patentTermAdjustmentData: A/B/C delays, applicant delay, total adjustment days, PTA history) for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.adjustment('17248024'); ``` #### `odp.patents.assignment` `odp.patents.assignment(applicationNumber)` Recorded assignments (assignmentBag: reel/frame, conveyance, assignors, assignees, recorded/execution dates) for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.assignment('17248024'); ``` #### `odp.patents.attorney` `odp.patents.attorney(applicationNumber)` Attorney/agent of record and correspondence address (recordAttorney: customer number, power of attorney, practitioners with registration numbers) for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.attorney('17248024'); ``` #### `odp.patents.continuity` `odp.patents.continuity(applicationNumber)` Continuity: parentContinuityBag (parents: continuation/divisional/CIP/provisional claims) and childContinuityBag for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.continuity('17248024'); ``` #### `odp.patents.foreignPriority` `odp.patents.foreignPriority(applicationNumber)` Foreign priority claims (foreignPriorityBag: country, application number, filing date) for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.foreignPriority('17248024'); ``` #### `odp.patents.transactions` `odp.patents.transactions(applicationNumber)` Prosecution transaction history (eventDataBag: eventCode, eventDescriptionText, eventDate) — the file-wrapper timeline for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.transactions('17248024'); ``` #### `odp.patents.documents` `odp.patents.documents(applicationNumber, { documentCodes?: string | string[], officialDateFrom?: 'YYYY-MM-DD', officialDateTo? })` List the documents in an application’s file wrapper (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’): documentBag\[] with documentIdentifier, documentCode (e.g. CTNF non-final rejection, CTFR final rejection, NOA notice of allowance, CLM claims, SPEC, ABST, REM applicant remarks, IDS), documentCodeDescriptionText, officialDate, and downloadOptionBag\[] (PDF/XML/DOCX URLs + page counts). Downloads themselves are not available in the sandbox; return the URLs. Counts against the separate 1.2M/week documents quota. ```js const r = await odp.patents.documents('17248024', { documentCodes: ['CTNF', 'CTFR', 'NOA'], }); return r.documentBag.map((d) => ({ code: d.documentCode, date: d.officialDate, desc: d.documentCodeDescriptionText, pages: d.downloadOptionBag?.[0]?.pageTotalQuantity, })); ``` #### `odp.patents.associatedDocuments` `odp.patents.associatedDocuments(applicationNumber)` Associated pre-grant publication and grant full-text documents (pgpubDocumentMetaData / grantDocumentMetaData: XML file names, product identifiers, download URIs in the bulk XML datasets) for one patent application (applicationNumber: string — ‘17248024’, ‘17/248,024’, ‘US 17/248,024’, or a PCT number like ‘PCT/US2024/012345’). Returns { count, patentFileWrapperDataBag: \[record] } with only this section populated. ```js await odp.patents.associatedDocuments('17248024'); ``` #### `odp.patents.statusCodes` `odp.patents.statusCodes({ q?, offset?, limit? } | q-string)` Look up application status codes and descriptions (statusCodeBag: applicationStatusCode, applicationStatusDescriptionText), e.g. to translate applicationMetaData.applicationStatusCode or to find the code for ‘Patented Case’ (150) or ‘Abandoned’. ```js await odp.patents.statusCodes({ q: 'applicationStatusDescriptionText:abandoned', limit: 50, }); ``` ### `odp.ptab.proceedings` #### `odp.ptab.proceedings.search` `odp.ptab.proceedings.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search PTAB AIA trial proceedings (IPR, PGR, CBM, DER): trialNumber, trialMetaData (trialTypeCode, trialStatusCategory, petitionFilingDate, institutionDecisionDate, terminationDate), patentOwnerData (patentNumber, applicationNumberText, technology center), regularPetitionerData (realPartyInInterestName, counselName). Returns { count, patentTrialProceedingDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js await odp.ptab.proceedings.search({ q: 'patentOwnerData.patentNumber:9876543', fields: [ 'trialNumber', 'trialMetaData.trialTypeCode', 'trialMetaData.trialStatusCategory', 'trialMetaData.petitionFilingDate', 'regularPetitionerData.realPartyInInterestName', ], }); ``` #### `odp.ptab.proceedings.get` `odp.ptab.proceedings.get(trialNumber)` One PTAB trial proceeding by trial number (e.g. ‘IPR2021-01599’, ‘PGR2023-00012’). Returns { patentTrialProceedingDataBag: \[record] }. ```js const t = await odp.ptab.proceedings.search({ fields: ['trialNumber'], limit: 1, }); return await odp.ptab.proceedings.get( t.patentTrialProceedingDataBag[0].trialNumber, ); ``` ### `odp.ptab.decisions` #### `odp.ptab.decisions.search` `odp.ptab.decisions.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search PTAB trial decisions (institution decisions, final written decisions, rehearing): decisionData (decisionTypeCategory, trialOutcomeCategory, decisionIssueDate, statuteAndRuleBag), documentData (documentName, documentTitleText, documentOCRText = full OCR text, fileDownloadURI), trialMetaData, patentOwnerData, regularPetitionerData. Returns { count, patentTrialDocumentDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js await odp.ptab.decisions.search({ rangeFilters: { 'decisionData.decisionIssueDate': ['2024-01-01', '2024-12-31'], }, facets: ['decisionData.trialOutcomeCategory'], fields: [ 'trialNumber', 'decisionData', 'documentData.documentTitleText', 'patentOwnerData.patentNumber', ], limit: 10, }); ``` #### `odp.ptab.decisions.get` `odp.ptab.decisions.get(documentIdentifier)` One PTAB trial decision document by documentIdentifier (from decisions.search / byTrial). Includes documentData.documentOCRText (full text). ```js const s = await odp.ptab.decisions.search({ fields: ['documentData.documentIdentifier'], limit: 1, }); const d = await odp.ptab.decisions.get( s.patentTrialDocumentDataBag[0].documentData.documentIdentifier, ); return d.patentTrialDocumentDataBag[0].documentData.documentOCRText.slice( 0, 1500, ); ``` #### `odp.ptab.decisions.byTrial` `odp.ptab.decisions.byTrial(trialNumber)` All decision documents in one PTAB trial (e.g. ‘IPR2021-01599’). Returns { count: 0, patentTrialDocumentDataBag: \[] } when the trial has no decisions yet. ```js const s = await odp.ptab.decisions.search({ fields: ['trialNumber'], limit: 1, }); const r = await odp.ptab.decisions.byTrial( s.patentTrialDocumentDataBag[0].trialNumber, ); return r.patentTrialDocumentDataBag.map((d) => ({ id: d.documentData.documentIdentifier, type: d.decisionData?.decisionTypeCategory, outcome: d.decisionData?.trialOutcomeCategory, date: d.decisionData?.decisionIssueDate, })); ``` ### `odp.ptab.documents` #### `odp.ptab.documents.search` `odp.ptab.documents.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search all PTAB trial papers and exhibits (petitions, patent owner responses, exhibits, orders): documentData (documentCategory, filingPartyCategory PETITIONER/PATENT OWNER/BOARD, documentTitleText, documentOCRText, documentFilingDate, fileDownloadURI). Returns { count, patentTrialDocumentDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js const s = await odp.ptab.proceedings.search({ fields: ['trialNumber'], limit: 1, }); return await odp.ptab.documents.search({ q: `trialNumber:${s.patentTrialProceedingDataBag[0].trialNumber}`, fields: [ 'documentData.documentIdentifier', 'documentData.documentTitleText', 'documentData.documentFilingDate', 'documentData.filingPartyCategory', ], limit: 25, }); ``` #### `odp.ptab.documents.get` `odp.ptab.documents.get(documentIdentifier)` One PTAB trial document by documentIdentifier, with documentOCRText. ```js const s = await odp.ptab.documents.search({ fields: ['documentData.documentIdentifier'], limit: 1, }); const d = await odp.ptab.documents.get( s.patentTrialDocumentDataBag[0].documentData.documentIdentifier, ); return d.patentTrialDocumentDataBag[0].documentData.documentTitleText; ``` #### `odp.ptab.documents.byTrial` `odp.ptab.documents.byTrial(trialNumber)` All papers and exhibits in one PTAB trial. Can be large (OCR text included): prefer documents.search with fields when you only need the list. ```js const s = await odp.ptab.proceedings.search({ fields: ['trialNumber'], limit: 1, }); const r = await odp.ptab.documents.byTrial( s.patentTrialProceedingDataBag[0].trialNumber, ); return r.patentTrialDocumentDataBag.map( (d) => d.documentData.documentTitleText, ); ``` ### `odp.ptab.appeals` #### `odp.ptab.appeals.search` `odp.ptab.appeals.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search PTAB ex parte appeal decisions (appeals from examiner rejections): appealNumber, appealMetaData, appellantData (applicationNumberText, patentNumber, technology center), decisionData (appealOutcomeCategory e.g. Affirmed / Reversed, decisionIssueDate, issueTypeBag e.g. ‘103’, statuteAndRuleBag), documentData (documentOCRText). Returns { count, patentAppealDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js await odp.ptab.appeals.search({ q: 'decisionData.appealOutcomeCategory:Reversed', fields: [ 'appealNumber', 'decisionData.decisionIssueDate', 'appellantData.applicationNumberText', ], sort: 'decisionData.decisionIssueDate desc', limit: 10, }); ``` #### `odp.ptab.appeals.get` `odp.ptab.appeals.get(documentIdentifier)` One PTAB appeal decision document by documentIdentifier. ```js const s = await odp.ptab.appeals.search({ fields: ['documentData.documentIdentifier'], limit: 1, }); return await odp.ptab.appeals.get( s.patentAppealDataBag[0].documentData.documentIdentifier, ); ``` #### `odp.ptab.appeals.byAppeal` `odp.ptab.appeals.byAppeal(appealNumber)` All decisions for one appeal number (e.g. ‘2023001234’). ```js const s = await odp.ptab.appeals.search({ fields: ['appealNumber'], limit: 1 }); return await odp.ptab.appeals.byAppeal(s.patentAppealDataBag[0].appealNumber); ``` ### `odp.ptab.interferences` #### `odp.ptab.interferences.search` `odp.ptab.interferences.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search PTAB interference decisions (pre-AIA priority contests): interferenceNumber, interferenceMetaData, seniorPartyData, juniorPartyData, additionalPartyDataBag, documentData. Returns { count, patentInterferenceDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js await odp.ptab.interferences.search({ fields: [ 'interferenceNumber', 'documentData.documentIdentifier', 'documentData.documentTitleText', ], limit: 10, }); ``` #### `odp.ptab.interferences.get` `odp.ptab.interferences.get(documentIdentifier)` One interference decision document by documentIdentifier. ```js const s = await odp.ptab.interferences.search({ fields: ['documentData.documentIdentifier'], limit: 1, }); return await odp.ptab.interferences.get( s.patentInterferenceDataBag[0].documentData.documentIdentifier, ); ``` #### `odp.ptab.interferences.byInterference` `odp.ptab.interferences.byInterference(interferenceNumber)` All decisions for one interference number (e.g. ‘105970’). ```js const s = await odp.ptab.interferences.search({ fields: ['interferenceNumber'], limit: 1, }); return await odp.ptab.interferences.byInterference( s.patentInterferenceDataBag[0].interferenceNumber, ); ``` ### `odp.petitions` #### `odp.petitions.search` `odp.petitions.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search final petition decisions from the Office of Petitions and Technology Centers (revival of abandoned applications, reinstated patents after late maintenance fees, delayed priority claims, make special, PTA reconsideration…): applicationNumberText, patentNumber, decisionPetitionTypeCode + decisionPetitionTypeCodeDescriptionText (what was petitioned, often with the 37 CFR rule), decidedPetitionTypeCode + decidedPetitionTypeCodeDescriptionText (outcome, e.g. GRANTED / DENIED / DISMISSED), petitionMailDate, decisionDate, decisionMailDate, finalDecidingOfficeName, technologyCenter, groupArtUnitNumber, ocrSearchText (decision text), documentBag. Returns { count, petitionDecisionDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js await odp.petitions.search({ q: 'decidedPetitionTypeCodeDescriptionText:GRANTED', rangeFilters: { decisionDate: ['2025-01-01', '2025-12-31'] }, facets: ['decisionPetitionTypeCodeDescriptionText'], fields: [ 'petitionDecisionRecordIdentifier', 'applicationNumberText', 'decisionPetitionTypeCodeDescriptionText', 'decisionDate', ], limit: 10, }); ``` #### `odp.petitions.get` `odp.petitions.get(petitionDecisionRecordIdentifier)` One petition decision by petitionDecisionRecordIdentifier (from petitions.search), including documentBag (decision documents with download URLs) and ocrSearchText. ```js const s = await odp.petitions.search({ fields: ['petitionDecisionRecordIdentifier'], limit: 1, }); const r = await odp.petitions.get( s.petitionDecisionDataBag[0].petitionDecisionRecordIdentifier, ); return r.petitionDecisionDataBag[0].decidedPetitionTypeCodeDescriptionText; ``` ### `odp.officeActions` #### `odp.officeActions.search` `odp.officeActions.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search office actions (full text) issued by examiners for public applications filed 2001+: applicationNumberText, documentCode (CTNF non-final, CTFR final, CTRS restriction, NOA…), documentCodeDescriptionText, submissionDate, groupArtUnitNumber, patentNumber, rejectionTypeBag (statute sections as strings: ‘101’, ‘102’, ‘103’, ‘112’), officeActionText, officeActionRecordIdentifier. This is the current Office Action Search API; prefer it over the legacy odp.oa.\* DSAPI endpoints. Returns { count, officeActionDataBag: \[…] }. Params: q, filters, rangeFilters, sort, fields, facets, limit, offset (see odp.syntax.search). ```js await odp.officeActions.search({ q: 'documentCode:CTNF AND rejectionTypeBag:103', fields: [ 'officeActionRecordIdentifier', 'applicationNumberText', 'submissionDate', 'rejectionTypeBag', ], sort: 'submissionDate desc', limit: 10, }); ``` #### `odp.officeActions.get` `odp.officeActions.get(officeActionRecordIdentifier)` One office action record by officeActionRecordIdentifier (from officeActions.search), including officeActionText. ```js const s = await odp.officeActions.search({ fields: ['officeActionRecordIdentifier'], limit: 1, }); return await odp.officeActions.get( s.officeActionDataBag[0].officeActionRecordIdentifier, ); ``` #### `odp.officeActions.text` `odp.officeActions.text(officeActionRecordIdentifier)` The full text of one office action as a plain string. Long: slice or search it in the sandbox and return only the relevant passages. ```js const s = await odp.officeActions.search({ q: 'rejectionTypeBag:103', fields: ['officeActionRecordIdentifier'], limit: 1, }); const t = await odp.officeActions.text( s.officeActionDataBag[0].officeActionRecordIdentifier, ); const i = t.indexOf('103'); return t.slice(Math.max(0, i - 200), i + 1500); ``` ### `odp.oa.text` #### `odp.oa.text.search` `odp.oa.text.search(criteria: Lucene/Solr query string (default '*:*'), { start?: number, rows?: 1-1000 (default 25) })` LEGACY Office Action DSAPI — office action full text, with section-level fields (e.g. bodyText, sections.\*). Returns { response: { numFound, start, docs: \[…] } }. Criteria uses this dataset’s own field names (see odp.oa.text.fields and odp.fields.oa.text); application numbers are digits only, e.g. patentApplicationNumber:16123456. ```js await odp.oa.text.search('patentApplicationNumber:16123456', { rows: 10 }); ``` #### `odp.oa.text.fields` `odp.oa.text.fields()` LEGACY DSAPI field list and dataset info for odp.oa.text.search (field names usable in criteria). ```js await odp.oa.text.fields(); ``` ### `odp.oa.citations` #### `odp.oa.citations.search` `odp.oa.citations.search(criteria: Lucene/Solr query string (default '*:*'), { start?: number, rows?: 1-1000 (default 25) })` LEGACY Office Action DSAPI — references cited by examiners in office actions (form PTO-892 and in-text citations). Returns { response: { numFound, start, docs: \[…] } }. Criteria uses this dataset’s own field names (see odp.oa.citations.fields and odp.fields.oa.citations); application numbers are digits only, e.g. patentApplicationNumber:16123456. ```js await odp.oa.citations.search('patentApplicationNumber:16123456'); ``` #### `odp.oa.citations.fields` `odp.oa.citations.fields()` LEGACY DSAPI field list and dataset info for odp.oa.citations.search (field names usable in criteria). ```js await odp.oa.citations.fields(); ``` ### `odp.oa.rejections` #### `odp.oa.rejections.search` `odp.oa.rejections.search(criteria: Lucene/Solr query string (default '*:*'), { start?: number, rows?: 1-1000 (default 25) })` LEGACY Office Action DSAPI — per-claim rejection data parsed from office actions (101/102/103/112 flags, rejected claims, action type). Returns { response: { numFound, start, docs: \[…] } }. Criteria uses this dataset’s own field names (see odp.oa.rejections.fields and odp.fields.oa.rejections); application numbers are digits only, e.g. patentApplicationNumber:16123456. ```js await odp.oa.rejections.search('hasRej103:1', { rows: 10 }); ``` #### `odp.oa.rejections.fields` `odp.oa.rejections.fields()` LEGACY DSAPI field list and dataset info for odp.oa.rejections.search (field names usable in criteria). ```js await odp.oa.rejections.fields(); ``` ### `odp.oa.enrichedCitations` #### `odp.oa.enrichedCitations.search` `odp.oa.enrichedCitations.search(criteria: Lucene/Solr query string (default '*:*'), { start?: number, rows?: 1-1000 (default 25) })` LEGACY Office Action DSAPI — enriched cited-reference metadata (cited document, relevant claims/passages, examiner vs applicant citation). Returns { response: { numFound, start, docs: \[…] } }. Criteria uses this dataset’s own field names (see odp.oa.enrichedCitations.fields and odp.fields.oa.enrichedCitations); application numbers are digits only, e.g. patentApplicationNumber:16123456. ```js await odp.oa.enrichedCitations.search('patentApplicationNumber:16123456'); ``` #### `odp.oa.enrichedCitations.fields` `odp.oa.enrichedCitations.fields()` LEGACY DSAPI field list and dataset info for odp.oa.enrichedCitations.search (field names usable in criteria). ```js await odp.oa.enrichedCitations.fields(); ``` ### `odp.bulk` #### `odp.bulk.search` `odp.bulk.search(params: { q?, filters?, rangeFilters?, sort?, fields?, facets?, limit?, offset? } | q-string)` Search the bulk dataset catalog (bulkDataProductBag\[]: productIdentifier e.g. PTGRXML patent grant full text, TRTDXFAP trademark full text, OACT office action weekly archives, plus PatentsView tables; productTitleText, productDescriptionText, productFrequencyText, date range, file counts). At most one filter and one rangeFilter (GET-only endpoint); put further conditions in q. Catalog metadata only: bulk files cannot be downloaded from the sandbox. ```js await odp.bulk.search({ q: 'patent grant full text', fields: ['productIdentifier', 'productTitleText', 'productFrequencyText'], limit: 20, }); ``` #### `odp.bulk.get` `odp.bulk.get(productIdentifier, { fileDataFromDate?, fileDataToDate?, offset?, limit?, includeFiles?: boolean, latest?: boolean })` One bulk dataset product with its file list (productFileBag.fileDataBag\[]: fileName, fileSize, fileDataFromDate/ToDate, fileReleaseDate, fileDownloadURI). Use latest: true or a date window to keep the file list small. Downloads are not available in the sandbox; return the URIs. ```js await odp.bulk.get('PTGRXML', { latest: true }); ``` ### `tsdr` #### `tsdr.status` `tsdr.status(caseId)` Trademark case status and bibliographic data as JSON ({ trademarks: \[ { status: { markElement (the mark text), status (code), extStatusDesc / tm5StatusDesc (status text), filingDate, usRegistrationNumber, … }, parties: { ownerGroups (keyed by party type code) }, gsList (goods & services by class), prosecutionHistory (events), publication, divisional, internationalData } ] }). caseId: ‘sn’ + 8-digit serial (‘sn97123456’), ‘rn’ + registration number (‘rn6123456’), ‘ref’ + Madrid reference number (‘refZ1231384’), ‘ir’ + international registration number; a bare 8-digit number is a serial number. ```js const r = await tsdr.status('sn97123456'); const t = r.trademarks[0]; return { mark: t.status.markElement, status: t.status.tm5StatusDesc, detail: t.status.extStatusDesc, filed: t.status.filingDate, classes: t.gsList?.map((g) => g.primeClassCode), }; ``` #### `tsdr.multiStatus` `tsdr.multiStatus(type: 'sn' | 'rn' | 'ref' | 'ir', ids: string[] /* 1-25 */)` Status for up to 25 trademark cases of one number type in one call (counts as one request). Returns { size, transactionList: \[ { searchId, trademarks: \[…] } ] } with the same record shape as tsdr.status. ```js await tsdr.multiStatus('sn', ['97123456', '97123457']); ``` #### `tsdr.documents` `tsdr.documents(caseId)` The trademark case’s document list (applications, office actions, responses, registration certificates, specimens) as XML text, one entry per document with its type, mail/received date, document id and page URLs. Parse with string methods / regex in the sandbox and return a summary; PDFs cannot be downloaded from the sandbox. Inspect a slice of the XML first to see the element names. ```js const xml = await tsdr.documents('sn97123456'); return xml.slice(0, 3000); ``` #### `tsdr.documentInfo` `tsdr.documentInfo(caseId, documentId)` Metadata for one document in a trademark case (XML text), e.g. page count and media types. documentId comes from tsdr.documents. ```js const xml = await tsdr.documents('sn97123456'); const id = (xml.match(/([^<]+) Inputs, results, and limits of search_api, describe_schema, and execute. The server has three tools. All three are read-only. Each result is compact JSON text, with the same object as structured content. ## search_api Searches the SDK method documentation and the response-field dictionary. | Input | Type | Notes | | ------- | ---------------- | ----------------------------------------- | | `query` | string | What you want to do, in plain words. | | `k` | integer, 1 to 50 | The number of results. The default is 10. | It returns `{ hits, note }`. Each hit has an `id`, a `description`, and a `score`. A hit for a method also has its `signature` and a ready-to-run `example`. ## describe_schema Looks up entries by name. Give exactly one of the two inputs. | Input | Type | Notes | | -------- | ------ | ---------------------------------------------------- | | `path` | string | One exact entry, for example `odp.patents.search`. | | `prefix` | string | Every entry in a namespace, for example `odp.ptab.`. | It returns `{ found: true, entries }`, or `{ found: false, message }` when nothing matches. ## execute Runs JavaScript in the sandbox, with `odp` and `tsdr` as globals. | Input | Type | Notes | | ----------- | ----------------------- | ------------------------------------------------------------------------------------- | | `code` | string | Plain JavaScript. Type annotations are rejected. Top-level `await` and `return` work. | | `timeoutMs` | integer, 100 to 120,000 | The time limit of the run. The default is 30,000. | | `memoryMb` | integer, 16 to 256 | The memory limit of the run. The default is 64. | A run that succeeds returns `{ ok: true, value, logs, durationMs }`, where `value` is what the program returned. A run that fails returns `{ ok: false, error: { name, message, status? }, logs, durationMs }` and is marked as an error, so the assistant sees what went wrong. The [SDK reference](/docs/reference/sdk/#errors) lists the error names. ### Limits of one run | What | Default limit | Past the limit | | ------------------------- | --------------------------- | -------------------------------------------------------------- | | Code | 256 KiB | The call is refused, with an argument error or `CodeTooLarge`. | | Returned value | 256 KiB | `ResultTooLarge` | | Logs | 64 KiB or 1,000 lines | No error. The logs are cut. | | Arguments of one SDK call | 64 KiB | `ArgumentsTooLarge` | | SDK calls pending at once | 16 | `TooManyPendingCalls` | | USPTO calls | 50 for `odp`, 25 for `tsdr` | `CallBudgetExceeded` | | One USPTO response | 8 MiB | `ResponseTooLarge` | A self-hosted server can change the last two limits. See [every setting](https://github.com/blen-labs/uspto-mcp-server/blob/main/.env.example). # Security > What the sandbox allows, where keys live, and how to report a vulnerability. The server runs code that a model wrote, and it treats that code as untrusted. ## The sandbox * **No access to your computer.** A program has no network, file system, environment, or subprocess access. * **A check before the run.** The server parses each program and rejects imports, `eval`, and references to host globals. * **An isolated runtime.** The program runs in a fresh V8 isolate, or in a separate Deno process with no permissions. With sign-in, the server uses the Deno process only. * **A deadline that the server owns.** The server stops a run that passes its time limit. * **One way out.** A program reaches USPTO only through the registered read methods of the `odp` and `tsdr` SDK. ## Keys * Keys stay in the server process. The server never passes them into the sandbox. * If USPTO echoes a key back, the server replaces it with `[REDACTED]` in results and errors. * In account mode, one person’s key never serves another person’s calls. ## What the server does not do * It does not change anything at USPTO. All three tools are read-only. * It does not download document PDFs or bulk files. The SDK returns their URLs. ## Report a vulnerability Do not open a public issue. Open a [private security advisory](https://github.com/blen-labs/uspto-mcp-server/security/advisories/new). The full policy and the threat model are in [SECURITY.md](https://github.com/blen-labs/uspto-mcp-server/blob/main/SECURITY.md). # Self-host > Run the server's HTTP transport for yourself or for other people, and where the full guides are. Remote clients such as ChatGPT, Claude custom connectors, and Gemini Enterprise need an HTTPS endpoint. The server has a Streamable HTTP transport for that. Pick the mode by who uses it. | Mode | Who it serves | Whose keys | How to start it | | ------------ | --------------------- | ----------------- | -------------------------------------------- | | Local | You, on your computer | Yours | `--http --insecure` | | Single owner | You, from anywhere | Yours | `--http` with an OIDC provider | | Accounts | Many people | Each person’s own | `--http` with `USPTO_AUTH_PROVIDER=accounts` | USPTO keys are personal. The single-owner mode answers every token holder with the server’s own keys, so use it only for yourself. To host for other people, use account mode. ## Local ```bash USPTO_API_KEY=... npx @blen/uspto-mcp-server --http --insecure --port 8080 ``` There is no sign-in. The server binds to `127.0.0.1` unless `HOST` or `--host` names another address. ## Single owner ```bash USPTO_API_KEY=... \ USPTO_AUTH_PROVIDER=clerk \ USPTO_AUTH_ISSUER=https://.clerk.accounts.dev \ USPTO_AUTH_AUDIENCE=https://your-host.example.com/mcp \ USPTO_AUTH_JWKS_URL=https://.clerk.accounts.dev/.well-known/jwks.json \ USPTO_PUBLIC_ORIGIN=https://your-host.example.com \ npx @blen/uspto-mcp-server --http ``` The issuer, the audience, and an HTTPS JWKS URL are all required. The provider can be `clerk`, `workos`, `auth0`, or `generic-oidc`. Then give your client the URL `https://your-host.example.com/mcp`. ## Accounts Account mode adds Google sign-in, an account page where each person saves their own keys, and OAuth for MCP clients. The keys are encrypted in PostgreSQL. See the [account mode guide](https://github.com/blen-labs/uspto-mcp-server/blob/main/docs/accounts.md). ## Rules for every deployment * **Run one replica.** The queue for each key is in memory. Two instances that share a key look like concurrent clients to USPTO. * **Sign-in is required.** `--http` refuses to start without `--insecure` or a configured provider. * **Install Deno.** With sign-in, the server runs each program in a separate Deno process, and `execute` is unavailable without it. * **Name your host.** To listen on an address that is not loopback, set `USPTO_PUBLIC_ORIGIN` or `USPTO_ALLOWED_HOSTS`. ## Full guides These documents are in the repository: * [Architecture](https://github.com/blen-labs/uspto-mcp-server/blob/main/docs/architecture.md) * [Account mode](https://github.com/blen-labs/uspto-mcp-server/blob/main/docs/accounts.md) * [Railway walkthrough](https://github.com/blen-labs/uspto-mcp-server/blob/main/deploy/RAILWAY.md) * [Every setting](https://github.com/blen-labs/uspto-mcp-server/blob/main/.env.example)