List patents

GET /api/v2/external/patents

Authentication: x-api-key header, with the patents:read scope. See Authentication and limits.

Paginated list of the patents owned by the authenticated client. Use itemsPerPage and currentPage for pagination (server cap: 100 / page). Filter by your own reference with ?providerId= (exact match). Sort with ?sort=field (ascending) or ?sort=-field (descending) over the external field names clientCaseReference, office, applicationDate, publicationNumber, status (unknown fields are rejected with 400).

Query parameters

Name	Type	Required	Description
`itemsPerPage`	number	No	Number of items per page. Default 10; values above 100 are silently clamped to 100 (hard server cap, spec §6.1).
`currentPage`	number	No	Current page (1-based). Offset pagination: a page can shift if the collection mutates between calls; re-fetch from page 1 for a consistent sweep.
`sort`	string	No	Sort field expressed as `field` (ASC) or `-field` (DESC). Allowed fields: clientCaseReference, office, applicationDate, publicationNumber, status.
`providerId`	string	No	Exact-match filter on your own client-side reference (provider id). Returns at most one patent.

Response

200 A page of patents with the standard v2 list envelope { pagination, data }.

json

{
  "pagination": {
    "totalItems": 128,
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalPages": 13,
    "hasMore": true
  },
  "data": [
    {
      "object": "patent",
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "providerId": "ACME-2021-0042",
      "clientCaseReference": "P-2021-0042-EP",
      "clientFamilyReference": "FAM-0042",
      "title": "Heat exchanger with corrugated fins",
      "office": "EP",
      "patentType": "PATENT",
      "applicationNumber": "21305432.1",
      "applicationDate": "2021-04-02",
      "nationalPhaseEntryDate": null,
      "priorityDate": "2020-04-03",
      "publicationNumber": "EP3891234A1",
      "publicationDate": "2022-10-05",
      "grantPublicationNumber": "EP3891234B1",
      "grantDate": "2024-03-13",
      "pctApplicationNumber": "PCT/EP2021/059012",
      "officialNumbers": {
        "applicationNumber": "21305432.1",
        "publicationNumber": "EP3891234A1",
        "grantPublicationNumber": "EP3891234B1",
        "pctApplicationNumber": "PCT/EP2021/059012"
      },
      "expirationDate": "2041-04-02",
      "extendedExpirationDate": null,
      "lapseDate": null,
      "renewalsManagedFrom": "2021-04-02",
      "status": "GRANTED",
      "filingRoute": "EP",
      "applicantType": "LARGE",
      "claimCount": 15,
      "designatedCountries": [
        "DE",
        "FR",
        "GB",
        "IT"
      ],
      "owner": "Acme Industries SA",
      "secondaryOwners": [],
      "subCase": null,
      "createdAt": "2026-01-10T08:30:00.000Z",
      "updatedAt": "2026-07-15T14:00:00.000Z"
    }
  ]
}

Response fields

Field	Type	Description
`pagination`	object	Pagination metadata.
`pagination.totalItems`	integer	Total number of items across all pages.
`pagination.currentPage`	integer	1-based index of the current page.
`pagination.itemsPerPage`	integer	Number of items per page (server cap: 100).
`pagination.totalPages`	integer	Total number of pages.
`pagination.hasMore`	boolean	True when another page exists after the current one.
`data`	array of objects	Page of results.
`data[].object`	string	String describing the object type (auto-description). One of: `patent`.
`data[].id`	string	Opaque, stable Renewr UUID of the patent. Format: `uuid`.
`data[].providerId`	string or null	Client-provided matching reference; searchable via ?providerId=.
`data[].clientCaseReference`	string or null	Case reference on the client side.
`data[].clientFamilyReference`	string or null	Family reference on the client side.
`data[].title`	string or null	Title of the patent.
`data[].office`	string	Patent office / authority code (WO, EP, EA, or an ISO 3166-1 national office code).
`data[].patentType`	string or null	One of: `PATENT`, `UTILITY`, `DESIGN`.
`data[].applicationNumber`	string or null	Application (filing) number, as recorded in your portfolio (no normalization applied); the office-standard form lives in officialNumbers.
`data[].applicationDate`	string or null	ISO date string.
`data[].nationalPhaseEntryDate`	string or null	ISO date string.
`data[].priorityDate`	string or null	ISO date string.
`data[].publicationNumber`	string or null	Publication number, as recorded in your portfolio.
`data[].publicationDate`	string or null	ISO date string.
`data[].grantPublicationNumber`	string or null	Grant publication number, as recorded in your portfolio.
`data[].grantDate`	string or null	ISO date string.
`data[].pctApplicationNumber`	string or null	PCT application number, as recorded in your portfolio.
`data[].officialNumbers`	object	Office-standard numbers maintained by Renewr operators (the form required by the IP offices, used for official payments). Read-only: not writable via sync.
`data[].officialNumbers.applicationNumber`	string or null	Office-standard application (filing) number.
`data[].officialNumbers.publicationNumber`	string or null	Office-standard publication number.
`data[].officialNumbers.grantPublicationNumber`	string or null	Office-standard grant publication number.
`data[].officialNumbers.pctApplicationNumber`	string or null	Office-standard PCT application number.
`data[].expirationDate`	string or null	ISO date string.
`data[].extendedExpirationDate`	string or null	ISO date string.
`data[].lapseDate`	string or null	ISO date string.
`data[].renewalsManagedFrom`	string or null	ISO date string.
`data[].status`	string or null	Shared IP right status. One of: `PENDING`, `PUBLISHED`, `GRANTED`, `LAPSED`.
`data[].filingRoute`	string or null	How the title was filed. One of: `NATIONAL`, `PCT`, `EP`, `EA`, `DIVISIONAL`.
`data[].applicantType`	string or null	One of: `MICRO`, `SMALL`, `LARGE`.
`data[].claimCount`	integer or null	Number of claims.
`data[].designatedCountries`	array of string or null	ISO 3166-1 alpha-2 designations (EP/regional).
`data[].owner`	string or null	Owner (display).
`data[].secondaryOwners`	array of string or null	Co-owners.
`data[].subCase`	string or null	Sub-case.
`data[].createdAt`	string or null	ISO 8601 timestamp (UTC). Format: `date-time`.
`data[].updatedAt`	string or null	ISO 8601 timestamp (UTC). Format: `date-time`.

Errors

Errors use the application/problem+json envelope with stable machine-readable codes. See the Errors guide.

Status	Description
400	Validation failed (`validation_failed`): carries per-field `errors[]` with RFC 6901 JSON Pointers.
401	Missing or invalid API key (`invalid_api_key`), or expired key (`api_key_expired`).
403	API key lacks the required scope (`insufficient_scope`, with `requiredScope` extension) or the operation is not enabled for this client (`forbidden`).
429	Daily API call limit exceeded (`rate_limit_exceeded`): the `Retry-After` header gives the seconds until reset.

Example request

bash

curl "https://api.renewr.example/api/v2/external/patents?itemsPerPage=10&currentPage=1" \
  -H "x-api-key: $RENEWR_API_KEY"

List patents ​

Query parameters ​

Response ​

Errors ​

Example request ​

List patents

Query parameters

Response

Errors

Example request