openapi: 3.0.3
info:
  title: Google Sheets Developer Metadata Spreadsheets API
  description: The Google Sheets API v4 is a RESTful interface that lets developers read and modify Google Spreadsheet data programmatically. Supports creating spreadsheets, reading and writing cell values by range (A1 notation), batch operations for efficiency, managing sheet structure and formatting, pivot tables, charts, and developer metadata. Authentication uses Google OAuth 2.0 with the sheets.readonly or sheets scope.
  version: 4.0.0
  termsOfService: https://developers.google.com/terms/
  contact:
    name: Google Workspace Developer Support
    url: https://developers.google.com/workspace/sheets/api
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://sheets.googleapis.com/v4
  description: Google Sheets API v4
security:
- OAuth2:
  - https://www.googleapis.com/auth/spreadsheets
  - https://www.googleapis.com/auth/spreadsheets.readonly
tags:
- name: Spreadsheets
  description: Spreadsheet-level operations
paths:
  /spreadsheets:
    post:
      operationId: create-spreadsheet
      tags:
      - Spreadsheets
      summary: Create Spreadsheet
      description: Creates a new spreadsheet, returning the newly created spreadsheet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpreadsheetRequest'
      responses:
        '200':
          description: Spreadsheet created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Spreadsheet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /spreadsheets/{spreadsheetId}:
    get:
      operationId: get-spreadsheet
      tags:
      - Spreadsheets
      summary: Get Spreadsheet
      description: Returns the spreadsheet at the given ID. The caller must specify the spreadsheet ID. By default, data within grids is not returned. Include the ranges request parameter to specify the data to retrieve.
      parameters:
      - name: spreadsheetId
        in: path
        description: The spreadsheet ID to retrieve
        required: true
        schema:
          type: string
          example: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
      - name: ranges
        in: query
        description: The ranges to retrieve from the spreadsheet
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: includeGridData
        in: query
        description: True if grid data should be returned
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Spreadsheet retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Spreadsheet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /spreadsheets/{spreadsheetId}:batchUpdate:
    post:
      operationId: batch-update-spreadsheet
      tags:
      - Spreadsheets
      summary: Batch Update Spreadsheet
      description: Applies one or more updates to the spreadsheet. Each request is validated before being applied. If any request is not valid then the entire request will fail and nothing will be applied.
      parameters:
      - name: spreadsheetId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateRequest'
      responses:
        '200':
          description: Batch update applied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    Sheet:
      type: object
      properties:
        properties:
          $ref: '#/components/schemas/SheetProperties'
    SpreadsheetProperties:
      type: object
      properties:
        title:
          type: string
          description: The title of the spreadsheet
          example: My Spreadsheet
        locale:
          type: string
          description: The locale of the spreadsheet (BCP 47 language tag)
          example: en_US
        timeZone:
          type: string
          description: The time zone of the spreadsheet (CLDR format)
          example: America/New_York
        autoRecalc:
          type: string
          enum:
          - ON_CHANGE
          - MINUTE
          - HOUR
          description: The amount of time to wait before volatile functions are recalculated
    SpreadsheetRequest:
      type: object
      description: Request body for creating a new spreadsheet
      properties:
        properties:
          $ref: '#/components/schemas/SpreadsheetProperties'
        sheets:
          type: array
          items:
            $ref: '#/components/schemas/Sheet'
    Spreadsheet:
      type: object
      description: A Google Sheets spreadsheet resource
      properties:
        spreadsheetId:
          type: string
          description: The ID of the spreadsheet
        properties:
          $ref: '#/components/schemas/SpreadsheetProperties'
        sheets:
          type: array
          items:
            $ref: '#/components/schemas/Sheet'
        spreadsheetUrl:
          type: string
          format: uri
          description: The URL of the spreadsheet
    BatchUpdateRequest:
      type: object
      properties:
        requests:
          type: array
          description: A list of updates to apply to the spreadsheet
          items:
            type: object
            description: A single kind of update to apply to a spreadsheet
        includeSpreadsheetInResponse:
          type: boolean
          description: Determines if the update response should include the spreadsheet resource
      required:
      - requests
    SheetProperties:
      type: object
      properties:
        sheetId:
          type: integer
          description: The ID of the sheet. Must be non-negative
        title:
          type: string
          description: The name of the sheet
          example: Sheet1
        index:
          type: integer
          description: The index of the sheet within the spreadsheet (0-indexed)
        sheetType:
          type: string
          enum:
          - GRID
          - OBJECT
          - DATA_SOURCE
          description: The type of sheet
        hidden:
          type: boolean
          description: True if the sheet is hidden in the UI
        gridProperties:
          type: object
          description: Grid-specific properties
          properties:
            rowCount:
              type: integer
              description: The number of rows in the grid
            columnCount:
              type: integer
              description: The number of columns in the grid
            frozenRowCount:
              type: integer
              description: The number of rows that are frozen
            frozenColumnCount:
              type: integer
              description: The number of columns that are frozen
    BatchUpdateResponse:
      type: object
      properties:
        spreadsheetId:
          type: string
        replies:
          type: array
          items:
            type: object
        updatedSpreadsheet:
          $ref: '#/components/schemas/Spreadsheet'
    Error:
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Human-readable error message
        status:
          type: string
          description: Error status
  responses:
    Unauthorized:
      description: Authentication required or access token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Spreadsheet or range not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient permissions to access this spreadsheet
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/spreadsheets: Read and write access to Google Sheets
            https://www.googleapis.com/auth/spreadsheets.readonly: Read-only access to Google Sheets
externalDocs:
  description: Google Sheets API Documentation
  url: https://developers.google.com/workspace/sheets/api