Google Forms Watches API

openapi: 3.2.0
info:
  title: Google Forms Watches API
  description: The Google Forms API is a RESTful interface that lets you create and modify Google Forms programmatically, read form responses, and set up watches for notifications on form changes and new responses.
  version: v1
  contact:
    name: Google
    url: https://developers.google.com/forms/api
  license:
    name: Google APIs Terms of Service
    url: https://developers.google.com/terms
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
- url: https://forms.googleapis.com
  description: Google Forms API production server
security:
- oauth2: []
tags:
- name: Watches
  description: Operations for managing form change notifications
paths:
  /v1/forms/{formId}/watches:
    post:
      operationId: createWatch
      summary: Google Forms Create Watch
      description: Create a new watch to receive notifications about form changes or new responses via Cloud Pub/Sub.
      tags:
      - Watches
      parameters:
      - name: formId
        in: path
        required: true
        description: The ID of the form to watch.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWatchRequest'
      responses:
        '200':
          description: Successful response with the created watch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watch'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Form not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listWatches
      summary: Google Forms List Watches
      description: Return a list of the watches owned by the invoking project for the specified form.
      tags:
      - Watches
      parameters:
      - name: formId
        in: path
        required: true
        description: The ID of the form whose watches to list.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with the list of watches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWatchesResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Form not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/forms/{formId}/watches/{watchId}:
    delete:
      operationId: deleteWatch
      summary: Google Forms Delete Watch
      description: Delete a watch and stop receiving notifications.
      tags:
      - Watches
      parameters:
      - name: formId
        in: path
        required: true
        description: The ID of the form.
        schema:
          type: string
      - name: watchId
        in: path
        required: true
        description: The ID of the watch to delete.
        schema:
          type: string
      responses:
        '204':
          description: Watch successfully deleted.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Watch not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/forms/{formId}/watches/{watchId}:renew:
    post:
      operationId: renewWatch
      summary: Google Forms Renew Watch
      description: Renew an existing watch for seven days from the current time.
      tags:
      - Watches
      parameters:
      - name: formId
        in: path
        required: true
        description: The ID of the form.
        schema:
          type: string
      - name: watchId
        in: path
        required: true
        description: The ID of the watch to renew.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with the renewed watch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watch'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Watch not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    WatchTarget:
      type: object
      description: The target for watch notifications.
      properties:
        topic:
          $ref: '#/components/schemas/CloudPubsubTopic'
    Watch:
      type: object
      description: A watch for receiving notifications about form changes or responses.
      properties:
        id:
          type: string
          description: Output only. The ID of this watch.
          readOnly: true
          example: watch-abc123
        target:
          $ref: '#/components/schemas/WatchTarget'
        eventType:
          type: string
          description: Required. Which event type to watch for.
          enum:
          - EVENT_TYPE_UNSPECIFIED
          - SCHEMA
          - RESPONSES
          example: RESPONSES
        createTime:
          type: string
          format: date-time
          description: Output only. Timestamp of when this was created.
          readOnly: true
          example: '2026-04-15T10:00:00Z'
        expireTime:
          type: string
          format: date-time
          description: Output only. Timestamp for when this will expire.
          readOnly: true
          example: '2026-04-22T10:00:00Z'
        errorType:
          type: string
          description: Output only. The most recent error type for an attempted delivery.
          readOnly: true
          enum:
          - ERROR_TYPE_UNSPECIFIED
          - PROJECT_NOT_AUTHORIZED
          - NO_USER_ACCESS
          - OTHER_ERRORS
        state:
          type: string
          description: Output only. The current state of the watch.
          readOnly: true
          enum:
          - STATE_UNSPECIFIED
          - ACTIVE
          - SUSPENDED
          example: ACTIVE
    CloudPubsubTopic:
      type: object
      description: A Cloud Pub/Sub topic for receiving notifications.
      properties:
        topicName:
          type: string
          description: Required. A fully qualified Pub/Sub topic name to publish to.
          example: projects/my-project/topics/forms-notifications
    CreateWatchRequest:
      type: object
      description: Request to create a new watch.
      properties:
        watch:
          $ref: '#/components/schemas/Watch'
    Error:
      type: object
      description: An error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: The HTTP status code.
              example: 404
            message:
              type: string
              description: A human-readable error message.
              example: Requested entity was not found.
            status:
              type: string
              description: The error status code.
              example: NOT_FOUND
    ListWatchesResponse:
      type: object
      description: Response from listing watches.
      properties:
        watches:
          type: array
          description: The list of watches.
          items:
            $ref: '#/components/schemas/Watch'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for Google Forms API.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/forms.body: View and manage your forms in Google Drive
            https://www.googleapis.com/auth/forms.body.readonly: View your forms in Google Drive
            https://www.googleapis.com/auth/forms.responses.readonly: View responses to your Google Forms
            https://www.googleapis.com/auth/drive: See, edit, create, and delete all of your Google Drive files
            https://www.googleapis.com/auth/drive.file: View and manage Google Drive files created with this app
            https://www.googleapis.com/auth/drive.readonly: View files in your Google Drive