> For the complete documentation index, see [llms.txt](https://docs.moregoodreviews.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moregoodreviews.com/platform/api-reference/reviews.md).

# Reviews

Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.

## List Reviews

> Retrieve project reviews with facet, source, location, score, and tag filters, optional sorting by rating or timestamps, and calendar bounds on a chosen review datetime column.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}},"schemas":{"SpriteClass":{"type":"string","maxLength":50,"pattern":"^(fab|fad|fak|fal|far|fas|fat)\\s+fa-[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Font Awesome icon: two CSS class names as used with Font Awesome Web Fonts / classic CSS (not SVG/React props).\nFormat is a style prefix (`fab`, `fad`, `fak`, `fal`, `far`, `fas`, or `fat`), one ASCII space, then an icon slug\nstarting with `fa-` (lowercase letters and digits, hyphen-separated words). Examples: `fab fa-google`, `fas fa-star`.\nOn write, omit, send null, or whitespace-only to clear. Font Awesome 6 semantic pairs such as `fa-solid fa-star`\nare not accepted; use `fas fa-star` instead."}}},"paths":{"/reviews":{"get":{"tags":["Reviews"],"summary":"List Reviews","operationId":"listReviews","description":"Retrieve project reviews with facet, source, location, score, and tag filters, optional sorting by rating or timestamps, and calendar bounds on a chosen review datetime column.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Object containing response data for this resource.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Short code or application-level status code for this resource."},"data":{"type":"array","description":"Response payload for the request.","items":{"type":"object","description":"Response payload for the request.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this resource."},"uuid":{"type":"string","description":"Stable UUID for this resource."},"score":{"type":"integer","description":"Score for this resource."},"review":{"type":"string","description":"Review for this resource."},"review_html":{"type":"string","description":"Review html for this resource."},"reply":{"type":"string","description":"Reply text associated with the review or message."},"is_hidden":{"type":"boolean","description":"Is hidden for this resource."},"is_duplicate":{"type":"boolean","description":"Is duplicate for this resource."},"has_highlights":{"type":"boolean","description":"Has highlights for this resource."},"can_reply":{"type":"boolean","description":"Can reply for this resource."},"has_reply":{"type":"boolean","description":"Has reply for this resource."},"external_url":{"type":"string","description":"External url for this resource."},"platform_url":{"type":"string","description":"Absolute URL to this review in the web console; uses the agency white-label host when configured."},"replied_at":{"type":"integer","description":"Unix timestamp when a reply was posted."},"created_at":{"type":"integer","description":"Unix timestamp when this resource was created."},"customer":{"type":"object","description":"Customer for this resource.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this resource."},"uuid":{"type":"string","description":"Stable UUID for this resource."},"name":{"type":"string","description":"Display name for this resource."},"color":{"type":"string","description":"Hex color associated with the resource."},"platform_url":{"type":"string","description":"Absolute URL to this customer in the web console; uses the agency white-label host when configured."}}},"location":{"type":"object","description":"Location for this resource.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this resource."},"project_id":{"type":"integer","description":"Unique numeric identifier for the project."},"uuid":{"type":"string","description":"Stable UUID for this resource."},"name":{"type":"string","description":"Display name for this resource."},"display_name":{"type":"string","description":"Public display name for this resource."},"slug":{"type":"string","description":"URL-friendly identifier for this resource."},"store_code":{"type":"string","description":"Internal store identifier for this location."},"title":{"type":"string","description":"Title or headline for the resource."},"address":{"type":"string","description":"Address for this resource."},"address1":{"type":"string","description":"Primary street address line."},"address2":{"type":"string","description":"Secondary street address line, such as suite or apartment."},"city":{"type":"string","description":"City for the address."},"state":{"type":"string","description":"State, province, or region for the address."},"postal_code":{"type":"string","description":"Postal or ZIP code for the address."}}},"rating":{"type":"object","description":"Numeric rating value for the review.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this resource."},"score":{"type":"integer","description":"Score for this resource."},"label":{"type":"string","description":"Label for this resource."}}},"reviewer":{"type":"object","description":"Reviewer for this resource.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this resource."},"name":{"type":"string","description":"Display name for this resource."},"photo_url":{"type":"string","description":"Photo url for this resource."}}},"source":{"type":"object","description":"Source system or review platform for this record.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this resource."},"uuid":{"type":"string","description":"Stable UUID for this resource."},"name":{"type":"string","description":"Display name for this resource."},"slug":{"type":"string","description":"URL-friendly identifier for this resource."},"sprite":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SpriteClass"}]},"color":{"type":"string","description":"Hex color associated with the resource."},"icon":{"type":"string","description":"Icon for this resource.","nullable":true}}},"fields":{"type":"array","description":"List of fields for this resource.","items":{"type":"object","description":"Fields for this resource.","properties":{"name":{"type":"string","description":"Display name for this resource."},"value":{"type":"string","description":"Stored value for this field."}}}},"tags":{"type":"array","description":"Maximum or current allowance for tag records.","items":{"type":"object","description":"Maximum or current allowance for tag records.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for this resource."},"uuid":{"type":"string","description":"Stable UUID for this resource."},"name":{"type":"string","description":"Display name for this resource."},"slug":{"type":"string","description":"URL-friendly identifier for this resource."}}}}}}},"pagination":{"type":"object","description":"Pagination metadata for list responses.","properties":{"current_page":{"type":"integer","description":"Current page number in the paginated result set."},"from":{"type":"integer","description":"Index of the first item returned on the current page."},"last_page":{"type":"integer","description":"Last available page number in the paginated result set."},"path":{"type":"string","description":"Base API path used for the paginated result set."},"per_page":{"type":"integer","description":"Number of items returned per page."},"to":{"type":"integer","description":"Index of the last item returned on the current page."},"total":{"type":"integer","description":"Total number of matching items."}}}}}}}}},"parameters":[{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date","nullable":true,"description":"Inclusive lower calendar date (YYYY-MM-DD) for the column chosen by date_key, defaulting to created_at when date_key is omitted."},"description":"Inclusive lower calendar date (YYYY-MM-DD) for the column chosen by date_key, defaulting to created_at when date_key is omitted."},{"name":"date_key","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Review datetime column paired with date_from and date_to (defaults to created_at when omitted).","enum":["created_at","replied_at","updated_at"]},"description":"Review datetime column paired with date_from and date_to (defaults to created_at when omitted)."},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date","nullable":true,"description":"Inclusive upper calendar date (YYYY-MM-DD) for the column chosen by date_key; must be on or after date_from when both bounds are provided."},"description":"Inclusive upper calendar date (YYYY-MM-DD) for the column chosen by date_key; must be on or after date_from when both bounds are provided."},{"name":"filter","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Review list facet aligned with console filters (non-duplicates unless duplicate is selected).","enum":["anonymous","duplicate","hidden","identified","native","visible","with-highlights","with-replies","without-replies","written"]},"description":"Filter reviews by visibility, platform, duplication, replies, content, or audience."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","nullable":true,"description":"Maximum number of records to return."},"description":"Maximum number of records to return."},{"name":"location_id","in":"query","required":false,"schema":{"type":"integer","nullable":true,"description":"Unique numeric identifier for the location."},"description":"Filter reviews by location ID."},{"name":"location_slug","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"URL-friendly identifier for the location."},"description":"Filter reviews by location slug."},{"name":"location_uuid","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Stable UUID for the location."},"description":"Filter reviews by location UUID."},{"name":"score","in":"query","required":false,"schema":{"type":"integer","nullable":true,"minimum":1,"maximum":5,"description":"Numeric rating score for the review."},"description":"Filter reviews by rating score."},{"name":"source_id","in":"query","required":false,"schema":{"type":"integer","nullable":true,"description":"Identifier for the source system or review platform."},"description":"Filter reviews by source ID."},{"name":"source_slug","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Source slug for this resource."},"description":"Filter reviews by source slug."},{"name":"source_uuid","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Source uuid for this resource."},"description":"Filter reviews by source UUID."},{"name":"sort_dir","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Sort direction applied when sort_key is set (defaults to desc when omitted).","enum":["asc","desc"]},"description":"Sort direction: asc or desc."},{"name":"sort_key","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"Review attribute to sort by; omit to use newest-first by creation time.","enum":["score","replied_at","created_at","updated_at"]},"description":"Review attribute to sort by."},{"name":"tag_slug","in":"query","required":false,"schema":{"type":"string","nullable":true,"description":"URL-friendly identifier for the review tag."},"description":"Filter reviews by tag slug."}]}}}}
```

## Delete Review

> Remove a review that should no longer be reconciled.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}}},"paths":{"/reviews/{id}":{"delete":{"tags":["Reviews"],"summary":"Delete Review","operationId":"deleteReview","description":"Remove a review that should no longer be reconciled.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Object containing response data for this resource.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Short code or application-level status code for this resource."}}}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","nullable":false,"description":"Unique numeric identifier for this resource."},"description":"Unique numeric identifier for this resource."}]}}}}
```

