Trademark API Reference

Overview

This is the endpoint reference for the Goalie IP USPTO trademark API — structured access to a continuously-refreshed copy of the USPTO trademark dataset, the same data that powers our search tools. Query by mark name, owner, status, international class, serial number, and more. New here? The product overview has a feature summary, TSDR comparison, and pricing.

Why this API vs. USPTO TSDR

The USPTO TSDR API returns one record at a time by serial or registration number — there is no way to search by mark text, owner, or class. The Goalie IP API adds full-text, exact, and fuzzy mark search with filtering and pagination across the entire dataset, returning clean JSON built for application use.

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Keys are created and managed in your portal.

Authorization: Bearer gip_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are prefixed with gip_live_ and are 41 characters total. The Bearer prefix is recommended but optional — a bare Authorization: gip_live_… is also accepted, because some directories and clients forward an API-key field verbatim without a scheme. Keep them secret — they are shown only once at creation. You can create up to 5 active keys per account.

Quick start

Search for all active registrations of a mark in a specific class:

curl -X POST https://www.goalieip.com/api/v1/trademarks/search \
  -H "Authorization: Bearer gip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "markLiteral": "ACME",
    "markLiteralMode": "exact",
    "currentStatusCode": ["700", "800"],
    "internationalClasses": ["025"],
    "page": 1,
    "pageSize": 25
  }'

Look up a specific trademark by serial number:

curl https://www.goalieip.com/api/v1/trademarks/97123456 \
  -H "Authorization: Bearer gip_live_your_key_here"

MCP server (for AI agents)

The same trademark data is available over the Model Context Protocol, so an AI agent can search the US federal register directly — no HTTP client to write and no schema to teach it. See the trademark MCP server overview for how it compares to a TSDR lookup. It is included with every API plan at no extra cost and uses the same key and the same monthly quota as the REST endpoints.

Connect on claude.ai or ChatGPT (OAuth — one click)

In claude.ai (or ChatGPT), add a custom connector and paste the server URL https://www.goalieip.com/api/mcp. You'll be sent to GoalieIP to sign in and approve access — no API key to copy and no config file to edit. The connector then searches on your behalf, with usage counting against your account's plan and quota. Revoke access anytime from your portal.

New here? Create a free account first, then click the link in the verification email — an unverified account is refused at the approval step. OAuth connections start on the free tier (200 calls/month) and inherit your plan's limits when you upgrade. For editors and scripts that take a static token, the API-key methods below are simpler.

Claude Code

claude mcp add --transport http goalieip \
  https://www.goalieip.com/api/mcp \
  --header "Authorization: Bearer gip_live_your_key_here"

Claude API MCP connector (for your own code — not the Claude Desktop app, which is below)

Use this only when your own program calls the Anthropic Messages API and you want Claude to reach our trademark tools while it answers. Anthropic makes the connection to our server for you — there is no config file to edit and nothing to install locally. The request needs three things together: the mcp-client-2025-11-20 beta header, an mcp_servers entry, and a matching mcp_toolset in tools (the API rejects the call if the toolset is missing).

import anthropic

client = anthropic.Anthropic()  # your ANTHROPIC_API_KEY

message = client.beta.messages.create(
    model="claude-opus-4-5",  # or any current Claude model
    max_tokens=1024,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://www.goalieip.com/api/mcp",
            "name": "goalieip",
            "authorization_token": "gip_live_your_key_here",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "goalieip"}],
    messages=[
        {"role": "user", "content": "Find live trademarks for GOALIE in class 25."}
    ],
)

Two different keys are in play: your Anthropic API key authenticates the call to Anthropic, and your GoalieIP key (gip_live_…) goes in authorization_token so Anthropic can reach our server on your behalf. This is a request from code — not a snippet to paste into any desktop or client config file.

Any MCP client (generic config)

{
  "mcpServers": {
    "goalieip": {
      "type": "http",
      "url": "https://www.goalieip.com/api/mcp",
      "headers": {
        "Authorization": "Bearer gip_live_your_key_here"
      }
    }
  }
}

Claude Desktop

Claude Desktop's Add connector screen only accepts OAuth — it has no field for an API key — so a direct URL connection won't work yet. Connect instead through a small local bridge (mcp-remote) that attaches your key for you. It runs automatically; you only edit one config file. Two steps trip most people up, so follow these in order.

1. Find the config file

The reliable way: in Claude Desktop open Settings → Developer → Edit Config. That opens the exact file (creating it if it doesn't exist). To locate it by hand instead:

Windows:  %APPDATA%\Claude\claude_desktop_config.json
macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows, paste that path into the File Explorer address bar. Turn on View → File name extensions first, so your editor can't silently save it as .json.txt — Claude only reads the exact .json.

3. Paste the configuration and save

Replace the file's contents with this, using a key from your portal:

{
  "mcpServers": {
    "goalieip": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote@latest",
        "https://www.goalieip.com/api/mcp",
        "--header", "Authorization: Bearer gip_live_your_key_here"
      ]
    }
  }
}

