Sheets DB API

Google Cloud Function that proxies requests to Google Sheets API, treating sheets as database tables

Base URL: https://sheetsapi-g56q77hy2a-uc.a.run.app

Getting Started

Authentication

All requests require the X-Spreadsheet-Id header containing your Google Sheets spreadsheet ID.

Data Format

The API uses JSON for request and response bodies. Row data is represented as key-value objects where keys are column headers.

Row Indexing

Rows are 1-indexed in the API. Row 1 contains headers, so data rows start at index 2.

Sheet Access

Share your Google Sheet with the API service account to grant access:



Grant Editor access to allow the API to read and write data.

Health

GET /health Health check

Returns the health status of the API

Responses

200
application/json 
{
  "status": "ok"
}

Example

cURL 
curl -X GET 'https://sheetsapi-g56q77hy2a-uc.a.run.app/health' \
  -H 'Content-Type: application/json'

Sheets

GET /sheets List all sheets

Returns a list of all sheets in the spreadsheet

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID

Responses

200 400 500
application/json 
{
  "sheets": [
    {
      "sheetId": 0,
      "title": "Users",
      "index": 0
    }
  ]
}

Example

cURL 
curl -X GET 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms'
POST /sheets Create a new sheet

Creates a new sheet in the spreadsheet

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID

Request Body

application/json 
{
  "name": "NewSheet"
}

Responses

201 400 500
application/json 
{
  "sheet": {
    "sheetId": 0,
    "title": "Users",
    "index": 0
  }
}

Example

cURL 
curl -X POST 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms' \
  -d '{  "name": "NewSheet"}'
DELETE /sheets/{sheetName} Delete a sheet

Deletes a sheet from the spreadsheet

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet

Responses

204 400 404 500
application/json 
// No content

Example

cURL 
curl -X DELETE 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms'
GET /sheets/{sheetName}/schema Get sheet schema

Returns the column headers (first row) of the sheet

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet

Responses

200 400 500
application/json 
{
  "columns": [
    "id",
    "name",
    "email",
    "created_at"
  ]
}

Example

cURL 
curl -X GET 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/schema' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms'

Rows

GET /sheets/{sheetName}/rows Get all rows

Returns all rows from the sheet (excluding header row)

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet

Responses

200 400 500
application/json 
{
  "rows": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "active": true
    }
  ]
}

Example

cURL 
curl -X GET 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/rows' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms'
POST /sheets/{sheetName}/rows Create a new row

Appends a new row to the sheet. If the sheet is empty, creates headers from the object keys.

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet

Request Body

application/json 
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "active": true
}

Responses

201 400 500
application/json 
{
  "rowIndex": 5
}

Example

cURL 
curl -X POST 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/rows' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms' \
  -d '{  "id": 1,  "name": "John Doe",  "email": "john@example.com",  "active": true}'
POST /sheets/{sheetName}/rows/bulk Create multiple rows

Creates multiple rows in a single request. Accepts 1-1000 rows. If the sheet is empty, creates headers from the first row's keys.

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet

Request Body

application/json 
{
  "rows": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com",
      "age": 30
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com",
      "age": 25
    }
  ]
}

Responses

201 400 500
application/json 
{
  "rows": [
    {
      "rowIndex": 5,
      "data": {
        "id": 1,
        "name": "Alice",
        "email": "alice@example.com",
        "age": 30
      }
    },
    {
      "rowIndex": 6,
      "data": {
        "id": 2,
        "name": "Bob",
        "email": "bob@example.com",
        "age": 25
      }
    }
  ]
}

Example

cURL 
curl -X POST 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/rows/bulk' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms' \
  -d '{  "rows": [    {      "id": 1,      "name": "Alice",      "email": "alice@example.com",      "age": 30    },    {      "id": 2,      "name": "Bob",      "email": "bob@example.com",      "age": 25    }  ]}'
PUT /sheets/{sheetName}/rows/bulk Bulk update rows

Update multiple rows by row index with partial data merge behavior. Only updates specified fields, leaving other columns unchanged.

Parameters

Name Type Location Description
sheetName required string path The name of the sheet (tab) within the spreadsheet
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID

Request Body

application/json 
{
  "rows": [
    {
      "rowIndex": 5,
      "data": {
        "name": "Alice Updated",
        "age": 31
      }
    }
  ]
}

Responses

200 400 500
application/json 
{
  "rows": [
    {
      "rowIndex": 5,
      "data": {
        "id": 1,
        "name": "Alice Updated",
        "email": "alice@example.com",
        "age": 31
      }
    }
  ]
}

Example

cURL 
curl -X PUT 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/rows/bulk' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms' \
  -d '{  "rows": [    {      "rowIndex": 5,      "data": {        "name": "Alice Updated",        "age": 31      }    }  ]}'
GET /sheets/{sheetName}/rows/{rowIndex} Get a specific row

Returns a single row by its index (1-indexed, must be >= 2 since row 1 contains headers)

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet
rowIndex required integer path The 1-indexed row number (must be >= 2, since row 1 contains headers)

Responses

200 400 404 500
application/json 
{
  "row": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "active": true
  }
}

Example

cURL 
curl -X GET 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/rows/{rowIndex}' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms'
PUT /sheets/{sheetName}/rows/{rowIndex} Update a row

Updates an existing row by its index

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet
rowIndex required integer path The 1-indexed row number (must be >= 2, since row 1 contains headers)

Request Body

application/json 
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "active": true
}

Responses

204 400 500
application/json 
// No content

Example

cURL 
curl -X PUT 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/rows/{rowIndex}' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms' \
  -d '{  "id": 1,  "name": "John Doe",  "email": "john@example.com",  "active": true}'
DELETE /sheets/{sheetName}/rows/{rowIndex} Delete a row

Deletes a row by its index

Parameters

Name Type Location Description
X-Spreadsheet-Id required string header The Google Sheets spreadsheet ID
sheetName required string path The name of the sheet (tab) within the spreadsheet
rowIndex required integer path The 1-indexed row number (must be >= 2, since row 1 contains headers)

Responses

204 400 500
application/json 
// No content

Example

cURL 
curl -X DELETE 'https://sheetsapi-g56q77hy2a-uc.a.run.app/sheets/{sheetName}/rows/{rowIndex}' \
  -H 'Content-Type: application/json' \
  -H 'X-Spreadsheet-Id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms'