Google Sheets API

This page documents the public API for reading and changing Google Sheets. Connect the Google account once, then call the same endpoint for all sheet and spreadsheet actions.

Connect

Create a short-lived connection ticket:

curl -X POST https://auth.genium.one/api/social/connect-ticket \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"sheets"}'

Open the returned connect_url in a browser. The Google OAuth callback is:

https://auth.genium.one/callback/sheets

List connected Google accounts:

curl https://auth.genium.one/api/google/sheets/accounts \
  -H "Authorization: Bearer $USER_API_KEY"

Endpoint and authentication

POST https://auth.genium.one/api/google/sheets
Authorization: Bearer <USER_API_KEY>
Content-Type: application/json

Every request returns an envelope containing operation and result. Errors return an error string and an HTTP error status.

Optional Idempotency-Key headers are recommended for writes. Reusing the same key returns the original response instead of performing the write twice.

Common fields

Field	Type	Used by	Description
resource	sheet or spreadsheet	All	Defaults to sheet.
operation	string	All	The action to run.
account_id	number	All	Selects a connected Google account.
spreadsheet_id	string	Existing spreadsheet actions	Google spreadsheet ID.
sheet	string	Read/write values	Tab title, for example Sheet1.
sheet_id	number	Tab/row/column actions	Numeric tab gid.
range	string	Read, append, update, clear	A1 range such as A2:Z.

Options

Cell format

Use options.cell_format for writes:

Value	Meaning
USER_ENTERED	Google interprets values as entered by a user.
RAW	Google stores values without interpretation.

The legacy top-level value_input_mode field is also supported. If both are present, value_input_mode wins.

Header row

Object rows use the selected header row to map property names to columns:

{
  "options": { "header_row": 2 }
}

The default is row 1. The legacy top-level header_row field is also supported and wins over options.header_row.

Minimise API calls

For append with object rows, set options.minimise_api_calls to true and provide columns. Genium can then write directly without first reading the header row:

{
  "options": {
    "cell_format": "USER_ENTERED",
    "header_row": 1,
    "minimise_api_calls": true
  },
  "columns": ["video_id", "status", "permalink"],
  "rows": [
    {
      "video_id": "123",
      "status": "published",
      "permalink": "https://example.com/post"
    }
  ]
}

appendOrUpdate must read existing rows to locate the key, so this option does not remove that required lookup.

1. Read rows

Returns both raw values and mapped rows. The selected header row becomes the object key for each returned row.

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"read","spreadsheet_id":"SPREADSHEET_ID","sheet":"Sheet1","range":"A:Z"}'

Optional render field:

{
  "value_render_mode": "FORMATTED_VALUE"
}

Allowed values are FORMATTED_VALUE, UNFORMATTED_VALUE, and FORMULA.

2. Append rows

Object rows map to the existing header names:

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-append-001" \
  -H "Content-Type: application/json" \
  -d '{"operation":"append","spreadsheet_id":"SPREADSHEET_ID","sheet":"Sheet1","rows":[{"video_id":"123","status":"queued","permalink":null}]}'

Or send values directly without header mapping:

{
  "operation": "append",
  "spreadsheet_id": "SPREADSHEET_ID",
  "sheet": "Sheet1",
  "values": [["123", "queued", null]]
}

3. Update a range

update writes a specific A1 range and requires values:

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-update-001" \
  -H "Content-Type: application/json" \
  -d '{"operation":"update","spreadsheet_id":"SPREADSHEET_ID","sheet":"Sheet1","range":"A2:C2","values":[["123","published","https://example.com/post"]]}'

4. Append or update

appendOrUpdate updates rows whose key exists and appends rows whose key is missing. It requires key_column and object rows:

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-upsert-001" \
  -H "Content-Type: application/json" \
  -d '{"operation":"appendOrUpdate","spreadsheet_id":"SPREADSHEET_ID","sheet":"Sheet1","key_column":"video_id","rows":[{"video_id":"123","status":"published","permalink":"https://example.com/post"}]}'

The response includes updated, appended, updated_rows, and appended_rows.

5. Clear values

Clears cell values without deleting rows, columns, formatting, or the tab:

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-clear-001" \
  -H "Content-Type: application/json" \
  -d '{"operation":"clear","spreadsheet_id":"SPREADSHEET_ID","sheet":"Sheet1","range":"A2:Z"}'

6. Create a sheet tab

Creates a tab inside an existing spreadsheet. The response includes the new numeric sheet_id.

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-create-tab-001" \
  -H "Content-Type: application/json" \
  -d '{"resource":"sheet","operation":"create","spreadsheet_id":"SPREADSHEET_ID","title":"Published"}'

Optional create fields: index, hidden, right_to_left, tab_color, and sheet_id.

7. Delete rows or columns

Physically removes rows or columns. start_row is 1-based; column positions use A1 letters. sheet_id is the numeric tab gid.

Delete one row:

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-delete-row-001" \
  -H "Content-Type: application/json" \
  -d '{"resource":"sheet","operation":"delete","spreadsheet_id":"SPREADSHEET_ID","sheet_id":0,"dimension":"ROWS","start_row":2,"count":1}'

Delete columns B through C:

{
  "resource": "sheet",
  "operation": "delete",
  "spreadsheet_id": "SPREADSHEET_ID",
  "sheet_id": 0,
  "dimension": "COLUMNS",
  "start_column": "B",
  "count": 2
}

8. Remove a sheet tab

Permanently deletes a tab. This only needs the numeric sheet_id; sheet is not required.

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-remove-tab-001" \
  -H "Content-Type: application/json" \
  -d '{"resource":"sheet","operation":"remove","spreadsheet_id":"SPREADSHEET_ID","sheet_id":123456}'

9. Create a spreadsheet

Creates a new Google spreadsheet and returns its spreadsheetId and URL:

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-create-spreadsheet-001" \
  -H "Content-Type: application/json" \
  -d '{"resource":"spreadsheet","operation":"create","title":"Genium Content Log"}'

10. Delete a spreadsheet

Permanently deletes the spreadsheet through Google Drive permission:

curl -X POST https://auth.genium.one/api/google/sheets \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Idempotency-Key: sheets-delete-spreadsheet-001" \
  -H "Content-Type: application/json" \
  -d '{"resource":"spreadsheet","operation":"deleteSpreadsheet","spreadsheet_id":"SPREADSHEET_ID"}'

Limits and errors

• rows: up to 1,000 object rows per request.
• values: up to 1,000 rows and 100 columns per request.
• sheet: up to 100 characters.
• Invalid requests return HTTP 400.
• Missing connected account returns HTTP 404.
• Missing Sheets OAuth scope returns HTTP 403 and requires reconnecting.
• Google API failures return HTTP 502 with a sanitized error message.