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

# Preview Deployment Changes

> List changes available for promotion between linked workspaces. Use filters and pagination to select resource metadata, or supply 1–20 resource_keys to read selected before and after documents. Both workspace IDs are required on every call. Each call reads current configuration, so changes between pages can change the results. Unchanged context and unsupported deletions cannot be selected for promotion.

## 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: workspace comparison:** Requires permission to author promotions from the source workspace and stage promotions into the target workspace, with an active link between them. Every comparison and document read checks both permissions.


## OpenAPI

````yaml /sections/api-reference/openapi-spec-v2.yaml post /v2/deployments/preview-changes
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/deployments/preview-changes:
    post:
      tags:
        - Review API
      summary: Preview Deployment Changes
      description: >-
        List changes available for promotion between linked workspaces. Use
        filters and pagination to select resource metadata, or supply 1–20
        resource_keys to read selected before and after documents. Both
        workspace IDs are required on every call. Each call reads current
        configuration, so changes between pages can change the results.
        Unchanged context and unsupported deletions cannot be selected for
        promotion.
      operationId: svrelay.publicv2.PublicAPIServiceV2.PreviewDeploymentChanges
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/svmeta.publicapi.PreviewDeploymentChangesRequest
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/svmeta.publicapi.PreviewDeploymentChangesResponse
      security:
        - BearerAuth: []
