# Document Reviews Submit documents for review, track processing status, and retrieve completed findings. ## List document reviews > Return document reviews visible to the authenticated tenant. This endpoint is typically used to poll or reconcile asynchronous reviews in bulk. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Document Reviews","description":"Submit documents for review, track processing status, and retrieve completed findings."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"ReviewStatus":{"description":"Current processing state of a submitted document review.","type":"string","enum":["queued","processing","completed","failed"]},"DocumentReviewListResponse":{"description":"Paginated collection of reviews visible to the calling API key.","type":"object","required":["documentReviews","page"],"properties":{"documentReviews":{"type":"array","items":{"$ref":"#/components/schemas/DocumentReviewSummary"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"DocumentReviewSummary":{"description":"Summary representation of a review returned by the list endpoint.","type":"object","required":["id","status","documentId","documentEvaluationTypeId","document","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ReviewStatus"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"error":{"type":"string","description":"Failure message for reviews that completed with an error."}}},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"PageMetadata":{"description":"Standard offset-based pagination metadata.","type":"object","required":["limit","offset","count","total"],"properties":{"limit":{"type":"integer","default":25},"offset":{"type":"integer","default":0},"count":{"type":"integer"},"total":{"type":"integer"}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/document-reviews":{"get":{"summary":"List document reviews","description":"Return document reviews visible to the authenticated tenant. This endpoint is typically used to poll or reconcile asynchronous reviews in bulk.","operationId":"listDocumentReviews","tags":["Document Reviews"],"parameters":[{"name":"id","in":"query","required":false,"description":"Filter by a specific review identifier.","schema":{"type":"string","format":"uuid"}},{"name":"documentEvaluationTypeId","in":"query","required":false,"description":"Filter reviews created with a specific document evaluation type.","schema":{"type":"string","format":"uuid"}},{"name":"externalId","in":"query","required":false,"description":"Filter by the client-supplied external document identifier.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter reviews by processing status.","schema":{"$ref":"#/components/schemas/ReviewStatus"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","required":false,"schema":{"type":"integer","default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","required":false,"schema":{"type":"integer","default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","required":false,"schema":{"type":"string","enum":["createdAt","updatedAt"],"default":"createdAt"}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Document reviews page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentReviewListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Failed to list document reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Create a document review > Submit a document for compliance review. Use JSON for plain-text content or multipart form data for file uploads. Synchronous requests return findings inline; asynchronous requests return a queued review that can be polled later. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Document Reviews","description":"Submit documents for review, track processing status, and retrieve completed findings."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"TextReviewRequest":{"description":"JSON request body for creating a review from plain text content.","type":"object","required":["documentEvaluationTypeId","document"],"properties":{"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentEvaluationTypeId":{"type":"string","format":"uuid","description":"Identifier of the review configuration to apply."},"document":{"$ref":"#/components/schemas/TextReviewDocument"}}},"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"},"TextReviewDocument":{"description":"Plain-text document content submitted directly in the JSON request body.","type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"],"description":"Identifies the document payload type."},"title":{"type":"string","description":"Client-friendly document title shown in review metadata."},"externalId":{"type":"string","description":"Client-supplied identifier used to correlate Protege reviews with your own records."},"text":{"type":"string","description":"Full plain-text content to review."},"metadata":{"type":"object","description":"Optional client-defined metadata that Protege stores with the review.","additionalProperties":true}}},"MultipartFileReviewRequest":{"description":"Multipart form payload for uploading a single file to review.","type":"object","required":["documentEvaluationTypeId","file"],"properties":{"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentEvaluationTypeId":{"type":"string","format":"uuid","description":"Identifier of the review configuration to apply."},"title":{"type":"string","description":"Optional title to associate with the uploaded document."},"externalId":{"type":"string","description":"Client-supplied identifier used for downstream reconciliation."},"metadata":{"type":"string","description":"JSON-encoded object string for document metadata."},"file":{"type":"string","format":"binary","description":"Upload a single file. Supported types are `.docx`, `.pdf`, `.png`, `.jpg`, and `.jpeg`.\n"}}},"CompletedReviewResponse":{"description":"Final response returned when a document review has completed successfully.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["completed"]},"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Structured findings produced by the completed review.","items":{"$ref":"#/components/schemas/Finding"}}}},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"Finding":{"description":"Structured review output describing a policy, trademark, or claim-related issue found in the document. The populated fields depend on the `kind` value.\n","oneOf":[{"$ref":"#/components/schemas/PolicyFeedbackFinding"},{"$ref":"#/components/schemas/ClaimFinding"},{"$ref":"#/components/schemas/TrademarkInstanceFinding"}],"discriminator":{"propertyName":"kind","mapping":{"policy_feedback":"#/components/schemas/PolicyFeedbackFinding","claim":"#/components/schemas/ClaimFinding","trademark_instance":"#/components/schemas/TrademarkInstanceFinding"}}},"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]},"PendingReviewResponse":{"description":"Review response returned while an asynchronous review is still queued, processing, or has failed.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","failed"]},"mode":{"type":"string","enum":["async"]},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Findings accumulated so far. This is typically empty until processing finishes.","items":{"$ref":"#/components/schemas/Finding"}},"error":{"type":"string","description":"Failure message when the asynchronous review ends in a `failed` state."}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/document-reviews":{"post":{"summary":"Create a document review","description":"Submit a document for compliance review. Use JSON for plain-text content or multipart form data for file uploads. Synchronous requests return findings inline; asynchronous requests return a queued review that can be polled later.","operationId":"createDocumentReview","tags":["Document Reviews"],"requestBody":{"required":true,"description":"Review request body supplied as JSON or multipart form data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextReviewRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/MultipartFileReviewRequest"},"encoding":{"metadata":{"contentType":"text/plain"}}}}},"responses":{"200":{"description":"Sync review completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletedReviewResponse"}}}},"202":{"description":"Async review accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingReviewResponse"}}}},"400":{"description":"Validation or sync-limit error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document evaluation type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported content type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` ## Get document review status or result > Retrieve the latest state of a specific document review. Completed reviews include findings; pending reviews expose queue or processing status. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Document Reviews","description":"Submit documents for review, track processing status, and retrieve completed findings."}],"servers":[{"url":"https://sandbox.tryprotege.com","description":"Sandbox environment for partner integration and testing."}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Supply the Protege external API key in the `Authorization` header using the format `Bearer `.\n"}},"schemas":{"CompletedReviewResponse":{"description":"Final response returned when a document review has completed successfully.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["completed"]},"mode":{"$ref":"#/components/schemas/ReviewMode"},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Structured findings produced by the completed review.","items":{"$ref":"#/components/schemas/Finding"}}}},"ReviewMode":{"description":"Controls whether the review should complete inline or be queued for background processing.","type":"string","enum":["sync","async"],"default":"sync"},"ReviewDocumentSummary":{"description":"Summary metadata about the reviewed source document.","type":"object","required":["title","fileType"],"properties":{"title":{"type":"string","description":"Title associated with the reviewed document."},"fileType":{"type":"string","enum":["TEXT","PDF","WEBPAGE","IMAGE","WEBSITE"],"description":"Protege document type classification for the reviewed content."},"externalId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Client-provided identifier echoed back in review responses."}}},"Finding":{"description":"Structured review output describing a policy, trademark, or claim-related issue found in the document. The populated fields depend on the `kind` value.\n","oneOf":[{"$ref":"#/components/schemas/PolicyFeedbackFinding"},{"$ref":"#/components/schemas/ClaimFinding"},{"$ref":"#/components/schemas/TrademarkInstanceFinding"}],"discriminator":{"propertyName":"kind","mapping":{"policy_feedback":"#/components/schemas/PolicyFeedbackFinding","claim":"#/components/schemas/ClaimFinding","trademark_instance":"#/components/schemas/TrademarkInstanceFinding"}}},"PolicyFeedbackFinding":{"description":"A finding produced by a policy evaluation, such as a brand compliance violation.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["policy","details"],"properties":{"policy":{"$ref":"#/components/schemas/PolicyRef"},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Policy-specific detail payload.","properties":{"policyOutputId":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the policy output that produced this finding."},"recommendation":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Actionable recommendation for resolving the finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"FindingBase":{"description":"Fields shared across every finding kind.","type":"object","required":["kind","text","comment","feedbackLocation","status","details"],"properties":{"kind":{"type":"string","enum":["policy_feedback","claim","trademark_instance"],"description":"Category of finding returned by Protege."},"text":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Text snippet or extracted value associated with the finding, when available."},"comment":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Reviewer-facing explanation of the issue or recommendation."},"riskLevel":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Severity or risk classification assigned by the review."},"feedbackLocation":{"type":"string","description":"Machine-readable indicator of the content medium where the finding was detected (e.g. 'text', 'image_ocr_text')."},"location":{"$ref":"#/components/schemas/FindingLocation"},"status":{"type":"string","description":"Resolution or approval status associated with the finding."},"approval":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Approval guidance for trademark-related findings, when applicable."},"metadata":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"Additional model-specific or workflow-specific metadata."},"formattedOutput":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Richly formatted version of the finding when available."}}},"FindingLocation":{"description":"Location metadata for a finding within a document.","type":"object","required":["pageNumber"],"properties":{"pageNumber":{"type":"integer"}}},"PolicyRef":{"description":"Lightweight policy reference attached to a finding.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"TrademarkRef":{"description":"Lightweight trademark reference attached to a finding.","type":"object","required":["id","name","proprietary"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"proprietary":{"type":"boolean"},"approval":{"oneOf":[{"type":"string"},{"type":"null"}]},"markType":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ClaimFinding":{"description":"A finding representing an extracted claim, such as a marketing guarantee or warranty statement.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"oneOf":[{"$ref":"#/components/schemas/TrademarkRef"},{"type":"null"}]},"details":{"type":"object","description":"Claim-specific detail payload.","properties":{"claim":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Canonical claim text extracted from the document."},"disclosureText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Recommended disclosure or qualifying text for a claim finding."},"userFixedText":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"User-provided replacement text for a claim finding."},"approvalLimitations":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"Scope or limitations tied to an approved claim finding."},"approvalExpireAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Expiration timestamp for an approved claim finding."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested alternative text or actions for the finding."}}}}}]},"TrademarkInstanceFinding":{"description":"A finding representing a potential trademark usage issue detected in the document.","allOf":[{"$ref":"#/components/schemas/FindingBase"},{"type":"object","required":["trademark","details"],"properties":{"policy":{"oneOf":[{"$ref":"#/components/schemas/PolicyRef"},{"type":"null"}]},"trademark":{"$ref":"#/components/schemas/TrademarkRef"},"details":{"type":"object","description":"Trademark-specific detail payload.","properties":{"suggestedFixCasing":{"type":"boolean","description":"Whether the trademark instance suggests a casing fix."},"recommendedMarkType":{"type":"string","description":"Recommended mark type for a trademark instance (e.g. 'trademark', 'registered')."},"suggestedMarkExplanation":{"type":"string","description":"Explanation for the recommended mark type."},"suggestedMarkRecord":{"oneOf":[{"type":"object"},{"type":"null"}],"description":"USPTO record details when a trademark match is found.","properties":{"keyword":{"type":"string"},"registrationNumber":{"type":"string"},"registrationDate":{"type":"string"},"statusLabel":{"type":"string"},"ownerName":{"type":"string"},"logo":{"type":"string","format":"uri"}}}}}}}]},"PendingReviewResponse":{"description":"Review response returned while an asynchronous review is still queued, processing, or has failed.","type":"object","required":["id","status","mode","documentId","documentEvaluationTypeId","document","findings"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing","failed"]},"mode":{"type":"string","enum":["async"]},"documentId":{"type":"string","format":"uuid"},"documentEvaluationTypeId":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/ReviewDocumentSummary"},"findings":{"type":"array","description":"Findings accumulated so far. This is typically empty until processing finishes.","items":{"$ref":"#/components/schemas/Finding"}},"error":{"type":"string","description":"Failure message when the asynchronous review ends in a `failed` state."}}},"ErrorResponse":{"description":"Standard error envelope returned when a request cannot be fulfilled.","type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable explanation of the failure."}}},"RateLimitError":{"description":"Returned when the client has exceeded the allowed request rate.","type":"object","required":["error","retryAfter"],"properties":{"error":{"type":"string","description":"Human-readable description of the rate-limit violation."},"retryAfter":{"type":"integer","description":"Number of seconds the client should wait before retrying."}}}}},"paths":{"/api/v1/document-reviews/{reviewId}":{"get":{"summary":"Get document review status or result","description":"Retrieve the latest state of a specific document review. Completed reviews include findings; pending reviews expose queue or processing status.","operationId":"getDocumentReview","tags":["Document Reviews"],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Review status or completed result","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CompletedReviewResponse"},{"$ref":"#/components/schemas/PendingReviewResponse"}]}}}},"400":{"description":"Missing review id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Review not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Number of seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://gitbook.tryprotege.com/review/getting-started/api-reference/document-reviews.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.