> ## Documentation Index > Fetch the complete documentation index at: https://docs.reputably.net/llms.txt > Use this file to discover all available pages before exploring further. # List reviews > Reads reviews in the selected workspace. Filter with `q`, a JSON object of field matches. Reads only: writes through this route are refused for every entity and every credential. ## OpenAPI ````yaml /openapi.json get /api/entities/Review openapi: 3.1.0 info: title: Reputably API version: 1.0.0 description: >- The HTTP surface an agent credential can reach. It is read plus safe writes: you can read your reputation data, generate drafts, queue reports and run first-time tracking setup. You cannot send anything to an external platform, trigger syncs, touch billing or manage credentials. The same endpoints back the MCP server, so anything documented here is reachable both ways. servers: - url: https://app.reputably.net description: Reputably - url: https://your-domain.example description: Your own verified white-label domain security: - agentKey: [] tags: - name: Businesses description: The locations you track, their plan usage and AI-generated insights. - name: Reviews description: Google and Facebook reviews, including which still need a reply. - name: Brand mentions description: Mentions across X, Reddit, YouTube, Facebook communities and the open web. - name: Brand tracking description: The trackers that find mentions, and competitor share of voice. - name: Leads description: Buying signals detected in mentions, with the public post to reply to. - name: AI Visibility description: >- Whether AI assistants recommend the business, what they cite, and how it moves. - name: AI Traffic description: Which AI crawlers read the website, and who arrives from an AI answer. - name: Posts description: Google Business Profile posts and drafts. - name: Reports description: Queued report renders and their CSV output. - name: Setup description: First-time tracking configuration. - name: Account description: Workspaces, notifications, sync status and prospect audits. paths: /api/entities/Review: get: tags: - Reviews summary: List reviews description: >- Reads reviews in the selected workspace. Filter with `q`, a JSON object of field matches. Reads only: writes through this route are refused for every entity and every credential. operationId: listReview parameters: - name: q in: query required: false schema: type: string description: JSON filter object, for example {"needs_response":true}. - name: sort_by in: query required: false schema: type: string description: Field to sort on. - name: limit in: query required: false schema: type: integer description: Maximum rows to return. - name: skip in: query required: false schema: type: integer description: Rows to skip, for paging. - name: X-Workspace-Id in: header required: false schema: type: string description: >- Which workspace to read. Omit it and you get the account’s home workspace, which on an agency account is often not where the live businesses are. A workspace this credential cannot read is refused with 403 rather than quietly answered from the default. responses: '200': description: Matching reviews. content: application/json: schema: type: array items: $ref: '#/components/schemas/Review' '401': description: Missing or invalid credential. '403': description: Not readable by this credential, or not in this workspace. components: schemas: Review: type: object title: Review properties: id: type: string description: Unique id. location_id: type: string google_review_id: type: string source: type: string enum: - google - facebook description: >- Which platform this review came from. Drives the reply dispatcher and source-aware UI. source_id: type: string description: >- Platform-native identifier for this review. For GBP: matches google_review_id. For Facebook: the open_graph_story.id we comment on when replying. source_metadata: type: object description: >- Free-form platform-specific extras (e.g. Facebook recommendation_type, reply_comment_id). Generic code should not read from this. reviewer_name: type: string reviewer_photo_url: type: string reviewer_is_local_guide: type: boolean star_rating: type: - integer - 'null' description: >- Null for sources without a 1-5 rating (Facebook recommendations). Charts that aggregate on rating should exclude null rows. review_text: type: string review_language: type: string review_created_at: type: string review_updated_at: type: string reply_text: type: string reply_created_at: type: string reply_updated_by: type: string sentiment: type: string enum: - positive - neutral - negative - mixed sentiment_score: type: number key_topics: type: array items: type: string emotion: type: string enum: - joy - anger - sadness - fear - surprise - disgust - neutral is_flagged: type: boolean flag_reason: type: string is_read: type: boolean needs_response: type: boolean priority: type: string enum: - urgent - high - medium - low ai_suggested_response: type: string notes: type: string synced_at: type: string gbp_api_synced_at: type: string description: >- Last time the Google Business Profile API returned this review. Absent on reviews imported another way. removed_at_source_at: type: - string - 'null' description: >- Set when a VERIFIED-COMPLETE fetch of the source listing did not return this review — i.e. the reviewer deleted it, or the platform moderated it away. A soft flag rather than a delete so reply history and past analytics survive and a source-side glitch is recoverable: the row is cleared back to null the moment the source returns the review again. Rows carrying it are excluded from the response queue, the review lists, and every analytics denominator (server/lib/reviewVisibility.js + src/lib/reviewVisibility.js). Only ever written off a complete pass — see server/lib/reviewPruning.js. auto_response_status: type: string enum: - pending - sent - skipped - failed description: >- Lifecycle of the auto-response worker for this review. 'pending' = scheduled, awaiting fire time. 'sent' = AI reply was generated and posted to the source. 'skipped' = the rating wasn't in the agency's filter, or auto-response was disabled at sync time, or the review already had a reply. 'failed' = a fire attempt errored (see auto_response_error). Null/absent on review rows that pre-date the feature. auto_response_scheduled_at: type: string description: >- ISO timestamp the worker will fire at. Picked once at review-insert time as a uniform random value in [now+min_delay, now+max_delay] from the agency's auto_response_settings. Surviving process restarts is the whole point of stamping it on the row. auto_response_error: type: string description: >- Last error message when auto_response_status='failed'. Used to surface the failure on the review card without a separate audit table. securitySchemes: agentKey: type: http scheme: bearer description: >- An agent key (`rpk_...`) created in Settings → API & MCP, sent as `Authorization: Bearer rpk_...`. Bearer only: a cookie session can never drive this API. An OAuth 2.1 access token obtained from the same host works identically and lands on the same ceiling. ````