> For the complete documentation index, see [llms.txt](https://gitbook.tryprotege.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.tryprotege.com/review/getting-started/api-reference/reports.md). # Reports Retrieve scanner report summaries and detailed page-level report output. ## List reports > Return scanner report summaries generated from completed scanner runs. Reports can be filtered by brand or searched by name. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reports","description":"Retrieve scanner report summaries and detailed page-level report output."}],"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":{"ReportListResponse":{"description":"Paginated collection of scanner reports.","type":"object","required":["reports","page"],"properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/ReportListItem"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}},"ReportListItem":{"description":"Summary representation of a scanner report.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"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/reports":{"get":{"summary":"List reports","description":"Return scanner report summaries generated from completed scanner runs. Reports can be filtered by brand or searched by name.","operationId":"listReports","tags":["Reports"],"parameters":[{"name":"brandId","in":"query","description":"Filter reports for a specific brand.","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Case-insensitive search against report names.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return per page.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"offset","in":"query","description":"Number of records to skip before starting the page.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"sortBy","in":"query","description":"Field used to sort the result set.","schema":{"type":"string","enum":["createdAt","name","documentCount"]}},{"name":"sortOrder","in":"query","description":"Sort direction for the selected sort field.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Report summaries returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportListResponse"}}}},"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"}}}}}}}}} ``` ## Get a report with scanned pages > Retrieve a report and the scanned pages or captured documents that make up the report payload. ```json {"openapi":"3.1.0","info":{"title":"Protege External Review API","version":"1.0.1"},"tags":[{"name":"Reports","description":"Retrieve scanner report summaries and detailed page-level report output."}],"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":{"ReportDetail":{"description":"Report detail including captured pages and page-level metadata.","allOf":[{"$ref":"#/components/schemas/ReportDetailSummary"},{"type":"object","required":["pages"],"properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/ReportPage"}}}}]},"ReportDetailSummary":{"description":"Top-level report metadata returned with detailed report responses.","type":"object","required":["id","name","createdAt","documentCount"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"brand":{"oneOf":[{"$ref":"#/components/schemas/ReportBrand"},{"type":"null"}]},"documentCount":{"type":"integer"}}},"ReportBrand":{"description":"Lightweight brand reference attached to a scanner report.","type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ReportPage":{"description":"Page or document captured within a scanner report.","type":"object","required":["documentId","title","fileType","createdAt"],"properties":{"documentId":{"type":"string","format":"uuid"},"title":{"type":"string"},"link":{"oneOf":[{"type":"string"},{"type":"null"}]},"fileType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastScannedAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"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/reports/{reportId}":{"get":{"summary":"Get a report with scanned pages","description":"Retrieve a report and the scanned pages or captured documents that make up the report payload.","operationId":"getReport","tags":["Reports"],"parameters":[{"name":"reportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Report detail returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDetail"}}}},"400":{"description":"Missing or invalid report 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":"Report 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 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://gitbook.tryprotege.com/review/getting-started/api-reference/reports.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.