## Update Review Visibility

> Show or hide a review in public displays.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}}},"paths":{"/reviews/{id}/flag-hidden":{"put":{"tags":["Reviews"],"summary":"Update Review Visibility","operationId":"updateReviewVisibility","description":"Show or hide a review in public displays.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request body containing the desired review visibility flag.","properties":{"is_hidden":{"type":"boolean","description":"Whether this review should be hidden from public displays."}},"required":["is_hidden"]}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","nullable":false,"description":"Unique numeric identifier for this review."},"description":"Unique numeric identifier for this review."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Object containing response status for the request.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Application-level status code returned by this API."}}}}}}}}}}}
```

## Update Review Duplicate Flag

> Mark whether a review is a duplicate record.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}}},"paths":{"/reviews/{id}/flag-duplicate":{"put":{"tags":["Reviews"],"summary":"Update Review Duplicate Flag","operationId":"updateReviewDuplicateFlag","description":"Mark whether a review is a duplicate record.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request body containing the desired duplicate flag.","properties":{"is_duplicate":{"type":"boolean","description":"Whether this review should be marked as a duplicate."}},"required":["is_duplicate"]}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","nullable":false,"description":"Unique numeric identifier for this review."},"description":"Unique numeric identifier for this review."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Object containing response status for the request.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Application-level status code returned by this API."}}}}}}}}}}}
```

