Documentation

Quick
Start

Turn any Google Sheet into a REST API in under 2 minutes. No backend, no infrastructure.

Create an account

Connect your Google Sheet

In the Dashboard, click Create API. Share your sheet with our service account:sheetsandbox-api@sheetsandbox.iam.gserviceaccount.comGive it Editor access, then paste the sheet URL.

Copy your API token

Your API token is generated automatically and shown on the Dashboard. Keep it secret — it authorises all requests.

Make your first call

Replace YOUR_TOKEN and SheetName below:

cURL — first call

curl https://api.sheetsandbox.com/api/SheetName \
  -H "Authorization: Bearer YOUR_TOKEN"

How It Works

SheetSandbox wraps your Google Sheet with a RESTful interface. Understanding the two key conventions below will save you hours of debugging.

Tab name = URL path

The {SheetName} segment in every endpoint must exactly match the tab name inside your Google Sheet (case-sensitive).

Sheet tab name →

Waitlist

API endpoint →

GET /api/Waitlist

First row = column headers

Row 1 of your sheet must contain column headers. These become the keys in the JSON response. Data rows start at row 2.

Sheet row 1 →

name | email | status

JSON response key →

{ "name": "...", "email": "...", "status": "..." }

Base URL

https://api.sheetsandbox.com/api

All endpoints are relative to this base URL. Always use HTTPS.

Authentication

Every request must include your API token as a Bearer token in the Authorization header.

Where is my API token?

Open the Dashboard, find your connected project card, and click the copy icon next to the token. Each project has its own unique token.

Request header

Authorization: Bearer YOUR_TOKEN

cURL example

curl https://api.sheetsandbox.com/api/Users \
  -H "Authorization: Bearer YOUR_TOKEN"

Never expose your token in client-side JavaScript or public repositories. Treat it like a password — it grants full read/write access to your sheet.

Node.js SDK

npm

The official JavaScript/TypeScript SDK. Type-safe, promise-based, zero config.

Install

npm install sheetsandbox

Initialize

import SheetSandbox from 'sheetsandbox';

const client = new SheetSandbox('YOUR_TOKEN');

Fetch all rows

const rows = await client.get('Users');
// rows = [{ name: 'Alice', email: 'alice@...' }, ...]

Fetch one row by ID

const user = await client.getById('Users', 1);
// user = { name: 'Alice', email: 'alice@...' }

Create a row

const result = await client.post('Users', {
  name: 'Alice',
  email: 'alice@example.com'
});
// result = { success: true, data: 'Inserted' }

Python SDK

pip

The official Python SDK. Works with sync and async code. Great for scripts, automations, and backends.

Install

pip install sheetsandbox

Initialize

from sheetsandbox import SheetSandbox

client = SheetSandbox("YOUR_TOKEN")

Fetch all rows

rows = client.get("Users")
# rows = [{"name": "Alice", "email": "alice@..."}, ...]

Fetch one row by ID

user = client.get_by_id("Users", 1)
# user = {"name": "Alice", "email": "alice@..."}

Create a row

result = client.post("Users", {
    "name": "Alice",
    "email": "alice@example.com"
})
# result = {"success": True, "data": "Inserted"}

List Records

GET

Returns every row in the sheet as a JSON array. Row 1 headers become the object keys. An id field is automatically assigned to each row based on its row number.

Auto JSON conversion

Column headers become object keys automatically.

Row ID included

Each record includes an id field (its row number).

Order preserved

Rows are returned in sheet order, top to bottom.

Request

GET https://api.sheetsandbox.com/api/Users

Response

{
  "success": true,
  "data": [
    { "id": 1, "name": "Alice", "email": "alice@example.com" },
    { "id": 2, "name": "Bob",   "email": "bob@example.com"   }
  ]
}

Create Entry

POST

Appends a new row to your sheet. The JSON body keys must match your column headers exactly (case-sensitive). Any extra keys are ignored; missing keys leave that cell empty.

Appends to the sheet

New data is always added as the next available row.

Keys = column headers

Body keys must match row 1 headers (case-sensitive).

Send JSON only

Set Content-Type: application/json on every POST.

cURL

curl -X POST https://api.sheetsandbox.com/api/Users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}'

Response

{
  "success": true,
  "data": "Inserted"
}

Reference

Rate Limits

Requests / Day — Free

5,000

Requests / Day — Pro

Exceeding your daily limit returns a 429 Too Many Requests response. The counter resets at midnight UTC. Implement exponential backoff to handle bursts gracefully.

{
  "success": false,
  "error": "Rate limit exceeded. Resets at midnight UTC."
}

Status Codes

SheetSandbox uses standard HTTP status codes. All error responses include a success: false body with a human-readable error message.

200OK

Request succeeded.

201Created

Record inserted successfully.

400Bad Request

Missing or malformed request body.

401Unauthorized

Missing or invalid Authorization header.

403Forbidden

Token valid but not allowed for this resource.

404Not Found

Sheet name not found — check the tab name.

429Too Many Requests

Daily rate limit exceeded. Resets at midnight UTC.

500Server Error

Something went wrong on our end. Try again.

QuickStart