{"openapi":"3.0.3","info":{"title":"AppStruct Sheets API","version":"1.0.0","description":"\nProgrammatic read and write access to your **AppStruct Sheets** spreadsheets.\n\n### Authentication\nEvery request carries an API key, created from your AppStruct dashboard. Send it\nas either header:\n\n```\nAuthorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx\n# or\nx-api-key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nKeys are shown **once**, at creation. A key reaches the spreadsheets its own\naccount owns and nothing else — spreadsheets shared *with* that account, and\nanything opened by a share link, are not visible through the API.\n\n### Scopes\n- `*`\n- `sheets:read`\n- `sheets:write`\n- `sheets:write-protected`\n\n`sheets:write-protected` is separate from `sheets:write` on purpose. Without\nit, a write that lands inside a **protected range** is filtered through the same\nenforcement a collaborator's save goes through: the protected cells keep their\nstored values and the response reports how many were put back in\n`protectedCellsReverted`. Deleting a sheet that carries protected ranges is\nrefused outright rather than silently undone.\n\n### AI assistants (MCP)\nThe same key also opens a **Model Context Protocol** server at\n`POST /v1/sheets/mcp`, so Claude, Claude Code, Cursor or any other MCP client can\nread and write these spreadsheets directly. It speaks Streamable HTTP and takes\nthe same `Authorization: Bearer` header as the endpoints below.\n\nThe tools an assistant is offered are derived from the key's scopes — a\n`sheets:read` key never sees the write tools at all — and every tool runs\nthrough the same service, the same protected-range enforcement and the same\nlimits as the REST calls documented here. Copy-paste configuration for each\nclient is in the dashboard: <https://appstruct.ai/dashboard/sheets/api/connect>.\n\nBrowser clients are refused: the endpoint rejects any request carrying an\n`Origin` header, which is what the MCP specification requires against DNS\nrebinding, and real MCP clients are not browsers and send none.\n\n### Formulas\nA cell stores the text a person typed, and the formula engine lives in the\nspreadsheet client — so this API returns `=SUM(A1:A9)` for a formula cell under\nevery `valueRenderOption`, and tells you how many such cells a response\ncontains in `formulaCells`. Values you *write* are evaluated the next time the\nspreadsheet is opened.\n\n### Ranges\nA1 notation, URL-encoded in the path. An omitted endpoint opens that axis:\n`Sheet1!A:C` is those three columns for as far as the data goes, `Sheet1!A2:A`\nis column A from row 2 down, and `Sheet1` is everything. A read is clamped to\nthe cells that exist, so a range that reaches past your data simply returns your\ndata and echoes back the rectangle it actually covered. A write anchors your\ndata at the range's top-left and refuses if the data does not fit a bounded\nrange.\n\n### Limits\n- **120 requests per minute per key**, plus a coarser\n  **600 per minute per IP**. Both answer `429` with\n  `Retry-After`; every response carries `X-RateLimit-Limit`,\n  `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds), and the per-IP\n  tier reports the same three suffixed `-ip`.\n- **100,000 requests per rolling\n  24 hours per account**, shared across every key. Reported in\n  `X-AppStruct-RateLimit-Daily` and `X-AppStruct-RateLimit-Daily-Remaining`.\n- **50,000 cells** per write request,\n  counted as the rectangle the request addresses.\n- **500,000 cells** read per request,\n  summed across every range of a `batchGet`.\n- A sheet holds at most **5,000 rows** and\n  **260 columns**; a write reaching outside that is a `400`,\n  because a cell stored there could never be reached in the spreadsheet itself.\n- List endpoints take `?limit=` (1–200, default\n  50) and `?offset=`, and return `{ data, meta }`.\n\n### Errors\nStandard HTTP status codes with a JSON body. Switch on `statusCode`, not on the\nhuman-readable `message`.\n\n| Status | Meaning |\n| ------ | ------- |\n| 400 | The request or the range could not be understood |\n| 401 | Missing, invalid, expired or revoked API key |\n| 403 | The key lacks the required scope |\n| 404 | No such spreadsheet, sheet or range on this account |\n| 429 | A rate limit or the daily budget was exceeded |\n"},"servers":[{"url":"/","description":"Current host"}],"tags":[{"name":"Spreadsheets","description":"Discovery, structure and formatting"},{"name":"Values","description":"Reading and writing cells"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Your Sheets API key, e.g. ak_live_… (also accepted in the x-api-key header)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your Sheets API key, as an alternative to Authorization: Bearer."}}},"paths":{"/v1/sheets/spreadsheets":{"get":{"tags":["Spreadsheets"],"summary":"List spreadsheets","description":"Requires the `sheets:read` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},{"name":"includeTrashed","in":"query","schema":{"type":"boolean","default":false},"description":"Include spreadsheets in the trash."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"name":{"type":"string"},"starred":{"type":"boolean"},"trashed":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"},"sheets":{"type":"array","items":{"type":"object","properties":{"sheetId":{"type":"string"},"title":{"type":"string"},"index":{"type":"integer"},"rows":{"type":"integer"},"cols":{"type":"integer"},"protectedRanges":{"type":"integer"}}}}}}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}":{"get":{"tags":["Spreadsheets"],"summary":"Retrieve a spreadsheet","description":"Requires the `sheets:read` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"name":{"type":"string"},"starred":{"type":"boolean"},"trashed":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"},"sheets":{"type":"array","items":{"type":"object","properties":{"sheetId":{"type":"string"},"title":{"type":"string"},"index":{"type":"integer"},"rows":{"type":"integer"},"cols":{"type":"integer"},"protectedRanges":{"type":"integer"}}}}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}/sheets":{"post":{"tags":["Spreadsheets"],"summary":"Create a sheet","description":"Requires the `sheets:write` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":100},"rows":{"type":"integer","default":100,"maximum":5000},"cols":{"type":"integer","default":26,"maximum":260}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"sheetId":{"type":"string"},"title":{"type":"string"},"index":{"type":"integer"},"rows":{"type":"integer"},"cols":{"type":"integer"},"protectedRanges":{"type":"integer"}}}}}},"400":{"description":"Request validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}/sheets/{sheetId}":{"delete":{"tags":["Spreadsheets"],"summary":"Delete a sheet","description":"Requires the `sheets:write` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."},{"name":"sheetId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted. A sheet carrying protected ranges is refused with 403 unless the key holds sheets:write-protected.","content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"deletedSheetId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}/formats/{range}":{"get":{"tags":["Spreadsheets"],"summary":"Read cell formatting","description":"Requires the `sheets:read` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."},{"name":"range","in":"path","required":true,"schema":{"type":"string"},"description":"A URL-encoded A1 reference: `Sheet1!A1:C10`, `Sheet1!A:C`, `Sheet1!A2:A`, `Sheet1` for the whole sheet, or a bare `A1:C10` for the first sheet. A sheet name containing a space or a punctuation mark is single-quoted.","example":"Sheet1%21A1%3AC10"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string"},"cells":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","example":"B2"},"style":{"type":"object","description":"The stored cell style: bold, italic, align, color, bg, format, decimals, currency, border, …"}}}}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}/values":{"get":{"tags":["Values"],"summary":"Read several ranges","description":"Requires the `sheets:read` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."},{"name":"ranges","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"}},"description":"Repeat the parameter once per range, e.g. ?ranges=Sheet1!A1:B2&ranges=Sheet2!A1:A9."},{"name":"valueRenderOption","in":"query","schema":{"type":"string","enum":["FORMATTED_VALUE","UNFORMATTED_VALUE","FORMULA"],"default":"FORMATTED_VALUE"},"description":"FORMATTED_VALUE renders each cell the way the grid paints it (number format applied). UNFORMATTED_VALUE returns typed JSON — number, boolean or string. FORMULA returns the raw text a person typed."},{"name":"majorDimension","in":"query","schema":{"type":"string","enum":["ROWS","COLUMNS"],"default":"ROWS"},"description":"Whether the outer array of `values` is rows or columns."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"valueRanges":{"type":"array","items":{"type":"object","properties":{"range":{"type":"string","example":"Sheet1!A1:C10","description":"The rectangle actually returned, after open edges were closed against the data."},"majorDimension":{"type":"string","enum":["ROWS","COLUMNS"]},"values":{"type":"array","items":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}},"formulaCells":{"type":"integer","description":"How many returned cells hold a formula. This server stores the formula text and does not evaluate it, so those cells come back as their formula under every valueRenderOption."}}}}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}/values/batchUpdate":{"post":{"tags":["Values"],"summary":"Write several ranges in one save","description":"Requires the `sheets:write` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":100,"items":{"type":"object","required":["range","values"],"properties":{"range":{"type":"string"},"values":{"type":"array","items":{"type":"array","items":{}}}}}},"valueInputOption":{"type":"string","enum":["USER_ENTERED","RAW"]},"majorDimension":{"type":"string","enum":["ROWS","COLUMNS"]}}},"example":{"data":[{"range":"Sheet1!A1:B1","values":[["Name","Qty"]]},{"range":"Sheet1!A2:B2","values":[["Widget",12]]}]}}}},"responses":{"200":{"description":"Applied as ONE save, so the spreadsheet takes a single version snapshot and collaborators get a single notification.","content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"totalUpdatedCells":{"type":"integer"},"protectedCellsReverted":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"updatedRange":{"type":"string","example":"Sheet1!A1:C3"},"updatedRows":{"type":"integer"},"updatedColumns":{"type":"integer"},"updatedCells":{"type":"integer"},"protectedCellsReverted":{"type":"integer","description":"Cells the request asked to change that a protected range put back. Always 0 for a key holding sheets:write-protected."}}}}}}}}},"400":{"description":"Request validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}/values/{range}":{"get":{"tags":["Values"],"summary":"Read a range","description":"Requires the `sheets:read` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."},{"name":"range","in":"path","required":true,"schema":{"type":"string"},"description":"A URL-encoded A1 reference: `Sheet1!A1:C10`, `Sheet1!A:C`, `Sheet1!A2:A`, `Sheet1` for the whole sheet, or a bare `A1:C10` for the first sheet. A sheet name containing a space or a punctuation mark is single-quoted.","example":"Sheet1%21A1%3AC10"},{"name":"valueRenderOption","in":"query","schema":{"type":"string","enum":["FORMATTED_VALUE","UNFORMATTED_VALUE","FORMULA"],"default":"FORMATTED_VALUE"},"description":"FORMATTED_VALUE renders each cell the way the grid paints it (number format applied). UNFORMATTED_VALUE returns typed JSON — number, boolean or string. FORMULA returns the raw text a person typed."},{"name":"majorDimension","in":"query","schema":{"type":"string","enum":["ROWS","COLUMNS"],"default":"ROWS"},"description":"Whether the outer array of `values` is rows or columns."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string","example":"Sheet1!A1:C10","description":"The rectangle actually returned, after open edges were closed against the data."},"majorDimension":{"type":"string","enum":["ROWS","COLUMNS"]},"values":{"type":"array","items":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}},"formulaCells":{"type":"integer","description":"How many returned cells hold a formula. This server stores the formula text and does not evaluate it, so those cells come back as their formula under every valueRenderOption."}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}},"put":{"tags":["Values"],"summary":"Write a range","description":"Requires the `sheets:write` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."},{"name":"range","in":"path","required":true,"schema":{"type":"string"},"description":"A URL-encoded A1 reference: `Sheet1!A1:C10`, `Sheet1!A:C`, `Sheet1!A2:A`, `Sheet1` for the whole sheet, or a bare `A1:C10` for the first sheet. A sheet name containing a space or a punctuation mark is single-quoted.","example":"Sheet1%21A1%3AC10"},{"name":"valueInputOption","in":"query","schema":{"type":"string","enum":["USER_ENTERED","RAW"],"default":"USER_ENTERED"},"description":"USER_ENTERED stores the value as if it were typed, so `=SUM(A1:A9)` becomes a formula. RAW stores it as literal text, so the same string stays four visible characters."},{"name":"majorDimension","in":"query","schema":{"type":"string","enum":["ROWS","COLUMNS"],"default":"ROWS"},"description":"Whether the outer array of `values` is rows or columns."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["values"],"properties":{"values":{"type":"array","description":"Rows of cell values. An empty string clears a cell; JSON null leaves it exactly as it was.","items":{"type":"array","items":{}}}}},"example":{"values":[["Name","Qty"],["Widget",12]]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"updatedRange":{"type":"string","example":"Sheet1!A1:C3"},"updatedRows":{"type":"integer"},"updatedColumns":{"type":"integer"},"updatedCells":{"type":"integer"},"protectedCellsReverted":{"type":"integer","description":"Cells the request asked to change that a protected range put back. Always 0 for a key holding sheets:write-protected."}}}}}},"400":{"description":"Request validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}},"/v1/sheets/spreadsheets/{spreadsheetId}/values/{range}/append":{"post":{"tags":["Values"],"summary":"Append rows","description":"Requires the `sheets:write` scope.","security":[{"ApiKey":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"spreadsheetId","in":"path","required":true,"schema":{"type":"string"},"description":"The spreadsheet id, as returned by GET /v1/sheets/spreadsheets."},{"name":"range","in":"path","required":true,"schema":{"type":"string"},"description":"A URL-encoded A1 reference: `Sheet1!A1:C10`, `Sheet1!A:C`, `Sheet1!A2:A`, `Sheet1` for the whole sheet, or a bare `A1:C10` for the first sheet. A sheet name containing a space or a punctuation mark is single-quoted.","example":"Sheet1%21A1%3AC10"},{"name":"valueInputOption","in":"query","schema":{"type":"string","enum":["USER_ENTERED","RAW"],"default":"USER_ENTERED"},"description":"USER_ENTERED stores the value as if it were typed, so `=SUM(A1:A9)` becomes a formula. RAW stores it as literal text, so the same string stays four visible characters."},{"name":"majorDimension","in":"query","schema":{"type":"string","enum":["ROWS","COLUMNS"],"default":"ROWS"},"description":"Whether the outer array of `values` is rows or columns."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["values"],"properties":{"values":{"type":"array","description":"Rows of cell values. An empty string clears a cell; JSON null leaves it exactly as it was.","items":{"type":"array","items":{}}}}},"example":{"values":[["Name","Qty"],["Widget",12]]}}}},"responses":{"200":{"description":"Rows land after the block of data the range starts on, on the first run of empty rows big enough to hold them. An append never writes over a cell that already holds something.","content":{"application/json":{"schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"updatedRange":{"type":"string","example":"Sheet1!A1:C3"},"updatedRows":{"type":"integer"},"updatedColumns":{"type":"integer"},"updatedCells":{"type":"integer"},"protectedCellsReverted":{"type":"integer","description":"Cells the request asked to change that a protected range put back. Always 0 for a key holding sheets:write-protected."}}}}}},"400":{"description":"Request validation failed","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"404":{"description":"Not found on this account","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}},"429":{"description":"Rate limit or daily budget exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","example":403},"error":{"type":"string","example":"FORBIDDEN"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}}}}}}