API Documentation

This API allows you to interact with Google Sheets through various endpoints. You can perform operations such as retrieving data, managing sheets and tabs, manipulating rows and columns, handling cells, and importing/exporting data.

Authentication

All API requests require an API key, which must be included in the request parameters. The API key is specific to your user account and can be obtained from your account settings.

Required Parameter

Parameter Type Description
apiKey string Your API key

Base URL

All endpoints are prefixed with /v1 and are accessible via:

https://sheets.systems/api/v1

Endpoints

Legacy/Basic Operations

GET /sheets/{sheetId}

Get Data

Retrieve data from a specific Google Sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
range string Optional. The cell range to retrieve (e.g., A1:C10)
Example Request
curl -X GET "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms?apiKey=YOUR_API_KEY&sheetName=Sheet1&range=A1:C10"
Response Example
{
  "success": true,
  "data": [
    {
      "Column1": "Value1",
      "Column2": "Value2",
      "Column3": "Value3"
    }
  ]
}
GET /sheets/{sheetId}/info

Get Sheet Info

Retrieve metadata about a Google Sheet, including sheet names and optionally headers.

Legacy/Basic Operations

GET /sheets/{sheetId}

Get Data

Retrieve data from a specific Google Sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
range string Optional. The cell range to retrieve (e.g., A1:C10)
Example Request
curl -X GET "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms?apiKey=YOUR_API_KEY&sheetName=Sheet1&range=A1:C10"
Response Example
{
  "success": true,
  "data": [
    {
      "Column1": "Value1",
      "Column2": "Value2",
      "Column3": "Value3"
    }
  ]
}
GET /sheets/{sheetId}/info

Get Sheet Info

Retrieve metadata about a Google Sheet, including sheet names and optionally headers.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
includeHeaders boolean Optional. Whether to include headers for each sheet
Example Request
curl -X GET "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/info?apiKey=YOUR_API_KEY&includeHeaders=true"
Response Example
{
  "success": true,
  "data": {
    "sheets": [
      {
        "sheetId": 0,
        "title": "Sheet1",
        "headers": ["Column1", "Column2", "Column3"]
      }
    ]
  }
}

Sheet (Tab) Management

POST /sheets/{sheetId}/tabs

Create Sheet

Create a new sheet (tab) within an existing Google Sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
title string The title of the new sheet
Example Request
curl -X POST "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/tabs" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "title": "NewSheet"
    }'
Response Example
{
  "success": true,
  "message": "Sheet created successfully",
  "data": {
    "sheetId": 123456789,
    "title": "NewSheet"
  }
}
DELETE /sheets/{sheetId}/tabs/{tabId}

Delete Sheet

Delete an existing sheet (tab) from a Google Sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
tabId integer The ID of the tab to delete
apiKey string Your API key
Example Request
curl -X DELETE "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/tabs/123456789?apiKey=YOUR_API_KEY"
Response Example
{
  "success": true,
  "message": "Sheet deleted successfully"
}
PATCH /sheets/{sheetId}/tabs/{tabId}/rename

Rename Sheet

Rename an existing sheet (tab) within a Google Sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
tabId integer The ID of the tab to rename
apiKey string Your API key
newTitle string The new title for the sheet
Example Request
curl -X PATCH "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/tabs/123456789/rename" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "newTitle": "RenamedSheet"
    }'
Response Example
{
  "success": true,
  "message": "Sheet renamed successfully",
  "data": {
    "sheetId": 123456789,
    "title": "RenamedSheet"
  }
}

Row Operations

GET /sheets/{sheetId}/rows/find

Find Row

Find a row in a sheet based on criteria.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
criteria object Key-value pairs to match against rows
Example Request
curl -X GET "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/rows/find?apiKey=YOUR_API_KEY&sheetName=Sheet1&criteria[name]=John&criteria[age]=30"
Response Example
{
  "success": true,
  "data": {
    "rowNumber": 5,
    "rowData": {
      "name": "John",
      "age": "30",
      "email": "john@example.com"
    }
  }
}
PUT /sheets/{sheetId}/rows/update-by-criteria

Update Row by Criteria

Update a row in a sheet based on criteria.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
criteria object Key-value pairs to match against rows
updates object Key-value pairs of data to update
Example Request
curl -X PUT "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/rows/update-by-criteria" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sheetName": "Sheet1",
        "criteria": {
            "email": "john@example.com"
        },
        "updates": {
            "age": "31"
        }
    }'
Response Example
{
  "success": true,
  "message": "Row updated successfully"
}
DELETE /sheets/{sheetId}/rows/delete-by-criteria

Delete Row by Criteria

Delete a row in a sheet based on criteria.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
criteria object Key-value pairs to match against rows
Example Request
curl -X DELETE "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/rows/delete-by-criteria" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sheetName": "Sheet1",
        "criteria": {
            "email": "john@example.com"
        }
    }'
Response Example
{
  "success": true,
  "message": "Row deleted successfully"
}
POST /sheets/{sheetId}/rows/batch

Batch Update

Perform batch updates on multiple rows.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
operations array Array of operation objects containing criteria and updates
Example Request
curl -X POST "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/rows/batch" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sheetName": "Sheet1",
        "operations": [
            {
                "criteria": {"email": "john@example.com"},
                "updates": {"age": "31"}
            },
            {
                "criteria": {"email": "jane@example.com"},
                "updates": {"age": "28"}
            }
            ]
    }'
Response Example
{
  "success": true,
  "results": [
    {
      "index": 0,
      "success": true,
      "message": "Updated successfully"
    },
    {
      "index": 1,
      "success": true,
      "message": "Updated successfully"
    }
  ]
}

