openapi: 3.0.3
info:
  title: Zoho Sheet Data Workbook API
  description: 'REST API for reading, writing, and manipulating Zoho Sheet spreadsheet data. Supports workbook management, worksheet operations, cell content manipulation, chart management, tabular data operations, pivot tables, and merge templates. Authentication uses OAuth 2.0 with scopes for read and update access. All data API requests use POST with a method parameter to specify the operation.

    '
  version: v2
  contact:
    name: Zoho Sheet Support
    url: https://sheet.zoho.com/help/api/v2/
  termsOfService: https://www.zoho.com/terms.html
  license:
    name: Zoho API Terms
    url: https://www.zoho.com/terms.html
servers:
- url: https://sheet.zoho.com/api/v2
  description: Zoho Sheet API server (US)
- url: https://sheet.zoho.eu/api/v2
  description: Zoho Sheet API server (EU)
- url: https://sheet.zoho.com.au/api/v2
  description: Zoho Sheet API server (AU)
- url: https://sheet.zoho.in/api/v2
  description: Zoho Sheet API server (IN)
security:
- oauthToken: []
tags:
- name: Workbook
  description: Operations on Zoho Sheet workbooks (spreadsheet files)
paths:
  /{resource_id}:
    post:
      summary: Zoho Sheet Data API dispatcher
      description: 'All Zoho Sheet Data API operations are dispatched via POST to the resource URL. The specific operation is controlled by the `method` form parameter. The resource_id is the unique identifier of the spreadsheet (workbook).

        '
      operationId: dispatchSheetOperation
      tags:
      - Workbook
      parameters:
      - name: resource_id
        in: path
        required: true
        description: Unique identifier of the Zoho Sheet workbook (resource_id from the spreadsheet URL)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
              - $ref: '#/components/schemas/ReadSpreadsheetRequest'
              - $ref: '#/components/schemas/WriteSpreadsheetRequest'
              - $ref: '#/components/schemas/GetSpreadsheetContentRequest'
              - $ref: '#/components/schemas/AddWorksheetRequest'
              - $ref: '#/components/schemas/RenameWorksheetRequest'
              - $ref: '#/components/schemas/DeleteWorksheetRequest'
              - $ref: '#/components/schemas/ReadTabularDataRequest'
              - $ref: '#/components/schemas/WriteTabularDataRequest'
      responses:
        '200':
          description: Successful API response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Bad request - missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or expired OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient scope or permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded - API calls blocked for 5 minutes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - oauthToken:
        - ZohoSheet.dataAPI.READ
