> ## 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.

# Create a Review

> Supply exactly one source: draft with change_set_id, or promotion with source_team_id, target_team_id and selected resource_keys. Drafts use their saved versions and can be reviewed with approval-to-publish off; retries return the saved review. For a promotion, include top-level request_id. To revise a promotion, set promotion.revision with review_id and the latest expected_revision_id; omit expected_revision_id only if no revision exists. Title and description apply only to new reviews. Exact retries reuse the saved selection; a changed expected revision captures the selection again. RETRY_REQUIRED means the review was saved but setup needs recovery. NOT_NEEDED means no setup remains for that saved submission. This endpoint never publishes or applies changes.

## Authentication and permissions

> **Token requirements:** **User-based token (OAuth)**.
>
> 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 | Unsupported |
| Workspace-scoped API key | Unsupported |
| User-based token (OAuth) | Supported, subject to permissions |

Permissions joined by **+** are all required; **or** separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.

* **User: staged Catalyst draft:** With draft.change\_set\_id, requires workspace session access and permission to view the originating Catalyst chat or agent session in your organization. Creates a review of the staged versions, including when approval-to-publish is off. Omit promotion and revision inputs. Retrying the same change set returns its review. This operation never publishes or applies changes.

* **User: create or revise promotion review:** Requires author permission on the source and stage permission on the target, including retries. Retries are bound to the submitting user and workspace pair. New revisions require review revisions to be enabled, visibility of the existing review, the same workspace pair, and its current revision ID. Existing branch, link, validation, and receiving-approval checks remain enforced. This operation does not apply changes.


## OpenAPI

````yaml /sections/api-reference/openapi-spec-v2.yaml post /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: Alerts 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: Billing API
  - name: Browser API
  - name: Campaign API
  - name: Change Blackout API
  - name: Change Model API
  - name: Connected Channels API
  - name: Custom Field API
  - name: Custom Role 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
  - name: Forms API
  - name: Group API
  - name: Guidance API
  - name: Help Agent API
  - name: Improvement Request API
  - name: Journey API
  - name: Knowledge API
  - name: Knowledge Base API
  - name: One-Time Window API
  - name: Package API
  - name: Platform Migration API
  - name: Project API
  - name: Report API
  - name: Review API
  - name: Role Sync API
  - name: Roles API
  - name: SLA API
  - name: Schedule API
  - name: Skills API
  - name: Tag API
  - name: Ticket API
  - name: Ticket Import API
  - name: Ticket Type 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
  - name: Workspace API
  - name: Workspace Group API
  - name: Workspace SDLC Settings API
  - name: Workspace User API