Works on macOS and Windows as written; the bridge needs Node.js installed. Prefer to keep your key out of the file? Put it in an env block and reference it: add "env": { "GOALIE_KEY": "gip_live_…" } and change the header value to Authorization: Bearer ${GOALIE_KEY}.

4. Reopen Claude Desktop

Start it again and give it a few seconds — the first launch downloads the bridge. goalieip then appears under Settings → Developer, and the two tools are available in a new chat.

Troubleshooting connections

The server answers both protocol revisions on the same URL and selects per request, so there is nothing to configure either way. Verified clients: Claude Code, the Claude API MCP connector, and Claude Desktop (via the bridge above). If your client cannot reach a remote Streamable HTTP server at all, that is a client limitation rather than a server setting — tell us which one and we will test it.

How results differ from the REST API

Tool results are read into a model's context window, so search_trademarks returns a compact summary of each match — serial number, mark, owner, status, filing and registration dates, classes, and the opening of the goods/services text — rather than the full record. Page size defaults to 10 and is capped at 15. Call get_trademark with a serial number for the complete record, including the full goods/services text, owner details, status history, and classifications. The REST API is unchanged and still returns full records at up to 500 per page.

Every search must include at least one narrowing filter — markLiteral, ownerName, serialNumber, registrationNumber, goodsAndServices, or one of the other text filters. Class, status, and date filters alone match too much of the register to run. When a query is rejected or times out, the tool returns a message naming the parameter to change, so an agent can correct itself and retry.

Each tool call counts as one API call against your monthly quota, and the same per-tier burst limits apply. Note that agents typically make several tool calls per question, so MCP usage consumes quota faster than a scripted integration. Coverage is US federal (USPTO) data only — see the FAQ.

Code examples

Common recipes in Python and Node.js. Each call returns JSON; replace gip_live_your_key_here with a key from your portal.

Exact mark query (Python)

import requests

resp = requests.post(
    "https://www.goalieip.com/api/v1/trademarks/search",
    headers={"Authorization": "Bearer gip_live_your_key_here"},
    json={
        "markLiteral": "ACME",
        "markLiteralMode": "exact",
        "currentStatusCode": ["700", "800"],  # live / registered
        "page": 1,
        "pageSize": 25,
    },
)
data = resp.json()
print(data["meta"]["total"], "matches")
for tm in data["data"]:
    print(tm["serialNumber"], tm["markLiteral"], tm["currentStatusCode"])

Serial-number status as JSON (Node.js)

const res = await fetch(
  "https://www.goalieip.com/api/v1/trademarks/97123456",
  { headers: { Authorization: "Bearer gip_live_your_key_here" } }
);
const { data } = await res.json();
console.log(data.markLiteral, "→", data.currentStatusCode, data.currentStatusDate);

Fuzzy mark-literal search (curl)

Find confusingly similar marks using trigram matching — useful for clearance and watch workflows.

curl -X POST https://www.goalieip.com/api/v1/trademarks/search \
  -H "Authorization: Bearer gip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "markLiteral": "Kodak", "markLiteralMode": "fuzzy", "pageSize": 50 }'

Search by owner and class (Python)

resp = requests.post(
    "https://www.goalieip.com/api/v1/trademarks/search",
    headers={"Authorization": "Bearer gip_live_your_key_here"},
    json={
        "ownerName": "Nike, Inc.",
        "internationalClasses": ["025", "035"],
        "filingDateFrom": "2020-01-01",
        "sortField": "filingDate",
        "sortDir": "desc",
    },
)
print(resp.json()["meta"]["total"], "marks")

Pseudo-mark search (curl)

The pseudo mark is the USPTO's normalized spelling of a stylized or intentionally misspelled mark — searching it finds phonetic equivalents that a literal search misses (e.g. "KWIK" filings via "QUICK").

curl -X POST https://www.goalieip.com/api/v1/trademarks/search \
  -H "Authorization: Bearer gip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "pseudoMark": "QUICK", "currentStatusCode": ["700", "800"] }'

Design search code lookup (curl)

Find marks by their figurative elements using USPTO design search codes (dots optional).

curl -X POST https://www.goalieip.com/api/v1/trademarks/search \
  -H "Authorization: Bearer gip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "designSearchCodes": ["05.03.10"], "internationalClasses": ["025"] }'

Full-text goods/services search (curl)

Use goodsAndServicesMode: "words" for whole-word full-text matching with stemming — far faster than contains for common terms, and supports OR and -exclusion. Results come back newest-first.

curl -X POST https://www.goalieip.com/api/v1/trademarks/search \
  -H "Authorization: Bearer gip_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "goodsAndServices": "software -mobile", "goodsAndServicesMode": "words" }'

POST/api/v1/trademarks/search

