> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Reviews
> List a team's session reviews and incoming promotions, or use outgoing=true for promotions from that team. Results use cursor pagination. Each subsequent review or item request checks access independently.
## Authentication and permissions
> **Token requirements:** **User-based token (OAuth)** or **Organization-scoped API key** or **Team-scoped API key**.
>
> Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.
| Credential | Access requirements |
| - | - |
| Organization-scoped API key | **API key:** `reviews:read`
**User: session reviews and incoming promotions, User: outgoing promotions:** Unsupported |
| Team-scoped API key | **API key:** `reviews:read`
**User: session reviews and incoming promotions, User: outgoing promotions:** Unsupported |
| User-based token (OAuth) | **API key:** Unsupported
**User: session reviews and incoming promotions, User: outgoing promotions:** Supported, subject to permissions |
Permissions joined by **+** are all required; **or** separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Team keys must allow every team checked by the request. OAuth access depends on the user’s roles and resource access.
* **API key:** The requested team must be in your organization and allowed by the key. Use outgoing=true for promotions from that team.
* **User: session reviews and incoming promotions:** Requires permission to view configuration sessions in the requested team.
* **User: outgoing promotions:** With outgoing=true, requires permission to author promotions from the requested team.
## OpenAPI
````yaml /sections/api-reference/openapi-spec-v2.yaml get /v2/reviews
openapi: 3.1.0
info:
title: Serval Public API
description: Serval Public API
contact:
name: Serval
url: https://serval.com
email: support@serval.com
license:
name: Serval License
url: https://serval.com/license
version: 2.0.0
servers:
- url: https://public.api.serval.com
security:
- BearerAuth: []
tags:
- name: Access Membership API
- name: Access Policy API
- name: Access Policy Approval Procedure API
- name: Access Profile API
- name: Access Relationship API
- name: Access Request API
- name: Agent API
- name: Analytics API
- name: App Instance API
- name: App Resource API
- name: App Resource Role API
- name: Approval Delegation API
- name: Approval Procedure API
- name: Approval Request API
- name: Assignment Rules API
- name: Audit Log API
- name: Campaign API
- name: Change Blackout API
- name: Change Model API
- name: Connected Channels API
- name: Custom Field API
- name: Custom Service API
- name: Dashboards API
- name: Email Intake API
- name: Entity API
- name: Entity Field Mapping API
- name: Entity Ingestion Config API
- name: Entity Type API
- name: Folder API
- name: Forms API
- name: Group API
- name: Guidance API
- name: Help Agent API
- name: Journey API
- name: Knowledge API
- name: Knowledge Base API
- name: One-Time Window API
- name: Report API
- name: Review API
- name: Roles API
- name: SLA API
- name: Schedule API
- name: Tag API
- name: Team API
- name: Team Group API
- name: Team SDLC Settings API
- name: Team User API
- name: Ticket API
- name: Topic API
- name: User API
- name: User Relationship API
- name: Widgets API
- name: Worker API
- name: Workflow API
- name: Workflow Approval Procedure API
- name: Workflow Run API
paths:
/v2/reviews:
get:
tags:
- Review API
summary: List Reviews
description: >-
List a team's session reviews and incoming promotions, or use
outgoing=true for promotions from that team. Results use cursor
pagination. Each subsequent review or item request checks access
independently.
operationId: svrelay.publicv2.PublicAPIServiceV2.ListReviews
parameters:
- name: teamId
in: query
schema:
type: string
title: team_id
- name: outgoing
in: query
schema:
type: boolean
title: outgoing
description: >-
Outgoing promotions from team_id; otherwise reviews owned by
team_id.
- name: pageSize
in: query
schema:
type: integer
title: page_size
format: int32
description: Defaults to 50; maximum 100.
- name: pageToken
in: query
schema:
type: string
title: page_token
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/svmeta.publicapi.ListReviewsResponse'
security:
- BearerAuth: []
components:
schemas:
svmeta.publicapi.ListReviewsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/svmeta.publicapi.Review'
title: data
x-stainless-terraform-configurability: optional
nextPageToken:
type: string
title: next_page_token
x-stainless-terraform-configurability: optional
title: ListReviewsResponse
additionalProperties: false
svmeta.publicapi.Review:
type: object
properties:
id:
type: string
title: id
x-stainless-terraform-configurability: optional
title:
type: string
title: title
x-stainless-terraform-configurability: optional
description:
type: string
title: description
x-stainless-terraform-configurability: optional
createdByUserId:
type: string
title: created_by_user_id
x-stainless-terraform-configurability: optional
createdAt:
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: created_at
x-stainless-terraform-configurability: optional
closedAt:
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: closed_at
x-stainless-terraform-configurability: optional
sourceTeamId:
type: string
title: source_team_id
x-stainless-terraform-configurability: optional
targetTeamId:
type: string
title: target_team_id
x-stainless-terraform-configurability: optional
origin:
$ref: '#/components/schemas/svmeta.publicapi.ReviewOrigin'
title: origin
x-stainless-terraform-configurability: optional
session:
$ref: '#/components/schemas/svmeta.publicapi.ReviewSessionSource'
title: session
x-stainless-terraform-configurability: optional
applyStatus:
$ref: '#/components/schemas/svmeta.publicapi.ReviewApplyStatus'
title: apply_status
description: Application outcome is independent of approval and withdrawal.
x-stainless-terraform-configurability: optional
sourceOrgId:
type:
- string
- 'null'
title: source_org_id
description: Unset when the source team has been deleted or no longer exists.
x-stainless-terraform-configurability: optional
targetOrgId:
type:
- string
- 'null'
title: target_org_id
description: Unset when the target team has been deleted or no longer exists.
x-stainless-terraform-configurability: optional
title: Review
additionalProperties: false
google.protobuf.Timestamp:
type: string
examples:
- '2025-01-15T01:30:15.000Z'
- '2025-06-01T00:00:00.000Z'
format: date-time
description: A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").
svmeta.publicapi.ReviewOrigin:
type: string
title: ReviewOrigin
enum:
- REVIEW_ORIGIN_UNSPECIFIED
- REVIEW_ORIGIN_CATALYST
- REVIEW_ORIGIN_PROMOTION
svmeta.publicapi.ReviewSessionSource:
type: object
properties:
sessionId:
type: string
title: session_id
x-stainless-terraform-configurability: optional
agentId:
type:
- string
- 'null'
title: agent_id
description: Present for background-agent sessions.
x-stainless-terraform-configurability: optional
title: ReviewSessionSource
additionalProperties: false
svmeta.publicapi.ReviewApplyStatus:
type: string
title: ReviewApplyStatus
enum:
- REVIEW_APPLY_STATUS_UNSPECIFIED
- REVIEW_APPLY_STATUS_PENDING
- REVIEW_APPLY_STATUS_ACCEPTED
- REVIEW_APPLY_STATUS_REJECTED
- REVIEW_APPLY_STATUS_APPLYING
- REVIEW_APPLY_STATUS_APPLIED
- REVIEW_APPLY_STATUS_FAILED
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.