## Mark Review Replied

> Set or clear replied\_at when a reply was handled outside the platform without changing stored reply text.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}}},"paths":{"/reviews/{id}/mark-replied":{"put":{"tags":["Reviews"],"summary":"Mark Review Replied","operationId":"markReviewReplied","description":"Set or clear replied_at when a reply was handled outside the platform without changing stored reply text.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request body toggling whether the review counts as replied.","properties":{"replied":{"type":"boolean","description":"When true, records the current time as replied_at; when false, clears replied_at."}},"required":["replied"]}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","nullable":false,"description":"Unique numeric identifier for the review."},"description":"Unique numeric identifier for the review."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Object containing response status for the request.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Application-level status code returned by this API."}}}}}}}}}}}
```

## Reply to Review on Integration

> Publish or replace the business owner's reply on the review's connected platform (such as Google Business Profile or Facebook) using the project's active integration credentials; accepts manual reply text only and does not invoke AI drafting.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}}},"paths":{"/reviews/{id}/reply":{"put":{"tags":["Reviews"],"summary":"Reply to Review on Integration","operationId":"updateReviewIntegrationReply","description":"Publish or replace the business owner's reply on the review's connected platform (such as Google Business Profile or Facebook) using the project's active integration credentials; accepts manual reply text only and does not invoke AI drafting.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request body with the owner reply to send to the third-party review platform API.","properties":{"reply":{"type":"string","description":"Reply text to post or update on the external platform (for example Google or Facebook).","maxLength":4000}},"required":["reply"]}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","nullable":false,"description":"Unique numeric identifier for the review."},"description":"Unique numeric identifier for the review."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Object containing response status for the request.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Application-level status code returned by this API."}}}}}}}}}}}
```

## Update Review Tags

> Replace the tag assignments for a review using the provided slug list.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}}},"paths":{"/reviews/{id}/tags":{"put":{"tags":["Reviews"],"summary":"Update Review Tags","operationId":"updateReviewTags","description":"Replace the tag assignments for a review using the provided slug list.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request body listing tag slugs to apply; omitting unrelated tags removes them from the review.","properties":{"tag_slugs":{"type":"array","description":"Tag slugs to assign; send an empty array to clear all tags from this review.","items":{"type":"string","description":"Project tag slug."}}},"required":["tag_slugs"]}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Unique numeric identifier for the review."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","description":"Object containing response status for the request.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Application-level status code returned by this API."}}}}}}}}}}}
```

## Create Review Share Image

> Render a share-card PNG using optional template styling and aspect ratio, persist the image, and return CDN-backed metadata.

```json
{"openapi":"3.0.3","info":{"title":"MGR Project API","version":"1.0.0"},"tags":[{"description":"Review records collected for the project across its connected sources; list, moderate, share, tag, mark replied, or remove as integrations require.","name":"Reviews"}],"servers":[{"url":"https://api.moregoodreviews.com/project"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}}},"paths":{"/reviews/{id}/share-image":{"post":{"tags":["Reviews"],"summary":"Create Review Share Image","operationId":"createReviewShareImage","description":"Render a share-card PNG using optional template styling and aspect ratio, persist the image, and return CDN-backed metadata.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","nullable":false},"description":"Unique numeric identifier for the review."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Optionally pick a saved share template and export aspect ratio; send an empty object for built-in defaults at 1:1.","properties":{"ratio":{"type":"string","description":"Export aspect ratio; when set, overrides the ratio saved on the chosen template or the default preset.","enum":["1:1","4:5","9:16"]},"template_id":{"type":"integer","description":"Numeric id of a share template on this project; omit to merge only built-in defaults."}}}}}},"responses":{"200":{"description":"Generated share PNG exposed as Image metadata with a full HTTPS link matching other API image fields.","content":{"application/json":{"schema":{"type":"object","description":"Standard success envelope with ImageTransformer fields flattened into data like other singleton resources.","properties":{"success":{"type":"boolean","description":"Indicates whether the request completed successfully."},"code":{"type":"integer","description":"Application-level status code mirroring HTTP 200 on success."},"data":{"type":"object","description":"Transformed CDN-backed image backing the PNG share artifact.","properties":{"id":{"type":"integer","description":"Unique numeric identifier for the stored image asset."},"uuid":{"type":"string","description":"Stable UUID for the image asset and cache headers."},"link":{"type":"string","description":"Full HTTPS CDN URL referencing the PNG share card artifact."}},"required":["id","uuid","link"]}},"required":["success","code","data"]}}}}}}}}}
```