Appearance
List patent offices and their requirements
GET /api/v2/external/patent-officesAuthentication: x-api-key header, with the patents:read scope. See Authentication and limits.
Paginated list of the patent offices Renewr manages, each with the fields it requires before a patent can be managed (requiredFields) and the fields whose change on an existing patent is staged for review (stagedFields). Office-code order by default; sort with ?sort=office (ascending) or ?sort=-office (descending). Unknown sort 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: office. |
Response
200 A page of patent offices with the standard v2 list envelope { pagination, data }.
json
{
"pagination": {
"totalItems": 128,
"currentPage": 1,
"itemsPerPage": 10,
"totalPages": 13,
"hasMore": true
},
"data": [
{
"object": "patentOffice",
"office": "EP",
"requiredFields": [
"office",
"patentType",
"filingRoute",
"applicationNumber",
"applicationDate",
"applicantType"
],
"stagedFields": [
"office",
"filingRoute",
"patentType",
"status",
"applicationDate",
"publicationDate",
"grantDate",
"lapseDate",
"expirationDate",
"extendedExpirationDate",
"nationalPhaseEntryDate",
"renewalsManagedFrom",
"applicationNumber",
"publicationNumber",
"grantPublicationNumber",
"pctApplicationNumber"
]
}
]
}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: patentOffice. |
data[].office | string | Patent office / authority code (WO, EP, EA, or an ISO 3166-1 national office code). |
data[].requiredFields | array of string | Fields this office needs before a patent can be managed. Declarative: a creation is rejected only when it lacks office, patentType, applicationNumber or applicationDate; any other listed field may be missing, the item is still accepted and staged, and the reviewer completes it. |
data[].stagedFields | array of string | Fields whose change on an existing patent is staged for review instead of being applied. Applies to updates only: a creation is always staged. The four patent numbers (applicationNumber, publicationNumber, grantPublicationNumber, pctApplicationNumber) are always in this list. |
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/patent-offices?itemsPerPage=50" \
-H "x-api-key: $RENEWR_API_KEY"