Google Drive Approvals API

openapi: 3.2.0
info:
  title: Google Drive Approvals API
  description: The Google Drive API allows clients to access resources from Google Drive.
  version: v3
  contact:
    name: Google
    url: https://developers.google.com/workspace/drive/
  termsOfService: https://developers.google.com/terms
  x-generated-from: google-discovery
  x-source: https://www.googleapis.com/discovery/v1/apis/drive/v3/rest
  x-discovery-revision: '20261102'
  x-generated: '2026-11-04'
servers:
- url: https://www.googleapis.com/drive/v3
  description: Google Drive REST API v3
security:
- oauth2: []
tags:
- name: Approvals
paths:
  /files/{fileId}/approvals/{approvalId}:reassign:
    post:
      operationId: reassignApprovals
      summary: Reassigns the reviewers on an approval
      description: Reassigns the reviewers on an approval. For more information, see Manage approvals. Adds or replaces reviewers in the ReviewerResponse of the approval. This can be called by any user with the `writer` permission on the file while the approval Status is `IN_PROGRESS` and the Response for the reviewer being reassigned is `NO_RESPONSE`. A user with the `reader` permission can only reassign an approval that's assigned to themselves. Removing a reviewer isn't allowed.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.reassign
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is on.
      - name: approvalId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the approval to reassign.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReassignApprovalRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
  /files/{fileId}/approvals/{approvalId}:approve:
    post:
      operationId: approveApprovals
      summary: Approves an approval
      description: Approves an approval. For more information, see Manage approvals. This is used to update the ReviewerResponse of the requesting user with a Response of `APPROVED`. If this is the last required reviewer response, this also completes the approval and sets the approval Status to `APPROVED`.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.approve
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is on.
      - name: approvalId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the approval to approve.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveApprovalRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
  /files/{fileId}/approvals/{approvalId}:comment:
    post:
      operationId: commentApprovals
      summary: Comments on an approval
      description: Comments on an approval. For more information, see Manage approvals. This sends a notification to both the initiator and the reviewers. Additionally, a message is also added to the approval activity log.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.comment
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is on.
      - name: approvalId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the approval to comment on.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentApprovalRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
  /files/{fileId}/approvals:start:
    post:
      operationId: startApprovals
      summary: Starts an approval on a file
      description: Starts an approval on a file. For more information, see Manage approvals.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.start
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is created on.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartApprovalRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
  /files/{fileId}/approvals/{approvalId}:cancel:
    post:
      operationId: cancelApprovals
      summary: Cancels an approval
      description: Cancels an approval. For more information, see Manage approvals. Updates the approval Status to `CANCELLED`. This can be called by any user with the `writer` permission on the file while the approval Status is `IN_PROGRESS`.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.cancel
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is on.
      - name: approvalId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the approval to cancel.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelApprovalRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
  /files/{fileId}/approvals/{approvalId}:decline:
    post:
      operationId: declineApprovals
      summary: Declines an approval
      description: Declines an approval. For more information, see Manage approvals. This is used to update the ReviewerResponse of the requesting user with a Response of `DECLINED`. This also completes the approval and sets the approval Status to `DECLINED`.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.decline
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is on.
      - name: approvalId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the approval to decline.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeclineApprovalRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
  /files/{fileId}/approvals/{approvalId}:
    get:
      operationId: getApproval
      summary: Gets an approval by ID
      description: Gets an approval by ID. For more information, see Manage approvals.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.get
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is on.
      - name: approvalId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the approval.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.appdata
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
        - https://www.googleapis.com/auth/drive.metadata.readonly
        - https://www.googleapis.com/auth/drive.readonly
  /files/{fileId}/approvals:
    get:
      operationId: listApprovals
      summary: Lists the approvals on a file
      description: Lists the approvals on a file. For more information, see Manage approvals. By default, this method returns a minimal response that may not include the items array. To retrieve approval details, you must explicitly specify the fields you want using the `fields` query parameter. To return the exact fields you need, see Return specific fields.
      tags:
      - Approvals
      x-discovery-id: drive.approvals.list
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
        description: Required. The ID of the file that the approval is on.
      - name: pageToken
        in: query
        required: false
        schema:
          type: string
        description: The token for continuing a previous list request on the next page. This should be set to the value of `nextPageToken` from a previous response.
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          format: int32
        description: The maximum number of approvals to return. When not set, at most 100 approvals are returned.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApprovalList'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/drive
        - https://www.googleapis.com/auth/drive.appdata
        - https://www.googleapis.com/auth/drive.file
        - https://www.googleapis.com/auth/drive.metadata
        - https://www.googleapis.com/auth/drive.metadata.readonly
        - https://www.googleapis.com/auth/drive.readonly