Column Operations

GET /sheets/{sheetId}/columns

Get Columns

Retrieve the list of columns (headers) in a sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
Example Request
curl -X GET "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/columns?apiKey=YOUR_API_KEY&sheetName=Sheet1"
Response Example
{
  "success": true,
  "data": ["name", "age", "email"]
}
POST /sheets/{sheetId}/columns

Add Column

Add a new column to a sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
columnName string The name of the new column
defaultValue string Optional. The default value for existing rows
Example Request
curl -X POST "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/columns" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sheetName": "Sheet1",
        "columnName": "phone",
        "defaultValue": ""
    }'
Response Example
{
  "success": true,
  "message": "Column added successfully",
  "data": {
    "columnName": "phone"
  }
}
DELETE /sheets/{sheetId}/columns

Delete Column

Delete a column from a sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
columnName string The name of the column to delete
Example Request
curl -X DELETE "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/columns" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sheetName": "Sheet1",
        "columnName": "phone"
    }'
Response Example
{
  "success": true,
  "message": "Column deleted successfully"
}
PATCH /sheets/{sheetId}/columns/rename

Rename Column

Rename a column in a sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
oldColumnName string The current name of the column
newColumnName string The new name for the column
Example Request
curl -X PATCH "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/columns/rename" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sheetName": "Sheet1",
        "oldColumnName": "phone",
        "newColumnName": "contactNumber"
    }'
Response Example
{
  "success": true,
  "message": "Column renamed successfully",
  "data": {
    "oldColumnName": "phone",
    "newColumnName": "contactNumber"
  }
}

Cell Operations

GET /sheets/{sheetId}/cells

Get Cell Value

Retrieve the value of a specific cell.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
cell string The cell identifier (e.g., A1, B2)
Example Request
curl -X GET "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/cells?apiKey=YOUR_API_KEY&sheetName=Sheet1&cell=B2"
Response Example
{
  "success": true,
  "data": {
    "sheet_name": "Sheet1",
    "cell": "B2",
    "value": "John"
  }
}
PATCH /sheets/{sheetId}/cells

Update Cell Value

Update the value of a specific cell.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
cell string The cell identifier (e.g., A1, B2)
value string The new value for the cell
Example Request
curl -X PATCH "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/cells" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sheetName": "Sheet1",
        "cell": "B2",
        "value": "Jane"
    }'
Response Example
{
  "success": true,
  "message": "Cell value updated successfully",
  "data": {
    "sheet_name": "Sheet1",
    "cell": "B2",
    "value": "Jane"
  }
}

Data Import/Export

POST /sheets/{sheetId}/import

Import CSV

Import data from a CSV file into a sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
csvFile file The CSV file to import
hasHeader boolean Optional. Whether the CSV file includes a header row
Example Request
curl -X POST "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/import" \
    -F "apiKey=YOUR_API_KEY" \
    -F "sheetName=Sheet1" \
    -F "csvFile=@/path/to/yourfile.csv" \
    -F "hasHeader=true"
Response Example
{
  "success": true,
  "message": "CSV imported successfully",
  "data": {
    "sheetName": "Sheet1",
    "rowsImported": 100,
    "columnsImported": 5,
    "failedRows": []
  }
}
GET /sheets/{sheetId}/export

Export CSV

Export data from a sheet to a CSV file.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sheetName string Optional. The name of the sheet (tab)
Example Request
curl -X GET "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/export?apiKey=YOUR_API_KEY&sheetName=Sheet1"
Response Example
{
  "success": true,
  "message": "CSV file generated successfully",
  "data": {
    "file_url": "https://sheets.systems/storage/exports/sheet1_5f4dcc3b5aa765d61d8327deb882cf99_2021-08-01_123456.csv",
    "filename": "sheet1_5f4dcc3b5aa765d61d8327deb882cf99_2021-08-01_123456.csv",
    "rows_count": 100,
    "columns_count": 5,
    "file_size": {
      "bytes": 2048,
      "formatted": "2 KB"
    },
    "expiry": {
      "timestamp": 1627833600,
      "formatted": "2021-08-01T12:00:00+00:00",
      "human_readable": "in 24 hours"
    }
  }
}
POST /sheets/{sheetId}/copy

Copy Sheet

Copy an existing sheet (tab) within a Google Sheet to a new sheet.

Parameters
Parameter Type Description
sheetId string The ID of the Google Sheet
apiKey string Your API key
sourceSheetName string Optional. The name of the source sheet to copy
targetSheetName string The name of the new sheet to create
Example Request
curl -X POST "https://sheets.systems/api/v1/sheets/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/copy" \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "YOUR_API_KEY",
        "sourceSheetName": "Sheet1",
        "targetSheetName": "Sheet1_Copy"
    }'
Response Example
{
  "success": true,
  "message": "Sheet copied successfully",
  "data": {
    "sourceSheet": "Sheet1",
    "targetSheet": "Sheet1_Copy",
    "rowsCopied": 100,
    "failedRows": []
  }
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request.

Status Code Description
200 The request was successful
400 Bad Request - The request was invalid
401 Unauthorized - Invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Rate Limiting

The API enforces rate limits to prevent abuse. By default, the rate limit is:

  • 60 requests per minute

If you exceed this limit, you will receive a 429 Too Many Requests response.

Changelog

Version 1.0

  • Initial release with support for sheet data retrieval
  • Sheet management functionality
  • Row and column operations
  • Cell manipulation
  • Data import/export capabilities