Write Operations

Write operations let you use Google Sheets as a lightweight CMS or data store - appending form submissions, updating record status, removing stale entries - all without touching the sheet directly. Every write goes through the API, which means changes are validated, versioned, and tracked via the _id system field.

All write endpoints require an Authorization: Bearer sk_... header. See authentication for key setup.

The _id system field

Every row managed through SheetsAPI carries a _id field generated by GKit at the moment the row is first appended. It is stable: editing a row's data columns does not change its _id, and GKit never reuses an _id after a row is deleted.

PATCH and DELETE both require _id to identify the target row. You get _id from any GET response:

{
  "_id": "row_01j9xkt3v8",
  "Name": "Ada Lovelace",
  "Email": "ada@example.com",
  "Status": "Active"
}

Store _id wherever you store the row's data if you plan to update or delete it later.

POST - append a new row

POST /api/spreadsheets/{userKey}/{sheetName}

The request body is a JSON object whose keys match your sheet's header row. Extra keys not present in the header are silently ignored. Missing header columns are written as empty cells.

curl -X POST https://sheetsapi.gkit.mreshank.com/api/spreadsheets/YOUR_USER_KEY/Contacts \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Grace Hopper",
    "Email": "grace@example.com",
    "Status": "Active"
  }'

Response:

{
  "success": true,
  "row": {
    "_id": "row_02k1ylu4w9",
    "Name": "Grace Hopper",
    "Email": "grace@example.com",
    "Status": "Active"
  }
}

The _id assigned to the new row is returned in the response. Capture it if you need to update or delete this row later.

PATCH - update specific fields

PATCH /api/spreadsheets/{userKey}/{sheetName}/{rowId}

PATCH performs a partial update: only the fields present in the request body are changed. All other columns in the row remain untouched. rowId is the _id value from a prior GET or POST response.

curl -X PATCH https://sheetsapi.gkit.mreshank.com/api/spreadsheets/YOUR_USER_KEY/Contacts/row_02k1ylu4w9 \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "Status": "Inactive"
  }'

Response includes the full updated row after the change is applied:

{
  "success": true,
  "row": {
    "_id": "row_02k1ylu4w9",
    "Name": "Grace Hopper",
    "Email": "grace@example.com",
    "Status": "Inactive"
  }
}

To clear a field, pass an empty string as its value. Omitting a field entirely leaves it as-is.

DELETE - remove a row

DELETE /api/spreadsheets/{userKey}/{sheetName}/{rowId}

Deletes the row identified by _id. The operation is not reversible through the API - the row is removed from the sheet.

curl -X DELETE https://sheetsapi.gkit.mreshank.com/api/spreadsheets/YOUR_USER_KEY/Contacts/row_02k1ylu4w9 \
  -H "Authorization: Bearer sk_..."

Response:

{
  "success": true
}

DELETE is idempotent in intent but not in result: the first call removes the row and returns { "success": true }; a second call with the same _id returns a 404 because the row no longer exists.

Atomic multi-row writes

SheetsAPI does not support multi-row atomic transactions. Each POST, PATCH, or DELETE is an independent operation. If you need to write several rows in one logical unit, issue sequential requests in your application code and handle partial failure yourself.

For high-throughput bulk inserts, see batching requests, which covers concurrency patterns and retry strategies.

Error responses

On any error the response body follows the standard error shape:

{
  "success": false,
  "error": {
    "code": "ROW_NOT_FOUND",
    "message": "No row with _id 'row_02k1ylu4w9' exists in Contacts."
  }
}

See error handling for the full list of error codes and retry guidance.