paths:
  /v2/reviews:
    post:
      tags:
        - Review API
      summary: Create a Review
      description: >-
        Supply exactly one source: draft with change_set_id, or promotion with
        source_team_id, target_team_id and selected resource_keys. Drafts use
        their saved versions and can be reviewed with approval-to-publish off;
        retries return the saved review. For a promotion, include top-level
        request_id. To revise a promotion, set promotion.revision with review_id
        and the latest expected_revision_id; omit expected_revision_id only if
        no revision exists. Title and description apply only to new reviews.
        Exact retries reuse the saved selection; a changed expected revision
        captures the selection again. RETRY_REQUIRED means the review was saved
        but setup needs recovery. NOT_NEEDED means no setup remains for that
        saved submission. This endpoint never publishes or applies changes.
      operationId: svrelay.publicv2.PublicAPIServiceV2.CreateReview
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/svmeta.publicapi.CreateReviewRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/svmeta.publicapi.CreateReviewResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    svmeta.publicapi.CreateReviewRequest:
      type: object
      allOf:
        - properties:
            title:
              type:
                - string
                - 'null'
              title: title
              description: >-
                Only supported when creating a new review, not a promotion
                revision.
              x-stainless-terraform-configurability: optional
            description:
              type:
                - string
                - 'null'
              title: description
              x-stainless-terraform-configurability: optional
            requestId:
              type: string
              title: request_id
              description: >-
                Required for promotions. Reuse for retries; use a new value for
                different changes.
                 Optional and unused for Catalyst drafts, where change_set_id identifies retries.
              x-stainless-terraform-configurability: optional
        - oneOf:
            - type: object
              properties:
                draft:
                  $ref: '#/components/schemas/svmeta.publicapi.CatalystDraftSource'
                  title: draft
                  x-stainless-terraform-configurability: optional
              title: draft
              required:
                - draft
            - type: object
              properties:
                promotion:
                  $ref: '#/components/schemas/svmeta.publicapi.PromotionSource'
                  title: promotion
                  x-stainless-terraform-configurability: optional
              title: promotion
              required:
                - promotion
      title: CreateReviewRequest
      additionalProperties: false
    svmeta.publicapi.CreateReviewResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/svmeta.publicapi.ReviewSubmission'
          title: data
          x-stainless-terraform-configurability: optional
      title: CreateReviewResponse
      additionalProperties: false
    svmeta.publicapi.CatalystDraftSource:
      type: object
      properties:
        changeSetId:
          type: string
          title: change_set_id
          description: >-
            Create a review from this staged Catalyst change set, including its
            saved versions.
             Retrying the same change set returns its existing review without publishing it.
          x-stainless-terraform-configurability: required
      title: CatalystDraftSource
      required:
        - changeSetId
      additionalProperties: false
    svmeta.publicapi.PromotionSource:
      type: object
      properties:
        sourceTeamId:
          type: string
          title: source_team_id
          x-stainless-terraform-configurability: required
        targetTeamId:
          type: string
          title: target_team_id
          x-stainless-terraform-configurability: required
        resourceKeys:
          type: array
          items:
            $ref: '#/components/schemas/svmeta.publicapi.TeamConfigResourceKey'
          title: resource_keys
          x-stainless-terraform-configurability: required
        revision:
          $ref: '#/components/schemas/svmeta.publicapi.PromotionRevisionTarget'
          title: revision
          description: Set to add a revision to an existing promotion review.
          x-stainless-terraform-configurability: optional
      title: PromotionSource
      required:
        - sourceTeamId
        - targetTeamId
        - resourceKeys
      additionalProperties: false
    svmeta.publicapi.ReviewSubmission:
      type: object
      properties:
        reviewId:
          type: string
          title: review_id
          x-stainless-terraform-configurability: optional
        revisionId:
          type: string
          title: revision_id
          x-stainless-terraform-configurability: optional
        revisionNumber:
          type: integer
          title: revision_number
          format: int32
          x-stainless-terraform-configurability: optional
        setupStatus:
          $ref: '#/components/schemas/svmeta.publicapi.ReviewSetupStatus'
          title: setup_status
          x-stainless-terraform-configurability: optional
        reviewUrl:
          type: string
          title: review_url
          x-stainless-terraform-configurability: optional
      title: ReviewSubmission
      additionalProperties: false
    svmeta.publicapi.TeamConfigResourceKey:
      type: object
      properties:
        resourceKind:
          type: string
          title: resource_kind
          description: >-
            Canonical ResourceManager kind; together with scoped_id identifies a
            portable resource.
          x-stainless-terraform-configurability: required
        scopedId:
          type: string
          title: scoped_id
          x-stainless-terraform-configurability: required
      title: TeamConfigResourceKey
      required:
        - resourceKind
        - scopedId
      additionalProperties: false
    svmeta.publicapi.PromotionRevisionTarget:
      type: object
      properties:
        reviewId:
          type: string
          title: review_id
          x-stainless-terraform-configurability: required
        expectedRevisionId:
          type:
            - string
            - 'null'
          title: expected_revision_id
          description: >-
            The latest revision inspected by the caller. Omit only when the
            review has no revision.
          x-stainless-terraform-configurability: optional
      title: PromotionRevisionTarget
      required:
        - reviewId
      additionalProperties: false
    svmeta.publicapi.ReviewSetupStatus:
      type: string
      title: ReviewSetupStatus
      enum:
        - REVIEW_SETUP_STATUS_UNSPECIFIED
        - REVIEW_SETUP_STATUS_COMPLETE
        - REVIEW_SETUP_STATUS_RETRY_REQUIRED
        - REVIEW_SETUP_STATUS_NOT_NEEDED
      description: >-
        COMPLETE means approval and check setup finished. RETRY_REQUIRED means
        the review
         was saved but setup failed; retry the same request. NOT_NEEDED means the review
         is withdrawn, applying, applied or rejected, or a later revision replaced it.
         UNSPECIFIED is not returned by this API.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.