{"openapi":"3.1.0","info":{"title":"DownloadPatent API","version":"1","contact":{"name":"DownloadPatent support","email":"support@downloadpatent.com"},"description":"Patent PDFs and office action citation lists. Calls spend the same credits as the website. Patent PDFs: a free allowance per account (the amount and its period are on /pricing; GET /balance gives what is left), then the per-patent price on /pricing, from credits. Office actions: $0.15 (quick) or $0.25 (full) per analysed file, charged when the job finishes, whether or not the result is read; a file that fails costs nothing; on the Monthly plan they first use those included per subscription period, shared with the website. An office action's cited patent PDFs and its ZIP come with the result and are included in its price (no free patent PDFs used, no extra charge, not counted toward the daily cap); each English counterpart costs $0.03 on its first download (on the Monthly plan, see /pricing for what is included). At most 2,000 patent PDFs per account per UTC day through POST /patent-pdfs (429 daily_patent_cap_reached). All amounts are integers in micro-dollars (1,000,000 = $1). Requests from sanctioned regions or restricted accounts get 451 region_unavailable. Each key may make 60 requests per minute; responses carry the IETF RateLimit-Policy and RateLimit fields, and a 429 carries Retry-After. Versioning: the version is in the path; /v1 only gains fields, endpoints and error codes. Anything retired is announced at least 90 days ahead with Deprecation (RFC 9745) and Sunset (RFC 8594) response headers; see https://downloadpatent.com/developers#dp-api-versioning."},"externalDocs":{"description":"API reference","url":"https://downloadpatent.com/developers"},"servers":[{"url":"https://downloadpatent.com/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/balance":{"get":{"operationId":"getBalance","summary":"Spendable credits and free patent PDFs left","description":"Credits are in micro-dollars (1,000,000 = $1): unexpired sign-up credits plus top-ups.","responses":{"200":{"description":"Balance","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key used its requests for this minute (with the RateLimit fields), or this address sent too many invalid keys (Retry-After only). Wait for Retry-After seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/patent-pdfs":{"post":{"operationId":"downloadPatentPdf","summary":"Download one patent PDF","description":"Returns the PDF bytes. The number may contain spaces, commas, slashes or hyphens and any case (US 9,876,543 B2); X-Patent-Number gives the canonical form used; an application number (US 10/123,456, or a CN/TW/JP/PCT application) is refused with reason application_number, never looked up. Free up to the account allowance on /pricing; each later one spends the per-patent price on /pricing from credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["number"],"properties":{"number":{"type":"string","maxLength":64,"example":"US10000000B2"}}}}}},"responses":{"200":{"description":"The PDF","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"invalid_request","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits, daily_free_limit_reached or key_spend_limit_reached","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"patent_not_found","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (this minute) or daily_patent_cap_reached (the account's 2,000 patent PDFs today; Retry-After runs to the next UTC midnight).","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/oa-jobs":{"post":{"operationId":"createOaJob","summary":"Upload office actions for citation analysis","description":"Creates an asynchronous job and holds the credits it may spend. Retry with the same Idempotency-Key to get the same job back instead of a second one. Quick reads only the search report attached to each office action; one without a search report yields no citations, so send it as full.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"mode":{"type":"string","enum":["quick","full"],"default":"quick"},"find_english":{"type":"boolean","description":"Find and deliver an English counterpart for each non-English cited patent. Default: true on the Monthly plan while it has allowance left, false once used up and otherwise. Delivered counterparts count toward the allowance; those past it, and all of them without a plan, cost $0.03 each."},"deliver_files":{"type":"boolean","default":true,"description":"Prepare the cited patent PDFs and the citation ZIP with the result. false: citation list only."},"file":{"type":"array","items":{"type":"string","format":"binary"},"description":"PDF, up to 25 MB each and 28 MB per request; quick up to 10 files, full exactly 1."}}}}}},"responses":{"200":{"description":"Replay of an earlier request with the same Idempotency-Key","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/OaJob"}}}}}},"202":{"description":"Job created","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/OaJob"}}}}}},"400":{"description":"invalid_request","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits or key_spend_limit_reached","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_in_progress","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_conflict","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key used its requests for this minute (with the RateLimit fields), or this address sent too many invalid keys (Retry-After only). Wait for Retry-After seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/oa-jobs/{id}":{"get":{"operationId":"getOaJob","summary":"Job status","description":"Poll until the status is done, partial or failed. Reading the status never charges.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/OaJob"}}}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key used its requests for this minute (with the RateLimit fields), or this address sent too many invalid keys (Retry-After only). Wait for Retry-After seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/oa-jobs/{id}/result":{"get":{"operationId":"getOaJobResult","summary":"Citations per office action","description":"Patent and non-patent citations per analysed file. Reading costs nothing: the job was charged when it finished. With deliver_files (the default) each cited patent gets pdfUrl and the job and each office action a zipUrl once job.filesStatus is ready; read the result again (every 5 s) while it is preparing. Files are kept 24 hours, as on the website.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Citations","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OaJobResult"}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"result_not_ready","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key used its requests for this minute (with the RateLimit fields), or this address sent too many invalid keys (Retry-After only). Wait for Retry-After seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/oa-jobs/{id}/archive":{"get":{"operationId":"downloadOaJobZip","summary":"The job's citation ZIP","description":"One office action's citation ZIP (cited PDFs, English counterparts, the cited-reference list), or for several a ZIP of each one's ZIP. Cited PDFs are included in the office action; an English counterpart is charged on its first delivery.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits or key_spend_limit_reached","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found (no such job or file, or past the 24-hour retention)","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"result_not_ready or files_not_ready","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key used its requests for this minute (with the RateLimit fields), or this address sent too many invalid keys (Retry-After only). Wait for Retry-After seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/oa-jobs/{id}/results/{resultId}/archive":{"get":{"operationId":"downloadOaResultZip","summary":"One office action's citation ZIP","description":"The resultId's citation ZIP from the result's zipUrl: its cited PDFs, English counterparts and the cited-reference list. Cited PDFs are included in the office action; an English counterpart is charged on its first delivery.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"resultId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits or key_spend_limit_reached","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found (no such job or file, or past the 24-hour retention)","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"result_not_ready or files_not_ready","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key used its requests for this minute (with the RateLimit fields), or this address sent too many invalid keys (Retry-After only). Wait for Retry-After seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/oa-jobs/{id}/files/{fileId}":{"get":{"operationId":"downloadOaJobFile","summary":"One cited patent PDF or English counterpart of the job","description":"The URL comes from pdfUrl or englishPdfUrl in the result. A cited patent PDF is included in the office action; the first download of an English counterpart costs $0.03 (Monthly plan: see /pricing for what is included).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"invalid_api_key, key_disabled or key_expired","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits or key_spend_limit_reached","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_available, or terms_consent_required on a call that starts new work: accept the updated Terms on the website.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found (no such job or file, or past the 24-hour retention)","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"result_not_ready or files_not_ready","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key used its requests for this minute (with the RateLimit fields), or this address sent too many invalid keys (Retry-After only). Wait for Retry-After seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"region_unavailable","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"headers":{"RateLimitPolicy":{"description":"The key's quota and window, as an IETF RateLimit-Policy field (draft-ietf-httpapi-ratelimit-headers): \"per-key\";q=<requests>;w=60.","schema":{"type":"string","example":"\"per-key\";q=60;w=60"}},"RateLimit":{"description":"Requests left in the current window and seconds until it ends, as an IETF RateLimit field: \"per-key\";r=<remaining>;t=<seconds>.","schema":{"type":"string","example":"\"per-key\";r=59;t=42"}},"XRateLimitLimit":{"description":"Requests per minute for this key (the older form of RateLimit-Policy).","schema":{"type":"integer","example":60}},"XRateLimitRemaining":{"description":"Requests left this minute (the older form of RateLimit).","schema":{"type":"integer","example":59}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"example":42}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A dpk_live_… key from Settings"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":true,"properties":{"code":{"type":"string","enum":["invalid_api_key","key_disabled","key_expired","api_not_available","terms_consent_required","rate_limited","insufficient_credits","daily_free_limit_reached","key_spend_limit_reached","invalid_request","not_found","method_not_allowed","patent_not_found","idempotency_conflict","idempotency_in_progress","result_not_ready","files_not_ready","daily_patent_cap_reached","payload_too_large","region_unavailable","unavailable"]},"message":{"type":"string"}}}}},"Balance":{"type":"object","properties":{"credits":{"type":"object","properties":{"currency":{"type":"string","const":"USD"},"totalMicros":{"type":"integer","description":"1,000,000 = $1"},"grantMicros":{"type":"integer"},"topupMicros":{"type":"integer"},"nextGrantExpiresAt":{"type":["string","null"],"format":"date-time"}}},"patentPdfs":{"type":"object","properties":{"freeRemaining":{"type":"integer","description":"Free patent PDFs left in the period."},"freeResetsAt":{"type":["string","null"],"format":"date-time","description":"When the count starts over; null while a plan period end is unknown."},"freeRemainingToday":{"type":"integer","deprecated":true,"description":"The same number as freeRemaining."}}},"monthlyOas":{"type":["object","null"],"description":"The Monthly plan this subscription period: office actions included and used (website and API together); null without a plan.","properties":{"included":{"type":"integer"},"used":{"type":"integer"},"periodEndsAt":{"type":["string","null"],"format":"date-time"}}}}},"OaJob":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["quick","full"]},"status":{"type":"string","enum":["queued","running","partial","done","failed","cancelled"]},"files":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"status":{"type":"string","enum":["queued","reading","ready","failed"]},"resultId":{"type":"string"},"failureReason":{"type":"string","enum":["analysis_failed","ocr_unavailable"]}}}},"requested":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}},"OaJobResult":{"type":"object","properties":{"job":{"allOf":[{"$ref":"#/components/schemas/OaJob"},{"type":"object","properties":{"filesStatus":{"type":"string","enum":["not_requested","preparing","ready","failed"],"description":"The cited PDFs and ZIPs: preparing right after the job finishes; read the result again until ready. not_requested when created with deliver_files=false."},"zipUrl":{"type":["string","null"],"description":"The whole job's ZIP once ready: one office action's citation ZIP, or a ZIP of each office action's ZIP. Same API key."}}}]},"results":{"type":"array","items":{"type":"object","properties":{"resultId":{"type":"string"},"filename":{"type":"string"},"country":{"type":"string"},"searchReportFound":{"type":"boolean","description":"Quick mode only. false: no search report or official citation list was found, so there are no citations; notice suggests mode=full."},"notice":{"type":"string"},"zipUrl":{"type":["string","null"],"description":"This office action's citation ZIP once filesStatus is ready: the PDFs below plus the cited-reference list, as the website's download names them."},"zipFilename":{"type":["string","null"]},"patents":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"raw":{"type":["string","null"]},"country":{"type":["string","null"]},"title":{"type":["string","null"]},"groups":{"type":"array","items":{"type":"string","enum":["substantive","background","pto892","ids_disclosed","annex_family","llm_fallback"]}},"source":{"type":"string","enum":["rule","ai"],"description":"ai: recovered by the AI fallback; review before relying on it."},"suspected":{"type":"boolean","description":"true: a citation-like mention that could not be identified as a patent; number only labels the mention and is not a fetchable patent number."},"notReliedUpon":{"type":"boolean"},"familyOf":{"type":["string","null"]},"englishFamilyMember":{"type":["string","null"],"description":"The English family member; when an English counterpart PDF is delivered, its number."},"chineseFamilyMember":{"type":["string","null"]},"pdfStatus":{"type":"string","enum":["ready","failed","not_included","preparing","not_requested"],"description":"ready: pdfUrl downloads it. failed: no source had a PDF. not_included: outside the website's default download selection (background mentions, IDS rows, AI-recovered or suspected rows); fetch it with POST /patent-pdfs if needed."},"pdfUrl":{"type":["string","null"]},"pdfFilename":{"type":["string","null"]},"englishPdfUrl":{"type":["string","null"],"description":"The English counterpart PDF delivered with the job (find_english=true): $0.03 each on first download; /pricing shows what the Monthly plan includes."},"englishCandidates":{"type":"array","items":{"type":"string"},"description":"Every English counterpart found, best first; only the first ready one is delivered."}}}},"nonPatentLiterature":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"kind":{"type":"string"},"doi":{"type":["string","null"]}}}}}}}}}}}}