Google Forms Forms API

openapi: 3.0.3
info:
  title: Google Forms 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: Forms
  description: Operations for creating, reading, and updating forms
paths:
  /v1/forms:
    post:
      operationId: createForm
      summary: Google Forms Create Form
      description: Create a new form using the title given in the provided form message in the request body.
      tags:
      - Forms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Form'
      responses:
        '200':
          description: Successful response with the created form.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
        '400':
          description: Bad request - invalid form data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/forms/{formId}:
    get:
      operationId: getForm
      summary: Google Forms Get Form
      description: Get a form by its ID including the form structure, items, and settings.
      tags:
      - Forms
      parameters:
      - name: formId
        in: path
        required: true
        description: The ID of the form to retrieve.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with the form.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          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}:batchUpdate:
    post:
      operationId: batchUpdateForm
      summary: Google Forms Batch Update Form
      description: Change the form with a batch of updates including adding, removing, or modifying items and settings.
      tags:
      - Forms
      parameters:
      - name: formId
        in: path
        required: true
        description: The ID of the form to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateFormRequest'
      responses:
        '200':
          description: Successful response with the updated form.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateFormResponse'
        '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
  /v1/forms/{formId}:setPublishSettings:
    post:
      operationId: setPublishSettings
      summary: Google Forms Set Publish Settings
      description: Updates the publish settings of a form including whether the form is published and accepting responses.
      tags:
      - Forms
      parameters:
      - name: formId
        in: path
        required: true
        description: The ID of the form to update publish settings for.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPublishSettingsRequest'
      responses:
        '200':
          description: Successful response with the updated publish settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishSettings'
        '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
components:
  schemas:
    BatchUpdateFormResponse:
      type: object
      description: Response from a batch update operation.
      properties:
        form:
          $ref: '#/components/schemas/Form'
        replies:
          type: array
          description: The replies from each request in the batch.
          items:
            $ref: '#/components/schemas/Response'
        writeControl:
          $ref: '#/components/schemas/WriteControl'
    Request:
      type: object
      description: A single update request in a batch.
      properties:
        updateFormInfo:
          $ref: '#/components/schemas/UpdateFormInfoRequest'
        updateSettings:
          $ref: '#/components/schemas/UpdateSettingsRequest'
        createItem:
          $ref: '#/components/schemas/CreateItemRequest'
        moveItem:
          $ref: '#/components/schemas/MoveItemRequest'
        deleteItem:
          $ref: '#/components/schemas/DeleteItemRequest'
        updateItem:
          $ref: '#/components/schemas/UpdateItemRequest'
    ScaleQuestion:
      type: object
      description: A question with a numeric scale.
      properties:
        low:
          type: integer
          description: The lowest value on the scale.
          example: 1
        high:
          type: integer
          description: The highest value on the scale.
          example: 5
        lowLabel:
          type: string
          description: Label for the low end of the scale.
          example: Not Satisfied
        highLabel:
          type: string
          description: Label for the high end of the scale.
          example: Very Satisfied
    UpdateFormInfoRequest:
      type: object
      description: Request to update form info fields.
      properties:
        info:
          $ref: '#/components/schemas/Info'
        updateMask:
          type: string
          description: Fields to update specified as a comma-separated list.
          example: title,description
    QuestionGroupItem:
      type: object
      description: A form item containing a group of questions presented as a grid.
      properties:
        questions:
          type: array
          description: The list of questions in this group.
          items:
            $ref: '#/components/schemas/Question'
        image:
          $ref: '#/components/schemas/Image'
        grid:
          $ref: '#/components/schemas/Grid'
    MoveItemRequest:
      type: object
      description: Request to move an item to a different position.
      properties:
        originalLocation:
          $ref: '#/components/schemas/Location'
        newLocation:
          $ref: '#/components/schemas/Location'
    UpdateSettingsRequest:
      type: object
      description: Request to update form settings.
      properties:
        settings:
          $ref: '#/components/schemas/FormSettings'
        updateMask:
          type: string
          description: Fields to update.
          example: quizSettings.isQuiz
    Location:
      type: object
      description: A specific location in a form.
      properties:
        index:
          type: integer
          description: The index of an item in the form.
          example: 0
    QuizSettings:
      type: object
      description: Settings related to quiz forms and grading.
      properties:
        isQuiz:
          type: boolean
          description: Whether this form is a quiz.
          example: false
    Video:
      type: object
      description: A video in a form.
      properties:
        youtubeUri:
          type: string
          description: The YouTube URI of the video.
          example: https://www.youtube.com/watch?v=dQw4w9WgXcQ
        properties:
          $ref: '#/components/schemas/MediaProperties'
    Response:
      type: object
      description: A single response from a batch update request.
      properties:
        createItem:
          $ref: '#/components/schemas/CreateItemResponse'
    RatingQuestion:
      type: object
      description: A question with a rating input.
      properties:
        ratingScaleLevel:
          type: integer
          description: The number of rating levels.
          example: 5
        iconType:
          type: string
          description: The type of icon to display for the rating.
          enum:
          - ICON_TYPE_UNSPECIFIED
          - STAR
          - HEART
          - THUMB_UP
          example: STAR
    Grid:
      type: object
      description: A grid of questions sharing the same set of column choices.
      properties:
        columns:
          $ref: '#/components/schemas/ChoiceQuestion'
        shuffleQuestions:
          type: boolean
          description: Whether to randomize the order of rows.
          example: false
    CorrectAnswers:
      type: object
      description: The correct answers for grading.
      properties:
        answers:
          type: array
          description: A list of correct answers.
          items:
            $ref: '#/components/schemas/CorrectAnswer'
    CorrectAnswer:
      type: object
      description: A single correct answer value.
      properties:
        value:
          type: string
          description: The correct answer value.
          example: Paris
    VideoItem:
      type: object
      description: A form item that displays a video.
      properties:
        video:
          $ref: '#/components/schemas/Video'
        caption:
          type: string
          description: Caption displayed below the video.
          example: Product demo video
    WriteControl:
      type: object
      description: Provides control over write operations to prevent concurrent modifications.
      properties:
        requiredRevisionId:
          type: string
          description: The revision ID of the form that the request is based on.
          example: '00000042'
        targetRevisionId:
          type: string
          description: Output only. The target revision ID of the form.
          readOnly: true
    VideoLink:
      type: object
      description: A video link.
      properties:
        displayText:
          type: string
          description: The text to display for the video.
          example: Watch Tutorial
        youtubeUri:
          type: string
          description: The YouTube URI of the video.
          example: https://www.youtube.com/watch?v=dQw4w9WgXcQ
    Form:
      type: object
      description: A Google Form with items, settings, and metadata.
      properties:
        formId:
          type: string
          description: Output only. The form ID.
          readOnly: true
          example: 1BxiMVs0XRA5nFMdLXDSR2r9NphkU4V9qeeW0nQmGR8
        info:
          $ref: '#/components/schemas/Info'
        settings:
          $ref: '#/components/schemas/FormSettings'
        items:
          type: array
          description: A list of the form's items including section headers, questions, and media.
          items:
            $ref: '#/components/schemas/Item'
        revisionId:
          type: string
          description: Output only. The revision ID of the form used in write control for updates.
          readOnly: true
          example: '00000042'
        responderUri:
          type: string
          description: Output only. The form URI to share with responders.
          readOnly: true
          example: https://docs.google.com/forms/d/e/1FAIpQLSd.../viewform
        linkedSheetId:
          type: string
          description: Output only. The ID of the linked Google Sheet accumulating responses.
          readOnly: true
          example: 1a2b3c4d5e
        publishSettings:
          $ref: '#/components/schemas/PublishSettings'
    TimeQuestion:
      type: object
      description: A question that collects a time.
      properties:
        duration:
          type: boolean
          description: Whether the question is about a duration rather than a time of day.
          example: false
    Info:
      type: object
      description: General information about the form.
      required:
      - title
      properties:
        title:
          type: string
          description: Required. The title of the form visible to responders.
          example: Customer Feedback Survey
        documentTitle:
          type: string
          description: Output only. The title of the document visible in Google Drive.
          readOnly: true
          example: Customer Feedback Survey
        description:
          type: string
          description: The description of the form.
          example: Please share your feedback about our services.
    CreateItemResponse:
      type: object
      description: Response from creating an item.
      properties:
        itemId:
          type: string
          description: The ID of the created item.
          example: 4a5b6c7d
        questionId:
          type: array
          description: The IDs of created questions within the item.
          items:
            type: string
    Option:
      type: object
      description: An option for a choice question.
      properties:
        value:
          type: string
          description: The text value of the option.
          example: Very Satisfied
        image:
          $ref: '#/components/schemas/Image'
        isOther:
          type: boolean
          description: Whether this is an 'Other' option with a free text field.
          example: false
        goToAction:
          type: string
          description: Action to take when this option is selected.
          enum:
          - GO_TO_ACTION_UNSPECIFIED
          - NEXT_SECTION
          - RESTART_FORM
          - SUBMIT_FORM
        goToSectionId:
          type: string
          description: The item ID of the section to navigate to.
    TextQuestion:
      type: object
      description: A question that accepts text input.
      properties:
        paragraph:
          type: boolean
          description: Whether the question accepts paragraph (long) text.
          example: false
    CreateItemRequest:
      type: object
      description: Request to create a new item.
      properties:
        item:
          $ref: '#/components/schemas/Item'
        location:
          $ref: '#/components/schemas/Location'
    MediaProperties:
      type: object
      description: Properties of an image or video.
      properties:
        alignment:
          type: string
          description: The alignment of the media.
          enum:
          - ALIGNMENT_UNSPECIFIED
          - LEFT
          - RIGHT
          - CENTER
          example: CENTER
        width:
          type: integer
          description: The width of the media in pixels.
          example: 600
    ChoiceQuestion:
      type: object
      description: A question with predefined choices.
      properties:
        type:
          type: string
          description: The type of choice question.
          enum:
          - CHOICE_TYPE_UNSPECIFIED
          - RADIO
          - CHECKBOX
          - DROP_DOWN
          example: RADIO
        options:
          type: array
          description: The list of available options.
          items:
            $ref: '#/components/schemas/Option'
        shuffle:
          type: boolean
          description: Whether the options should be displayed in random order.
          example: false
    TextLink:
      type: object
      description: A text link.
      properties:
        uri:
          type: string
          description: The URI to link to.
          example: https://example.com/learn-more
        displayText:
          type: string
          description: The text to display for the link.
          example: Learn More
    Grading:
      type: object
      description: Grading configuration for a quiz question.
      properties:
        pointValue:
          type: integer
          description: The number of points available for this question.
          example: 10
        correctAnswers:
          $ref: '#/components/schemas/CorrectAnswers'
        whenRight:
          $ref: '#/components/schemas/Feedback'
        whenWrong:
          $ref: '#/components/schemas/Feedback'
        generalFeedback:
          $ref: '#/components/schemas/Feedback'
    BatchUpdateFormRequest:
      type: object
      description: Request to batch update a form.
      properties:
        includeFormInResponse:
          type: boolean
          description: Whether to include the updated form in the response.
          example: true
        requests:
          type: array
          description: The list of update requests to apply.
          items:
            $ref: '#/components/schemas/Request'
        writeControl:
          $ref: '#/components/schemas/WriteControl'
    DeleteItemRequest:
      type: object
      description: Request to delete an item.
      properties:
        location:
          $ref: '#/components/schemas/Location'
    Question:
      type: object
      description: A question in a form.
      properties:
        questionId:
          type: string
          description: Output only. The ID of the question.
          readOnly: true
          example: 7e8f9a0b
        required:
          type: boolean
          description: Whether the question must be answered to submit the form.
          example: true
        grading:
          $ref: '#/components/schemas/Grading'
        choiceQuestion:
          $ref: '#/components/schemas/ChoiceQuestion'
        textQuestion:
          $ref: '#/components/schemas/TextQuestion'
        scaleQuestion:
          $ref: '#/components/schemas/ScaleQuestion'
        dateQuestion:
          $ref: '#/components/schemas/DateQuestion'
        timeQuestion:
          $ref: '#/components/schemas/TimeQuestion'
        fileUploadQuestion:
          $ref: '#/components/schemas/FileUploadQuestion'
        rowQuestion:
          $ref: '#/components/schemas/RowQuestion'
        ratingQuestion:
          $ref: '#/components/schemas/RatingQuestion'
    QuestionItem:
      type: object
      description: A form item containing a single question.
      properties:
        question:
          $ref: '#/components/schemas/Question'
        image:
          $ref: '#/components/schemas/Image'
    Feedback:
      type: object
      description: Feedback shown after answering a quiz question.
      properties:
        text:
          type: string
          description: The feedback text.
          example: Great job!
        material:
          type: array
          description: Additional material shown with feedback.
          items:
            $ref: '#/components/schemas/ExtraMaterial'
    FormSettings:
      type: object
      description: Form-level settings including quiz configuration.
      properties:
        quizSettings:
          $ref: '#/components/schemas/QuizSettings'
        emailCollectionType:
          type: string
          description: Determines how email addresses are collected.
          enum:
          - EMAIL_COLLECTION_TYPE_UNSPECIFIED
          - DO_NOT_COLLECT
          - VERIFIED
          - RESPONDER_INPUT
          example: VERIFIED
    FileUploadQuestion:
      type: object
      description: A question that allows file upload.
      properties:
        folderId:
          type: string
          description: The Drive folder ID where uploaded files are stored.
          example: 1AbCdEfGhIjKlMnOpQrStUvWxYz
        types:
          type: array
          description: Allowed file types for upload.
          items:
            type: string
            enum:
            - FILE_TYPE_UNSPECIFIED
            - ANY
            - DOCUMENT
            - PRESENTATION
            - SPREADSHEET
            - DRAWING
            - PDF
            - IMAGE
            - VIDEO
            - AUDIO
        maxFiles:
          type: integer
          description: Maximum number of files a respondent can upload.
          example: 5
        maxFileSize:
          type: string
          description: Maximum file size in bytes.
          example: '10485760'
    ExtraMaterial:
      type: object
      description: Extra material that can be shown as feedback.
      properties:
        link:
          $ref: '#/components/schemas/TextLink'
        video:
          $ref: '#/components/schemas/VideoLink'
    UpdateItemRequest:
      type: object
      description: Request to update an existing item.
      properties:
        item:
          $ref: '#/components/schemas/Item'
        location:
          $ref: '#/components/schemas/Location'
        updateMask:
          type: string
          description: Fields to update.
          example: title,questionItem.question.required
    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
    Image:
      type: object
      description: An image in a form.
      properties:
        contentUri:
          type: string
          description: Output only. A URI for the image content.
          readOnly: true
        altText:
          type: string
          description: Alt text for the image.
          example: Survey header image
        properties:
          $ref: '#/components/schemas/MediaProperties'
        sourceUri:
          type: string
          description: The source URI for the image upload.
    DateQuestion:
      type: object
      description: A question that collects a date.
      properties:
        includeTime:
          type: boolean
          description: Whether to include a time component.
          example: false
        includeYear:
          type: boolean
          description: Whether to include a year component.
          example: true
    ImageItem:
      type: object
      description: A form item that displays an image.
      properties:
        image:
          $ref: '#/components/schemas/Image'
    Item:
      type: object
      description: A single item in a form which can be a question, text, image, video, or page break.
      properties:
        itemId:
          type: string
          description: The ID of the item.
          example: 4a5b6c7d
        title:
          type: string
          description: The title of the item.
          example: How satisfied are you with our service?
        description:
          type: string
          description: The description of the item.
          example: Please rate on a scale of 1-5
        questionItem:
          $ref: '#/components/schemas/QuestionItem'
        questionGroupItem:
          $ref: '#/components/schemas/QuestionGroupItem'
        pageBreakItem:
          type: object
          description: A page break item marking the start of a new page.
        textItem:
          type: object
          description: A text item displaying information.
        imageItem:
          $ref: '#/components/schemas/ImageItem'
        videoItem:
          $ref: '#/components/schemas/VideoItem'
    PublishSettings:
      type: object
      description: Settings controlling the publish state of the form.
      properties:
        isPublished:
          type: boolean
          description: Whether the form is published.
          example: true
        isAcceptingResponses:
          type: boolean
          description: Whether the form is currently accepting responses.
          example: true
    SetPublishSettingsRequest:
      type: object
      description: Request to set publish settings for a form.
      properties:
        publishSettings:
          $ref: '#/components/schemas/PublishSettings'
    RowQuestion:
      type: object
      description: A row in a question group (grid).
      properties:
        title:
          type: string
          description: The title of the row.
          example: Product Quality
  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