REST Endpoints

SheetsToJson automatically generates RESTful endpoints for each tab in your Google Sheet. All endpoints follow standard HTTP conventions.

Base URL

https://api.sheetstojson.com

Endpoint Structure

/api/v1/{sheetId}/{tabName}[/{rowId}]

• sheetId: Your Google Sheet ID (found in the sheet URL)
• tabName: The name of the sheet tab (case-sensitive)
• rowId: (Optional) Specific row identifier

Read Operations

Get All Rows

Retrieve all rows from a sheet tab.

GET /api/v1/{sheetId}/{tabName}

Query Parameters:

Parameter	Type	Description	Default
limit	integer	Number of rows to return	100
offset	integer	Number of rows to skip	0
sort	string	Column to sort by	-
order	string	Sort order: asc or desc	asc
filter	string	Filter expression (e.g., status=active)	-

Example Request:

curl -H "X-API-Key: your_api_key" \
  "https://api.sheetstojson.com/api/v1/abc123/Users?limit=10&offset=0"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "1",
      "name": "John Doe",
      "email": "[email protected]",
      "status": "active"
    },
    {
      "id": "2",
      "name": "Jane Smith",
      "email": "[email protected]",
      "status": "active"
    }
  ],
  "meta": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "returned": 2
  }
}

Get Single Row

Retrieve a specific row by its ID.

GET /api/v1/{sheetId}/{tabName}/{rowId}

Example Request:

curl -H "X-API-Key: your_api_key" \
  https://api.sheetstojson.com/api/v1/abc123/Users/1

Example Response:

{
  "success": true,
  "data": {
    "id": "1",
    "name": "John Doe",
    "email": "[email protected]",
    "status": "active",
    "created_at": "2025-01-15"
  }
}

Write Operations

Write Permissions Required

Write operations require an API key with write permissions enabled.

Create Row(s)

Add one or more rows to the sheet.

POST /api/v1/{sheetId}/{tabName}

Request Body (Single Row):

{
  "name": "Alice Johnson",
  "email": "[email protected]",
  "status": "pending"
}

Request Body (Multiple Rows):

[
  {
    "name": "Alice Johnson",
    "email": "[email protected]"
  },
  {
    "name": "Bob Williams",
    "email": "[email protected]"
  }
]

Example Request:

curl -X POST \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice Johnson","email":"[email protected]"}' \
  https://api.sheetstojson.com/api/v1/abc123/Users

Example Response:

{
  "success": true,
  "data": {
    "created": 1,
    "rows": [
      {
        "id": "151",
        "name": "Alice Johnson",
        "email": "[email protected]"
      }
    ]
  }
}

Update Row

Update an existing row by its ID.

PUT /api/v1/{sheetId}/{tabName}/{rowId}

Request Body:

{
  "status": "active",
  "updated_at": "2025-01-20"
}

Partial Updates

You only need to include the fields you want to update. Other fields remain unchanged.

Example Request:

curl -X PUT \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}' \
  https://api.sheetstojson.com/api/v1/abc123/Users/151

Example Response:

{
  "success": true,
  "data": {
    "id": "151",
    "name": "Alice Johnson",
    "email": "[email protected]",
    "status": "active",
    "updated_at": "2025-01-20"
  }
}

Delete Row

Delete a row by its ID.

DELETE /api/v1/{sheetId}/{tabName}/{rowId}

Example Request:

curl -X DELETE \
  -H "X-API-Key: your_api_key" \
  https://api.sheetstojson.com/api/v1/abc123/Users/151

Example Response:

{
  "success": true,
  "message": "Row deleted successfully"
}

Schema Operations

Get Schema

Retrieve the schema for a sheet (all tabs and their columns).

GET /api/{sheetId}/schema

Example Response:

{
  "success": true,
  "data": {
    "sheet_id": "abc123",
    "sheet_name": "My Database",
    "tabs": [
      {
        "name": "Users",
        "columns": [
          { "name": "id", "type": "string" },
          { "name": "name", "type": "string" },
          { "name": "email", "type": "string" },
          { "name": "status", "type": "string" }
        ]
      }
    ]
  }
}

Refresh Schema

Force a refresh of the cached sheet schema.

POST /api/{sheetId}/refresh-schema

Example Response:

{
  "success": true,
  "message": "Schema refreshed successfully",
  "data": {
    "tabs_count": 3,
    "updated_at": 1705747200000
  }
}

Error Responses

All errors follow this format:

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable error message"
}

Common Error Codes

Code	Status	Description
unauthorized	401	Missing or invalid API key
forbidden	403	API key lacks required permissions
not_found	404	Sheet, tab, or row not found
rate_limit_exceeded	429	Rate limit exceeded
validation_error	400	Invalid request data
server_error	500	Internal server error

Filtering and Querying

Use the filter query parameter for basic filtering:

# Filter by exact match
?filter=status=active

# Filter by multiple conditions (AND)
?filter=status=active,role=admin

# Combine with sorting and pagination
?filter=status=active&sort=created_at&order=desc&limit=20

Advanced Queries

For complex queries, filtering, and aggregations, consider fetching the data and processing it in your application.

Best Practices

1. Use Pagination: Always use limit and offset for large datasets
2. Cache Responses: Cache GET responses when data doesn't change frequently
3. Batch Operations: Create multiple rows in a single POST request
4. Error Handling: Always check the success field and handle errors gracefully
5. Rate Limiting: Implement exponential backoff for 429 errors

Next Steps

• View OpenAPI specification
• Understand rate limits
• See JavaScript examples