API Reference

Read and write data in your connected Google Sheets via REST API. Authenticate with an API key created in the Sheet Gurus dashboard. ## Row IDs The **first column** of your sheet is treated as the row identifier. When accessing individual rows via `/v1/data/{sheetId}/{rowId}`, the `rowId` is matched against values in the first column. You can use the `auto_id` option when creating rows to automatically generate a UUID-based `id` column as the first column.

Base URL

https://api.sheetgurus.com

Authentication

Pass your API key in the X-API-Key header

GET/v1/data/{sheetId}

Read rows

Retrieve rows from a sheet. Supports pagination, sorting, and filtering. Results are cached for 15 seconds.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)
`limit`	query	integer	Max rows to return (default 100, max 1000)(default: 100)(max: 1000)
`offset`	query	integer	Number of rows to skip for pagination(default: 0)
`sort_by`	query	string	Column name to sort by
`sort_order`	query	string	Sort direction (default asc)(asc \| desc)
`filter[column]`	query	string	Filter rows by column value (case-insensitive exact match). Use one filter param per column, e.g. ?filter[status]=active&filter[category]=Electronics

Success Response (200)

Sheet data with pagination metadata

{
  "data": [
    {
      "id": "1",
      "name": "Widget Pro",
      "price": "29.99",
      "in_stock": "true"
    },
    {
      "id": "2",
      "name": "Gadget Plus",
      "price": "49.99",
      "in_stock": "true"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 100,
    "offset": 0,
    "headers": [
      "id",
      "name",
      "price",
      "in_stock"
    ]
  }
}

Error Responses

Status	Description
`401`	Invalid or missing API key
`403`	API key or sheet does not have read permission

POST/v1/data/{sheetId}

Create rows

Append one or more new rows to the sheet.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Request Body

Field	Type	Description
`data`*	array	Array of row objects to create
`auto_id`	boolean	When true, automatically creates an 'id' column (if not present) and populates it with a UUID for each new row

Example Request Body

{
  "data": [
    {
      "name": "New Item",
      "price": "19.99",
      "in_stock": "true"
    }
  ],
  "auto_id": true
}

Success Response (201)

Rows created successfully

Error Responses

Status	Description
`400`	Invalid request (missing data, invalid format, unknown columns)
`401`	Invalid or missing API key
`403`	API key or sheet does not have write permission

PATCH/v1/data/{sheetId}

Bulk update rows

Update all rows matching a where clause. Both where and data are required.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Request Body

Field	Type	Description
`where`*	object	Column-value pairs to match rows (AND logic, case-insensitive)
`data`*	object	Fields to update on matched rows

Example Request Body

{
  "where": {
    "category": "Electronics"
  },
  "data": {
    "in_stock": "false"
  }
}

Success Response (200)

Matched rows updated

Error Responses

Status	Description
`400`	Invalid request (empty where/data, unknown columns)
`401`	Invalid or missing API key
`403`	API key or sheet does not have update permission

DELETE/v1/data/{sheetId}

Bulk delete rows

Delete all rows matching a where clause.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Request Body

Field	Type	Description
`where`*	object	Column-value pairs to match rows to delete (AND logic, case-insensitive)

Example Request Body

{
  "where": {
    "category": "Discontinued"
  }
}

Success Response (200)

Matched rows deleted

Error Responses

Status	Description
`400`	Invalid request (empty where clause)
`401`	Invalid or missing API key
`403`	API key or sheet does not have delete permission

POST/v1/data/{sheetId}/columns

Add columns

Add new columns to a sheet. Column names must be unique and non-empty.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Request Body

Field	Type	Description
`columns`*	array	Column names to add to the sheet

Example Request Body

{
  "columns": [
    "category",
    "sku"
  ]
}

Success Response (201)

Columns added successfully

Error Responses

Status	Description
`400`	Invalid request (empty or duplicate column names)
`401`	Invalid or missing API key
`403`	API key or sheet does not have write permission

GET/v1/data/{sheetId}/{rowId}

Get row

Retrieve a single row by its ID (the value in the first column).

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`rowId`*	path	string	Row ID — the value in the first column of the sheet for the target row
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Success Response (200)

Row data

Error Responses

Status	Description
`401`	Invalid or missing API key
`403`	API key or sheet does not have read permission
`404`	No row found with the given ID in the first column

PUT/v1/data/{sheetId}/{rowId}

Replace row

Replace all fields of a row. The row ID (first column) is preserved; all other columns are overwritten with the provided data.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`rowId`*	path	string	Row ID — the value in the first column of the sheet for the target row
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Request Body

Field	Type	Description
`data`*	object	Complete row data (all columns except the ID column)

Success Response (200)

Row replaced

Error Responses

Status	Description
`400`	Invalid request (missing data, unknown columns)
`401`	Invalid or missing API key
`403`	API key or sheet does not have update permission
`404`	No row found with the given ID

PATCH/v1/data/{sheetId}/{rowId}

Update row

Update specific fields of a row. Only the provided columns are changed; other columns are left untouched. The row ID (first column) cannot be changed.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`rowId`*	path	string	Row ID — the value in the first column of the sheet for the target row
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Request Body

Field	Type	Description
`data`*	object	Fields to update (partial — only include columns you want to change)

Success Response (200)

Row updated

Error Responses

Status	Description
`400`	Invalid request (missing data, unknown columns)
`401`	Invalid or missing API key
`403`	API key or sheet does not have update permission
`404`	No row found with the given ID

DELETE/v1/data/{sheetId}/{rowId}

Delete row

Delete a single row by its ID.

Parameters

Parameter	In	Type	Description
`sheetId`*	path	string	The sheet ID (UUID from the dashboard)
`rowId`*	path	string	Row ID — the value in the first column of the sheet for the target row
`tab`	query	string	Tab name within the spreadsheet (defaults to first tab)

Success Response (200)

Row deleted

Error Responses

Status	Description
`401`	Invalid or missing API key
`403`	API key or sheet does not have delete permission
`404`	No row found with the given ID