components:
  schemas:
    svmeta.publicapi.PreviewDeploymentChangesRequest:
      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
        filters:
          $ref: '#/components/schemas/svmeta.publicapi.TeamConfigDiffFilters'
          title: filters
          description: Values within a filter are ORed; separate filters are ANDed.
          x-stainless-terraform-configurability: optional
        pageSize:
          type: integer
          title: page_size
          format: int32
          description: Defaults to 50; maximum 100.
          x-stainless-terraform-configurability: computed_optional
        pageToken:
          type: string
          title: page_token
          description: Requires the same workspaces and filters as the preceding page.
          x-stainless-terraform-configurability: optional
        resourceKeys:
          type: array
          items:
            $ref: '#/components/schemas/svmeta.publicapi.TeamConfigResourceKey'
          title: resource_keys
          description: |-
            Read current documents for 1–20 unique keys, in request order.
             Cannot be combined with filters, page_size, or page_token.
          x-stainless-terraform-configurability: optional
      title: PreviewDeploymentChangesRequest
      required:
        - sourceTeamId
        - targetTeamId
      additionalProperties: false
    svmeta.publicapi.PreviewDeploymentChangesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/svmeta.publicapi.TeamConfigDiffItem'
          title: data
          x-stainless-terraform-configurability: optional
        nextPageToken:
          type: string
          title: next_page_token
          x-stainless-terraform-configurability: optional
        matchingCount:
          type: integer
          title: matching_count
          format: int32
          description: Number of matching rows, including required unchanged context.
          x-stainless-terraform-configurability: optional
      title: PreviewDeploymentChangesResponse
      additionalProperties: false
    svmeta.publicapi.TeamConfigDiffFilters:
      type: object
      properties:
        resourceTypes:
          type: array
          items:
            type: string
          title: resource_types
          description: >-
            Display types from the review UI, including separate guidance and
            skill types.
          x-stainless-terraform-configurability: optional
        operations:
          type: array
          items:
            type: string
          title: operations
          description: create, update, delete, or unchanged.
          x-stainless-terraform-configurability: optional
        itemStatuses:
          type: array
          items:
            type: string
          title: item_statuses
          description: >-
            pending, applied, failed, or withdrawn. Fresh comparisons usually
            have no status.
          x-stainless-terraform-configurability: optional
        search:
          type: string
          title: search
          description: >-
            Case-insensitive search of resource metadata and folder paths, not
            resource bodies.
          x-stainless-terraform-configurability: optional
      title: TeamConfigDiffFilters
      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.TeamConfigDiffItem:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/svmeta.publicapi.TeamConfigResourceKey'
          title: key
          x-stainless-terraform-configurability: optional
        resourceType:
          type: string
          title: resource_type
          x-stainless-terraform-configurability: optional
        name:
          type: string
          title: name
          x-stainless-terraform-configurability: optional
        description:
          type: string
          title: description
          x-stainless-terraform-configurability: optional
        operation:
          type: string
          title: operation
          x-stainless-terraform-configurability: optional
        itemStatus:
          type: string
          title: item_status
          x-stainless-terraform-configurability: optional
        selectable:
          type: boolean
          title: selectable
          x-stainless-terraform-configurability: computed_optional
        unavailableReason:
          type: string
          title: unavailable_reason
          x-stainless-terraform-configurability: optional
        validationErrorMessage:
          type: string
          title: validation_error_message
          x-stainless-terraform-configurability: optional
        configDiagnostics:
          $ref: >-
            #/components/schemas/serval.configuration.v1.ConfigurationDiagnosticReport
          title: config_diagnostics
          x-stainless-terraform-configurability: optional
        content:
          $ref: '#/components/schemas/svmeta.publicapi.TeamConfigDiffContent'
          title: content
          description: Only present when resource_keys requests selected documents.
          x-stainless-terraform-configurability: optional
      title: TeamConfigDiffItem
      additionalProperties: false
    serval.configuration.v1.ConfigurationDiagnosticReport:
      type: object
      properties:
        diagnostics:
          type: array
          items:
            $ref: >-
              #/components/schemas/serval.configuration.v1.ConfigurationDiagnostic
          title: diagnostics
          x-stainless-terraform-configurability: optional
        validationCompleteness:
          $ref: '#/components/schemas/serval.configuration.v1.ValidationCompleteness'
          title: validation_completeness
          x-stainless-terraform-configurability: optional
        supportReference:
          type: string
          title: support_reference
          x-stainless-terraform-configurability: optional
      title: ConfigurationDiagnosticReport
      additionalProperties: false
    svmeta.publicapi.TeamConfigDiffContent:
      type: object
      properties:
        contentStatus:
          $ref: '#/components/schemas/svmeta.publicapi.ReviewItemContentStatus'
          title: content_status
          x-stainless-terraform-configurability: optional
        before:
          $ref: '#/components/schemas/google.protobuf.Struct'
          title: before
          description: Portable, secret-scrubbed documents. Absent for a new resource.
          x-stainless-terraform-configurability: optional
        after:
          $ref: '#/components/schemas/google.protobuf.Struct'
          title: after
          description: >-
            Absent for a deletion. These documents are not public API mutation
            bodies.
          x-stainless-terraform-configurability: optional
      title: TeamConfigDiffContent
      additionalProperties: false
    serval.configuration.v1.ConfigurationDiagnostic:
      type: object
      properties:
        reason:
          type: string
          title: reason
          x-stainless-terraform-configurability: optional
        message:
          type: string
          title: message
          description: >-
            Keep the complete user-safe explanation for clients without guidance
            support.
          x-stainless-terraform-configurability: optional
        phase:
          $ref: '#/components/schemas/serval.configuration.v1.Phase'
          title: phase
          x-stainless-terraform-configurability: optional
        resource:
          $ref: '#/components/schemas/serval.configuration.v1.ResourceReference'
          title: resource
          x-stainless-terraform-configurability: optional
        guidance:
          $ref: >-
            #/components/schemas/serval.configuration.v1.ConfigurationDiagnosticGuidance
          title: guidance
          x-stainless-terraform-configurability: optional
      title: ConfigurationDiagnostic
      additionalProperties: false
    serval.configuration.v1.ValidationCompleteness:
      type: string
      title: ValidationCompleteness
      enum:
        - VALIDATION_COMPLETENESS_UNSPECIFIED
        - VALIDATION_COMPLETENESS_COMPLETE
        - VALIDATION_COMPLETENESS_PARTIAL
        - VALIDATION_COMPLETENESS_UNAVAILABLE
    svmeta.publicapi.ReviewItemContentStatus:
      type: string
      title: ReviewItemContentStatus
      enum:
        - REVIEW_ITEM_CONTENT_STATUS_UNSPECIFIED
        - REVIEW_ITEM_CONTENT_STATUS_AVAILABLE
        - REVIEW_ITEM_CONTENT_STATUS_MISSING_BASE
        - REVIEW_ITEM_CONTENT_STATUS_UNSUPPORTED
    google.protobuf.Struct:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/google.protobuf.Value'
      description: |-
        `Struct` represents a structured data value, consisting of fields
         which map to dynamically typed values. In some languages, `Struct`
         might be supported by a native representation. For example, in
         scripting languages like JS a struct is represented as an
         object. The details of that representation are described together
         with the proto support for the language.

         The JSON representation for `Struct` is JSON object.
    serval.configuration.v1.Phase:
      type: string
      title: Phase
      enum:
        - PHASE_UNSPECIFIED
        - PHASE_SERIALIZE
        - PHASE_PLAN
        - PHASE_VALIDATE
        - PHASE_STAGE
        - PHASE_REVIEW
        - PHASE_APPLY
        - PHASE_FINALIZE
        - PHASE_SETUP
    serval.configuration.v1.ResourceReference:
      type: object
      properties:
        kind:
          type: string
          title: kind
          x-stainless-terraform-configurability: optional
        resourceId:
          type: string
          title: resource_id
          x-stainless-terraform-configurability: optional
        scopedId:
          type: string
          title: scoped_id
          x-stainless-terraform-configurability: optional
        name:
          type: string
          title: name
          x-stainless-terraform-configurability: optional
        fieldPath:
          type: string
          title: field_path
          x-stainless-terraform-configurability: optional
      title: ResourceReference
      additionalProperties: false
    serval.configuration.v1.ConfigurationDiagnosticGuidance:
      type: object
      properties:
        summary:
          type: string
          title: summary
          description: >-
            Both fields contain intentionally user-safe text; raw errors stay in
            logs.
          x-stainless-terraform-configurability: optional
        recovery:
          type: string
          title: recovery
          x-stainless-terraform-configurability: optional
      title: ConfigurationDiagnosticGuidance
      additionalProperties: false
    google.protobuf.Value:
      oneOf:
        - type: 'null'
        - type: number
        - type: string
        - type: boolean
        - type: array
        - type: object
          additionalProperties: true
      description: |-
        `Value` represents a dynamically typed value which can be either
         null, a number, a string, a boolean, a recursive struct value, or a
         list of values. A producer of value is expected to set one of these
         variants. Absence of any variant indicates an error.

         The JSON representation for `Value` is JSON value.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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