# patent-api for agents

You are an AI agent. This page tells you how to get an API key, get it funded by your human, and query
the status of any US patent application. No human is needed except to pay. Replace `<PUBLIC_BASE_URL>` with
the origin this page was served from.

What you get: for every US patent application — is it pending, rejected, allowed, abandoned, granted; the
transaction timeline; who owns it (assignments); PTAB challenges; maintenance fees / is the patent alive;
and resolved entity ids for companies and inventors. Built from USPTO's public-domain bulk data, served from
our own copy. Every response carries `source` (the USPTO product and file date) and `as_of`.

**No seats, redistribution allowed, no AI-use restrictions.** Cache it, embed it, store it in a vector
database, resell it inside your product. Pay per request only.

## 1. Sign up (needs your owner's real email)

```bash
curl -s -X POST <PUBLIC_BASE_URL>/agent/signup \
  -H 'Content-Type: application/json' \
  -d '{"owner_email": "owner@example.com", "agent_name": "my-patent-watcher"}'
```

```json
{"api_key": "pk_live_...", "org_id": "org_...", "note": "save this now; not shown again"}
```

Save `api_key` immediately: it is never shown again. Your owner receives an email saying an agent enrolled
under their address (the email never contains the key). Rules:

- Lost the key before funding? Call signup again with the same email: the old key is revoked and a new one
  is minted.
- Once the org has ever been funded, signup with that email returns `409 {"error": "org_exists"}`. Mint more
  keys with `POST /keys` (step 5) using a key you still have.

## 2. You will get a 402 until funded

Any data request on an unfunded key returns:

```json
{"error": "payment_required", "checkout": "POST /agent/checkout-link", "minimum_usd": 20}
```

This is the onboarding flow, not a failure. Go to step 3.

## 3. Get a checkout link and hand it to your human

```bash
curl -s -X POST <PUBLIC_BASE_URL>/agent/checkout-link \
  -H 'Content-Type: application/json' -H 'X-API-KEY: pk_live_...' \
  -d '{"amount_usd": 20}'
```

```json
{"url": "https://checkout.stripe.com/c/pay/cs_...", "expires_at": "2026-09-14T17:00:00+00:00"}
```

Give `url` to your owner. They pay on Stripe's hosted page, no login. Credits land on your key within
seconds of the payment confirming. Poll `GET /agent/me` until `balance_units` is positive. Whole dollars,
minimum 20; the link expires after 24 hours, just request another.

If the service answers `503 {"error": "billing_not_configured"}`, billing is not enabled on this deployment
yet; tell your owner.

## 4. Query

```bash
curl -s <PUBLIC_BASE_URL>/v1/applications/17123456 -H 'X-API-KEY: pk_live_...'
```

Every successful data request costs 1 unit. List endpoints cost 1 unit per 100 rows returned. See
`<PUBLIC_BASE_URL>/openapi.json` for all endpoints.

## 5. Manage your org

```bash
# who am I, what is my balance, which keys exist
curl -s <PUBLIC_BASE_URL>/agent/me -H 'X-API-KEY: pk_live_...'
# mint another key on the same balance (e.g. one per deployment)
curl -s -X POST <PUBLIC_BASE_URL>/keys -H 'Content-Type: application/json' -H 'X-API-KEY: pk_live_...' \
  -d '{"name": "ci"}'
```

`GET /agent/me` returns `{"org_id", "owner_email", "balance_units", "keys": [{"key_id", "prefix", "name", "created_at"}]}`.
Any key under the org can top up the balance with `POST /agent/checkout-link`.

## Pricing

| Plan    | Price              | Requests            | Notes                                      |
| ------- | ------------------ | ------------------- | ------------------------------------------ |
| Credits | $20 one-time       | 1,000 ($0.02/req)   | No expiry. Buy any whole-dollar amount ≥ $20. |
| Build   | $200/mo            | 100,000             | Contact us (v0).                           |
| Scale   | $2,000/mo          | 1,000,000           | Contact us (v0). Webhooks included, SLA.   |

No seats, redistribution allowed, no AI-use restrictions.

## MCP

The same data is exposed as MCP tools (streamable HTTP) at `<PUBLIC_BASE_URL>/mcp`; authenticate with
your API key as the bearer token.

```bash
claude mcp add --transport http patent-status <PUBLIC_BASE_URL>/mcp
```

## Errors you will see

| Status | `error`                  | What to do                                                   |
| ------ | ------------------------ | ------------------------------------------------------------ |
| 401    | `invalid_api_key`        | Missing, revoked, or mistyped `X-API-KEY`. Sign up again if unfunded. |
| 402    | `payment_required`       | Request a checkout link (step 3).                            |
| 400    | `amount_below_minimum`   | Ask for at least `minimum_usd`.                              |
| 409    | `org_exists`             | Email already owns a funded org; use `POST /keys` with an existing key. |
| 503    | `billing_not_configured` | Deployment has no Stripe keys; tell your owner.              |

Source data: USPTO Open Data Portal bulk products (US government work, public domain). We cite USPTO; cite us.