components:
  schemas:
    WriteTabularDataRequest:
      type: object
      description: Request parameters for writing tabular data
      required:
      - method
      - worksheet_name
      - json_data
      properties:
        method:
          type: string
          enum:
          - tabular_range.records.add
          - tabular_range.records.update
          - tabular_range.records.delete
          description: API method identifier for modifying tabular range records
        worksheet_name:
          type: string
          description: Name of the worksheet containing the tabular data
        json_data:
          type: string
          description: JSON string of row data to add or update
        criteria:
          type: string
          description: JSON string filter criteria identifying rows to update or delete
    DeleteWorksheetRequest:
      type: object
      description: Request parameters for deleting a worksheet
      required:
      - method
      - worksheet_name
      properties:
        method:
          type: string
          enum:
          - worksheet.delete
          description: API method identifier for deleting a worksheet
        worksheet_name:
          type: string
          description: Name of the worksheet to delete
    ReadSpreadsheetRequest:
      type: object
      description: Request parameters for reading spreadsheet cell data
      required:
      - method
      - worksheet_name
      properties:
        method:
          type: string
          enum:
          - worksheet.records.fetch
          description: API method identifier for reading worksheet records
        worksheet_name:
          type: string
          description: Name of the worksheet to read from
        header_row:
          type: integer
          description: Row number to treat as header (1-indexed)
          default: 1
        start_row_index:
          type: integer
          description: Row index to start reading from (1-indexed)
        row_count:
          type: integer
          description: Number of rows to read
        start_column_index:
          type: integer
          description: Column index to start reading from (1-indexed)
        column_count:
          type: integer
          description: Number of columns to read
    ErrorResponse:
      type: object
      description: Error response from Zoho Sheet Data API
      properties:
        status:
          type: string
          enum:
          - failure
          description: Always "failure" for error responses
        error_code:
          type: integer
          description: Numeric error code
          example: 2862
        error_message:
          type: string
          description: Human-readable error description
      example:
        status: failure
        error_code: 2862
        error_message: Workbook not found
    GetSpreadsheetContentRequest:
      type: object
      description: Request parameters for getting spreadsheet content/metadata
      required:
      - method
      properties:
        method:
          type: string
          enum:
          - workbook.data.get
          description: API method identifier for getting workbook content
        worksheet_name:
          type: string
          description: Optional worksheet name to filter content
    AddWorksheetRequest:
      type: object
      description: Request parameters for adding a new worksheet
      required:
      - method
      - new_sheet_name
      properties:
        method:
          type: string
          enum:
          - worksheet.create
          description: API method identifier for creating a worksheet
        new_sheet_name:
          type: string
          description: Name for the new worksheet
        sheet_index:
          type: integer
          description: Position index for the new worksheet
    WriteSpreadsheetRequest:
      type: object
      description: Request parameters for writing cell data to a spreadsheet
      required:
      - method
      - worksheet_name
      - cell_data
      properties:
        method:
          type: string
          enum:
          - worksheet.records.add
          - worksheet.records.update
          description: API method identifier for writing worksheet records
        worksheet_name:
          type: string
          description: Name of the worksheet to write to
        header_row:
          type: integer
          description: Row number treated as header (1-indexed)
          default: 1
        cell_data:
          type: string
          description: JSON string array of row data objects to write
    ReadTabularDataRequest:
      type: object
      description: Request parameters for reading tabular (structured) data
      required:
      - method
      - worksheet_name
      properties:
        method:
          type: string
          enum:
          - tabular_range.records.fetch
          description: API method identifier for fetching tabular range records
        worksheet_name:
          type: string
          description: Name of the worksheet containing the tabular data
        criteria:
          type: string
          description: JSON string filter criteria for rows
        sort_column:
          type: string
          description: Column name to sort results by
        sort_order:
          type: string
          enum:
          - asc
          - desc
          description: Sort order direction
        start_row_index:
          type: integer
          description: Starting row index for pagination
        row_count:
          type: integer
          description: Number of rows to return for pagination
    RenameWorksheetRequest:
      type: object
      description: Request parameters for renaming a worksheet
      required:
      - method
      - old_sheet_name
      - new_sheet_name
      properties:
        method:
          type: string
          enum:
          - worksheet.rename
          description: API method identifier for renaming a worksheet
        old_sheet_name:
          type: string
          description: Current name of the worksheet
        new_sheet_name:
          type: string
          description: New name for the worksheet
    ApiResponse:
      type: object
      description: Standard successful response from Zoho Sheet Data API
      properties:
        status:
          type: string
          enum:
          - success
          - failure
          description: Indicates whether the operation succeeded
        spreadsheet_name:
          type: string
          description: Name of the spreadsheet
        worksheet_name:
          type: string
          description: Name of the worksheet (for worksheet-scoped operations)
        header_row:
          type: integer
          description: Header row index used for the operation
        records:
          type: array
          description: Array of data records returned by read operations
          items:
            type: object
            additionalProperties: true
        total_row_count:
          type: integer
          description: Total number of data rows in the worksheet
        worksheet_list:
          type: array
          description: List of worksheet names in the workbook
          items:
            type: object
            properties:
              sheet_name:
                type: string
              sheet_index:
                type: integer
  securitySchemes:
    oauthToken:
      type: oauth2
      description: Zoho OAuth 2.0 authentication
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          refreshUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            ZohoSheet.dataAPI.READ: Read spreadsheet data
            ZohoSheet.dataAPI.UPDATE: Write and update spreadsheet data
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoSheet.dataAPI.READ: Read spreadsheet data
            ZohoSheet.dataAPI.UPDATE: Write and update spreadsheet data
        clientCredentials:
          tokenUrl: https://accounts.zoho.com/oauth/v3/device/token
          scopes:
            ZohoSheet.dataAPI.READ: Read spreadsheet data
            ZohoSheet.dataAPI.UPDATE: Write and update spreadsheet data
externalDocs:
  description: Zoho Sheet Data API v2 Documentation
  url: https://sheet.zoho.com/help/api/v2/