components:
  schemas:
    AddReviewer:
      type: object
      description: Representation of a reviewer addition.
      properties:
        addedReviewerEmail:
          type: string
          description: Required. The email of the reviewer to add.
    ApprovalList:
      type: object
      description: The response of an approvals list request.
      properties:
        nextPageToken:
          type: string
          description: The page token for the next page of approvals. This is absent if the end of the approvals list has been reached. If the token is rejected for any reason, it should be discarded, and pagination should be restarted from the first page of results.
        items:
          type: array
          description: The list of approvals. If `nextPageToken` is populated, then this list may be incomplete and an additional page of results should be fetched.
          items:
            $ref: '#/components/schemas/Approval'
        kind:
          type: string
          description: This is always drive#approvalList
    CommentApprovalRequest:
      type: object
      description: Request for commenting on an approval.
      properties:
        message:
          type: string
          description: Required. A message to comment on the approval. This message is included in notifications for the action and in the approval activity log.
    User:
      type: object
      description: Information about a Drive user.
      properties:
        photoLink:
          type: string
          description: Output only. A link to the user's profile photo, if available.
          readOnly: true
        emailAddress:
          type: string
          description: Output only. The email address of the user. This may not be present in certain contexts if the user has not made their email address visible to the requester.
          readOnly: true
        me:
          type: boolean
          description: Output only. Whether this user is the requesting user.
          readOnly: true
        displayName:
          type: string
          description: Output only. A plain text displayable name for this user.
          readOnly: true
        kind:
          type: string
          description: 'Output only. Identifies what kind of resource this is. Value: the fixed string `drive#user`.'
          default: drive#user
          readOnly: true
        permissionId:
          type: string
          description: Output only. The user's ID as visible in Permission resources.
          readOnly: true
    Approval:
      type: object
      description: Metadata for an approval. An approval is a review or approve process for a Drive item.
      properties:
        completeTime:
          type: string
          description: The time the approval was completed.
          format: google-datetime
        status:
          type: string
          description: The status of the approval at the time this resource was requested.
          enum:
          - STATUS_UNSPECIFIED
          - IN_PROGRESS
          - APPROVED
          - CANCELLED
          - DECLINED
        initiator:
          $ref: '#/components/schemas/User'
        createTime:
          type: string
          description: The time the approval was created.
          format: google-datetime
        kind:
          type: string
          description: This is always drive#approval.
        reviewerResponses:
          type: array
          description: The responses made on the approval by reviewers.
          items:
            $ref: '#/components/schemas/ReviewerResponse'
        dueTime:
          type: string
          description: The time that the approval is due.
          format: google-datetime
        modifyTime:
          type: string
          description: The most recent time the approval was modified.
          format: google-datetime
        targetFileId:
          type: string
          description: Target file id of the approval.
        fileContentChangeBehavior:
          type: string
          description: The behavior of the approval when the file content changes.
          enum:
          - FILE_CONTENT_CHANGE_BEHAVIOR_UNSPECIFIED
          - RESET_APPROVAL
          - NO_APPROVAL_ACTION
        approvalId:
          type: string
          description: The approval ID.
    ReviewerResponse:
      type: object
      description: A response on an approval made by a specific reviewer.
      properties:
        kind:
          type: string
          description: This is always drive#reviewerResponse.
        reviewer:
          $ref: '#/components/schemas/User'
        response:
          type: string
          description: A reviewer’s response for the approval.
          enum:
          - RESPONSE_UNSPECIFIED
          - NO_RESPONSE
          - APPROVED
          - DECLINED
    CancelApprovalRequest:
      type: object
      description: Request for cancelling an approval as an initiator.
      properties:
        message:
          type: string
          description: Optional. A message to accompany the cancellation of the approval. This message is included in notifications for the action and in the approval activity log.
    ReassignApprovalRequest:
      type: object
      description: Request for reassigning an approval. Reviewers can be added or replaced, but not removed.
      properties:
        replaceReviewers:
          type: array
          description: Optional. The list of reviewer replacements.
          items:
            $ref: '#/components/schemas/ReplaceReviewer'
        addReviewers:
          type: array
          description: Optional. The list of reviewers to add.
          items:
            $ref: '#/components/schemas/AddReviewer'
        message:
          type: string
          description: Optional. A message to send to the new reviewers. This message is included in notifications for the action and in the approval activity log.
    ReplaceReviewer:
      type: object
      description: Representation of a reviewer replacement.
      properties:
        removedReviewerEmail:
          type: string
          description: Required. The email of the reviewer to remove.
        addedReviewerEmail:
          type: string
          description: Required. The email of the reviewer to add.
    DeclineApprovalRequest:
      type: object
      description: Request for declining an approval as a reviewer.
      properties:
        message:
          type: string
          description: Optional. A message to accompany the reviewer response on the approval. This message is included in notifications for the action and in the approval activity log.
    StartApprovalRequest:
      type: object
      description: Allows creating an approval on a file.
      properties:
        lockFile:
          type: boolean
          description: Optional. Whether to lock the file when starting the approval.
        dueTime:
          type: string
          description: Optional. The time that the approval is due.
          format: google-datetime
        reviewerEmails:
          type: array
          description: Required. The emails of the users who are set to review the approval.
          items:
            type: string
        fileContentChangeBehavior:
          type: string
          description: Optional. The behavior of the approval when the file content changes.
          enum:
          - FILE_CONTENT_CHANGE_BEHAVIOR_UNSPECIFIED
          - RESET_APPROVAL
          - NO_APPROVAL_ACTION
        message:
          type: string
          description: Optional. A message to send to reviewers when notifying them of the approval request.
    ErrorResponse:
      type: object
      description: Google API error envelope (https://cloud.google.com/apis/design/errors)
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            errors:
              type: array
              items:
                type: object
                properties:
                  domain:
                    type: string
                  reason:
                    type: string
                  message:
                    type: string
                  location:
                    type: string
                  locationType:
                    type: string
    ApproveApprovalRequest:
      type: object
      description: Request for approving an approval as a reviewer.
      properties:
        message:
          type: string
          description: Optional. A message to accompany the reviewer response on the approval. This message is included in notifications for the action and in the approval activity log.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/drive.scripts: Modify your Google Apps Script scripts' behavior
            https://www.googleapis.com/auth/drive.meet.readonly: See and download your Google Drive files that were created or edited by Google Meet.
            https://www.googleapis.com/auth/drive: See, edit, create, and delete all of your Google Drive files
            https://www.googleapis.com/auth/drive.appdata: See, create, and delete its own configuration data in your Google Drive
            https://www.googleapis.com/auth/drive.file: See, edit, create, and delete only the specific Google Drive files you use with this app
            https://www.googleapis.com/auth/drive.apps.readonly: View your Google Drive apps
            https://www.googleapis.com/auth/drive.photos.readonly: View the photos, videos and albums in your Google Photos
            https://www.googleapis.com/auth/drive.readonly: See and download all your Google Drive files
            https://www.googleapis.com/auth/drive.metadata: View and manage metadata of files in your Google Drive
            https://www.googleapis.com/auth/drive.metadata.readonly: See information about your Google Drive files