Beginning on October 2, 2020, you will need an API key to access the TSDR REST API See https://account.uspto.gov/api-manager and the uspto's TSDR Data API webpage for more information on retrieving bulk data.
Click on the Authorize box and enter your api key. It is required and will be sent on all requests.
This uses the uspto's swagger object with a number of changes. The uspto's api does not allow browser request (CORS issues) so requests from this page will not actually work. The generated curl commands will work and the modified swagger object can be imported into postman.
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export TSDR_APIKEY_HEADER="<paste-your-key>"
You can also persist this in your config file at ~/.config/tsdr-pp-cli/config.toml.
3. Verify Setup
uspto-tsdr-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
uspto-tsdr-pp-cli case-multi-status --ids example-value
Unique Features
These capabilities aren't available in any other tool for this API.
Trademark intelligence
-
trademark status — Full current state of a trademark in one command — mark text, status, owner, classes, filing/registration dates, attorney, and prosecution event count
Agents evaluating trademark status need the complete picture in one call instead of parsing XML manually
uspto-tsdr-pp-cli trademark status 97123456 --json
-
trademark timeline — Every prosecution event in chronological order — office actions, examiner reviews, publication events, and registration milestones
Trademark attorneys need the full event history to evaluate prosecution strength and identify potential issues
uspto-tsdr-pp-cli trademark timeline 97123456 --json
-
trademark docs — List all documents in the prosecution file — office actions, responses, specimens, registration certificates — with type and date filtering
Litigation prep and due diligence require reviewing every document in a trademark file without clicking through the TSDR web UI
uspto-tsdr-pp-cli trademark docs 97123456 --filter-type SPE --json
Portfolio management
-
trademark deadlines — Calculate Section 8, 9, and 15 maintenance deadlines with window-open dates and days-away countdown
Missing a maintenance deadline means losing the registration — this is the #1 pain point for trademark portfolio managers
uspto-tsdr-pp-cli trademark deadlines 97123456 --json
-
trademark watch — Monitor multiple trademarks for status changes — caches previous statuses locally and flags any changes since last check
Agents monitoring trademark portfolios need change detection, not full status dumps they have to diff themselves
uspto-tsdr-pp-cli trademark watch 97123456 97654321 --json
-
trademark batch — Batch status lookup for multiple trademarks using the multi-case endpoint or individual fallback with rate-limit throttling
IP paralegals managing hundreds of marks need batch status without manually checking each one
uspto-tsdr-pp-cli trademark batch 97123456 97654321 --json
Usage
Run uspto-tsdr-pp-cli --help for the full command reference and flag list.
Commands
case-multi-status
Manage case multi status
casedoc
Manage casedoc
casedocs
Manage casedocs
Note: exactly one of rn,sn,ref,ir must be specified, like sn in the examples
Note: exactly one of rn,sn,ref,ir must be specified, like sn or ir in the examples
Note: only one parameter can be specified, like sn in the example
casestatus
Manage casestatus
raw-image
Manage raw image
Output Formats
# Human-readable table (default in terminal, JSON when piped)
uspto-tsdr-pp-cli case-multi-status --ids example-value
# JSON for scripting and agents
uspto-tsdr-pp-cli case-multi-status --ids example-value --json
# Filter to specific fields
uspto-tsdr-pp-cli case-multi-status --ids example-value --json --select id,name,status
# Dry run — show the request without sending
uspto-tsdr-pp-cli case-multi-status --ids example-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
uspto-tsdr-pp-cli case-multi-status --ids example-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
uspto-tsdr-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/tsdr-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
TSDR_APIKEY_HEADER | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
uspto-tsdr-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $TSDR_APIKEY_HEADER
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
HTTP Transport
This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
Generated by CLI Printing Press