Search and filter the trademark database. Returns a paginated list of matching records. Every request must include at least one narrowing filter — one of markLiteral, ownerName, attorneyName, serialNumber, registrationNumber, goodsAndServices, pseudoMark, translation, transliteration, disclaimer, markDescription, or designSearchCodes. All other filters (class, status, dates, correspondence, and administrative fields) narrow results further but cannot be used on their own (a query with none of the above returns 400). Results are sorted by filing date descending unless sortField is set.

Request

POST /api/v1/trademarks/search
Authorization: Bearer gip_live_...
Content-Type: application/json

{
  "markLiteral": "NIKE",
  "markLiteralMode": "exact",
  "ownerName": "Nike, Inc.",
  "currentStatusCode": ["700", "800"],
  "internationalClasses": ["025", "035"],
  "filingDateFrom": "2020-01-01",
  "page": 1,
  "pageSize": 25
}

Response

{
  "data": [
    {
      "serialNumber": "97123456",
      "registrationNumber": "6789012",
      "markLiteral": "NIKE",
      "ownerName": "Nike, Inc.",
      "currentStatusCode": "700",
      "currentStatusDate": "2022-03-15T00:00:00.000Z",
      "filingDate": "2021-06-01T00:00:00.000Z",
      "internationalClasses": ["025"],
      "goodsAndServices": "Athletic footwear and apparel",
      ...
    }
  ],
  "meta": {
    "total": 61,
    "totalIsCapped": false,
    "page": 1,
    "pageSize": 25,
    "callsUsed": 1,
    "callsRemaining": 4999
  }
}

meta.total is exact up to 10,000 matches. Broader queries return "total": 10000, "totalIsCapped": true — read it as "10,000+". Pagination past the cap still works: keep requesting pages until one comes back with fewer than pageSize records.

GET/api/v1/trademarks/{serialNumber}

Retrieve a single trademark record by its USPTO serial number. Returns the full record or 404 if not found.

GET /api/v1/trademarks/97123456
Authorization: Bearer gip_live_...

Response

{
  "data": {
    "serialNumber": "97123456",
    "registrationNumber": "6789012",
    "markLiteral": "NIKE",
    ...
  },
  "meta": {
    "callsUsed": 2,
    "callsRemaining": 4998
  }
}

Search parameters

At least one narrowing filter is required (see above); all other fields are optional. Combining multiple fields narrows results (AND logic).

Substring filters (any field described as "substring match") require at least 3 characters — shorter patterns cannot use the search indexes and are rejected with a 400. The one exception is markLiteral with markLiteralMode: "exact", which accepts short marks like "3M".

Mark filters

Statement filters

Owner & attorney filters

Classification & goods filters

Status & identifier filters

Administrative filters

Date range filters

Pagination & sorting

Response fields

Each record in data[] contains the following fields.

headerFlags

Boolean attributes of the application. Commonly useful flags:

meta

Status codes

The currentStatusCode field uses USPTO internal codes. The most commonly encountered codes by category:

To filter for all live registered marks, pass "currentStatusCode": ["700", "701", "702", "703", "704", "705", "800"].

Drawing codes

The markDrawingCode field indicates the form of the mark drawing submitted to the USPTO.

To find only word marks (no design element), filter for markDrawingCode: "4" (standard characters) or "1" (typed drawing).

Error responses

Errors return a JSON body with an error string and the appropriate HTTP status code.

{ "error": "Monthly call quota of 5000 calls exceeded. Upgrade at https://goalieip.com/subscribe" }

Rate limits

Two limits apply. The monthly quota is enforced at the account level — all API keys on the same account share one monthly pool, and MCP tool calls draw from that same pool as REST requests. It resets on the 1st of each calendar month. A separate short-window burst limit caps how many requests a single key may make in a rolling 10-second window, protecting shared capacity; the REST endpoints and the MCP server each apply that ceiling independently, and paid tiers are far more generous.

Exceeding the burst limit returns 429 with a Retry-After header (seconds) plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Back off and retry after the indicated delay. Burst-limited requests do not count against your monthly quota.

How overage works

Going past your included calls does not switch your API off. On a paid plan, additional calls keep working and are billed at your plan's overage rate, charged to the card on file once the billing period closes — separately from your subscription. You'll get an email receipt itemising the calls and the amount.

We email you at 80% of your allowance and again when you reach it, so overage is never a surprise. If you are regularly exceeding your plan, the next tier up costs less than the overage — that is deliberate, and the notices say so.

Overage is capped at 3× your plan's included calls, after which requests return 429. The cap exists so a misconfigured client or a looping agent cannot run up an unbounded charge; if you need it raised, contact us and we will lift it or move you to a plan that fits.

The free tier does not have overage. It stops at 200 calls and resumes at the start of the next month.

Every response includes meta.callsUsed and meta.callsRemaining so you can monitor consumption in your application. Upgrade your plan →

Frequently asked questions

Ready to build? View API plans and get a key →