OA Actions Client

clients.oa_actions - Client for USPTO Office Action Text Retrieval API.

This module provides a client for interacting with the USPTO Office Action Text Retrieval API (v1). It allows users to search for full-text office action documents issued during patent examination, including body text and structured section data for rejections and allowances.

class pyUSPTO.clients.oa_actions.OAActionsClient(config=None, base_url=None)[source]

Bases: BaseUSPTOClient[OAActionsResponse]

Client for interacting with the USPTO Office Action Text Retrieval API.

This client provides methods to search for full-text office action documents. The API refreshes daily and contains publicly available Office Actions starting with 12 series applications.

ENDPOINTS = {'get_fields': 'api/v1/patent/oa/oa_actions/v1/fields', 'search': 'api/v1/patent/oa/oa_actions/v1/records'}
__init__(config=None, base_url=None)[source]

Initialize the OAActionsClient.

Parameters:

  • config (USPTOConfig | None) – USPTOConfig instance containing API key and settings. If not provided, creates config from environment variables (requires USPTO_API_KEY).

  • base_url (str | None) – Optional base URL override for the USPTO OA Actions API. If not provided, uses config.oa_actions_base_url or default.

get_fields()[source]

Retrieve available fields and API metadata for the OA Actions API.

Returns:

API metadata including available field

names and last data update timestamp.

Return type:

OAActionsFieldsResponse

Examples

>>> fields_response = client.get_fields()
>>> print(fields_response.field_count)
56
>>> print(fields_response.api_status)
'PUBLISHED'
paginate(post_body=None, **kwargs)[source]

Provide an iterator to paginate through office action search results.

Automatically handles pagination using Solr-style start/rows parameters. The start parameter is managed internally; providing it will raise a ValueError.

Parameters:

  • post_body (dict[str, Any] | None) – Optional POST body dict for complex search queries.

  • **kwargs (Any) – Keyword arguments passed to search().

Returns:

An iterator yielding OAActionsRecord objects.

Return type:

Iterator[OAActionsRecord]

Examples

# Paginate through all CTNF actions in tech center 1700 >>> for record in client.paginate( … tech_center_q=”1700”, … legacy_document_code_identifier_q=”CTNF”, … rows=50, … ): … print(record.patent_application_number)

# Paginate with POST body >>> for record in client.paginate( … post_body={“criteria”: “techCenter:1700”, “rows”: 50} … ): … process(record)

search(criteria=None, sort=None, start=0, rows=25, post_body=None, patent_application_number_q=None, legacy_document_code_identifier_q=None, group_art_unit_number_q=None, tech_center_q=None, access_level_category_q=None, application_type_category_q=None, submission_date_from_q=None, submission_date_to_q=None, additional_query_params=None)[source]

Return office action records matching the given criteria.

This method performs a POST request (form-urlencoded) to search for office action documents. You can provide either a direct post_body, a criteria string, or use convenience parameters.

Parameters:

  • criteria (str | None) – Direct Solr query string (e.g., "patentApplicationNumber:14485382").

  • sort (str | None) – Sort order for results (e.g., "submissionDate desc").

  • start (int | None) – Starting index for pagination (default: 0).

  • rows (int | None) – Maximum number of records to return (default: 25).

  • post_body (dict[str, Any] | None) – Optional POST body dict for complex queries. When provided, all other parameters are ignored.

  • patent_application_number_q (str | None) – Filter by patent application number.

  • legacy_document_code_identifier_q (str | None) – Filter by document code (e.g., "CTNF", "NOA").

  • group_art_unit_number_q (str | int | None) – Filter by group art unit number.

  • tech_center_q (str | None) – Filter by technology center code.

  • access_level_category_q (str | None) – Filter by access level (e.g., "PUBLIC").

  • application_type_category_q (str | None) – Filter by application type (e.g., "REGULAR").

  • submission_date_from_q (str | None) – Filter from this submission date ("YYYY-MM-DD").

  • submission_date_to_q (str | None) – Filter to this submission date ("YYYY-MM-DD").

  • additional_query_params (dict[str, Any] | None) – Additional custom POST body parameters.

Returns:

Response containing matching office action records.

Return type:

OAActionsResponse

Examples

# Search with a direct criteria string >>> response = client.search( … criteria=”patentApplicationNumber:14485382” … )

# Search with convenience parameters >>> response = client.search( … tech_center_q=”1700”, … legacy_document_code_identifier_q=”CTNF”, … rows=50, … )

# Search with POST body >>> response = client.search( … post_body={“criteria”: “techCenter:1700”, “rows”: 100} … )