# Add Row Source: https://docs.sheetninja.io/api-reference/endpoint/add-row POST /{endpointNamespace}/{projectName}/{tabSlug} Appends one or more rows to the bottom of the worksheet. Supports both a single object or an array of objects for bulk addition. # Delete Rows Source: https://docs.sheetninja.io/api-reference/endpoint/delete-row DELETE /{endpointNamespace}/{projectName}/{tabSlug}/{rowId} Permanently removes the row from the sheet. Note that subsequent rows will shift up to fill the gap. # Get Individual Row Source: https://docs.sheetninja.io/api-reference/endpoint/get-individual-row GET /{endpointNamespace}/{projectName}/{tabSlug}/{rowId} Fetches a specific row based on its physical row ID in the sheet. # List Rows Source: https://docs.sheetninja.io/api-reference/endpoint/list-rows GET /{endpointNamespace}/{projectName}/{tabSlug} Returns a paginated list of rows from the worksheet. Results are returned in a 'data' envelope with pagination metadata in 'meta'. # Update Row Source: https://docs.sheetninja.io/api-reference/endpoint/update-row PATCH /{endpointNamespace}/{projectName}/{tabSlug}/{rowId} Updates specific fields on an existing row. Only provided fields are modified; others remain unchanged. # Introduction Source: https://docs.sheetninja.io/api-reference/introduction Understand how Sheet Ninja endpoints work Welcome to the Sheet Ninja API reference. Sheet Ninja turns Google Sheets into a REST-style API, allowing you to read, create, update, and delete rows in a worksheet using simple HTTP endpoints. Each worksheet in your project can be enabled as an API and interacted with like a lightweight database. This section documents how Sheet Ninja endpoints are structured, how data is mapped, and what to expect when working with rows. The Sheet Ninja API lets you interact with Google Sheets using REST-style endpoints. *** ## How the API is organized Sheet Ninja APIs are organized around **projects**, **worksheets**, and **rows**. * A **project** represents a single Google Sheets workbook * Each **worksheet (tab)** within that workbook can be exposed as an API * Each **row** in a worksheet represents a single record Once a worksheet is enabled, Sheet Ninja automatically provides a set of endpoints for working with its rows. *** ## Available endpoints For each enabled worksheet, Sheet Ninja provides the following endpoints: * **[List Rows](/api-reference/endpoint/list-rows)** – Retrieve multiple rows from a worksheet * **[Get Individual Row](/api-reference/endpoint/get-individual-row)** – Retrieve a single row by its row number * **[Add Row](/api-reference/endpoint/add-row)** – Append a new row to the worksheet * **[Update Row](/api-reference/endpoint/update-row)** – Update one or more fields on an existing row * **[Delete Row](/api-reference/endpoint/delete-row)** – Permanently remove a row These endpoints are surfaced directly in the Sheet Ninja dashboard and update in real time as your sheet changes. *** ## Row identification Rows are identified by their **row number** in the worksheet. * Row 1 is always treated as the **header row** * Data rows start at row 2 * Row numbers are used when fetching, updating, or deleting individual rows Because row numbers reflect the sheet’s current state, inserting or deleting rows directly in Google Sheets may change row numbering. *** ## Data mapping Sheet Ninja maps spreadsheet data to structured API responses using the following rules: * Column headers define field names * Each row maps to a single object * Empty cells are returned as empty or null values * Extra fields not present in the sheet are ignored * Updates only affect the fields you provide Your Google Sheet remains the source of truth at all times. *** ## Pagination and limits When listing rows, responses may be paginated to ensure reliability and performance. * You can control how many rows are returned per request * Pagination helpers are included in responses to make iterating easy * Free and paid plans have different row limits per request This approach prevents timeouts and keeps large sheets fast and usable, especially when integrating with automation tools or AI systems :contentReference\[oaicite:1]index=1 *** ## Authentication Depending on your project settings, endpoints may require authentication. * Public endpoints allow read access without authentication * Protected endpoints require a valid API key * Write operations typically require authentication Authentication behavior is configured per project. See the [**Authentication**](/guides/authentication) section for full details. *** ## What’s next Use the endpoint pages in this section to learn how each operation behaves in detail, including supported parameters and response behavior. If you’re new to Sheet Ninja, start with the [**Quickstart**](/quickstart) to set up your first project and enable your first API. *** This introduction is intentionally conceptual. Individual endpoint pages contain operation-specific details. # Authentication Source: https://docs.sheetninja.io/guides/authentication Control access to your Sheet Ninja endpoints using API keys Sheet Ninja lets you control who can access your endpoints using API keys and access tokens. By default, new projects are **public and read-only**. This means anyone with your endpoint URL can fetch data, but they cannot add, change, or delete anything. Enabling authentication allows you to protect read access and securely enable write access. *** # How it Works In a [Project Dashboard](https://sheetninja.io/dashboard), head to the **Authentication** tab. When you create a new token, you choose which operations (like Read, Add, or Delete) that token should protect. Authentication As soon as a token is set to protect an operation, that operation becomes **Private**. From then on, any request to that endpoint must include a valid token, or Sheet Ninja will block it. *** ## Authentication methods Sheet Ninja uses the **Bearer Token** scheme. To authenticate your requests, include an `Authorization` header with your API token: ``` Authorization: Bearer your_api_token_here ``` If you’re using an AI agent (like Claude or ChatGPT), you can simply provide the token and tell it to "use this as a Bearer token for all Sheet Ninja requests." *** ## Best practices * Keep API keys secret and store them securely * Never expose API keys in frontend or client-side applications * Rotate keys periodically, especially if a key may have been exposed * Use separate API keys for different services or integrations # Endpoints Source: https://docs.sheetninja.io/guides/endpoints Interact with your Google Sheets using Sheet Ninja endpoints Sheet Ninja turns every tab in your Google Sheets into its own set of REST-style endpoints. This lets you treat your spreadsheet like a database—allowing you to read, add, update, and delete rows with simple web requests that your AI already knows how to do. All endpoints work on a single tab (worksheet) inside your project. *** ## Base URL Every endpoint is tied to your account and project. Your base URL looks like this: ```text theme={null} https://api.sheetninja.io/{namespace}/{projectName}/{tabSlug} ``` * **namespace**: Your unique user ID (e.g., `c01c052...`). * **projectName**: The name of your project. * **tabSlug**: The name of the specific tab (sheet) you're using. You can find your full, ready-to-use endpoint URLs directly in the [Sheet Ninja dashboard](https://sheetninja.io/dashboard). *** ## List Rows **Method:** GET Gets the rows from your sheet. Use this endpoint to: * Display tables or lists * Power dashboards and internal tools * Export spreadsheet data into other systems To keep things fast and stop your AI context from filling up too quickly, Sheet Ninja returns your data in **pages of 100 rows at a time** (Pro & Max users get much higher page sizes). Think of it as organised batches: instead of one massive data dump that might hit your AI's limit, you get exactly what you need in manageable chunks. You still have access to every row in your sheet—you just grab them 100 at a time. **Why this is great:** * Helps you mamage your context window prevents your AI from losing track of instructions due to massive data inputs. * Smaller batches load almost instantly, making your apps and agents feel much more responsive. * Every response includes a `meta` section with a `next_offset` so you (or your agent) know exactly how to pull the next page. This is industry standard and your AI agent will know how to loop through all the pages easily. Each row comes back as a JSON object, and we even add a handy `id` field representing the physical row number in your sheet. *** ## Get Individual Row **Method:** GET Gets a single row from your sheet using its row number (like `/5`). Perfect for when you need to show details for just one item or load data into a specific form. Remember, Row 1 is your header, so your data starts at Row 2! *** ## Add Row **Method:** POST Adds new data to the bottom of your sheet. You can add just one row at a time or send a whole list of them to update your sheet in bulk. To keep things stable and fast, Trial Users can add up to 10 rows in a single batch (with Pro & Max users able to add much more in a single request). If you send data for a column that doesn't exist, Sheet Ninja will just skip it and let you know. *** ## Update Row **Method:** PATCH Changes specific cells in a row using its row number. Only the fields you send in your request are changed. Everything else in that row stays exactly the same. Great for updating statuses or editing single fields. *** ## Delete Row **Method:** DELETE Removes a specific row from your sheet using its row number. **Note:** Since this physically removes the row, any rows below it will move up to fill the gap. This means their row numbers (IDs) will change! *** ## How data is mapped * **Magic Mapping**: You can use `camelCase` in your JSON (like `firstName`) and it will automatically find the right column (like "First Name") in your sheet. * **Row IDs**: Sheet Ninja adds an `id` field to every row it sends back. This is the row's physical position in the sheet. * **Instant Sync**: As soon as you make a request, the change appears in your Google Sheet. * **Empty Cells**: If a cell is blank in your sheet, it comes back as an empty string `""`. *** ## Notes * **Access Control**: You can turn Read, Add, Update, or Delete permissions on or off for each tab in your dashboard. * **Source of Truth**: Your Google Sheet is always the master version of your data. *** This page is a high-level overview. For all the technical details, request formats, and response codes, check out the [API Reference](https://docs.sheetninja.io/api-reference/introduction). # Introduction Source: https://docs.sheetninja.io/index Build powerful workflows on top of Google Sheets with Sheet Ninja Welcome to the Sheet Ninja documentation 👋 Sheet Ninja lets you turn *any* Google Sheets into a powerful backend — enabling APIs, automation, and workflows without the overhead of traditional infrastructure. Use Sheet Ninja to power internal tools, sync data between systems, or prototype production-ready applications using spreadsheets as your data source. These docs will help you get set up, understand how Sheet Ninja works, and build reliable applications on top of Google Sheets. *** ## Setting up Get up and running with Sheet Ninja in just a few minutes. Follow our quickstart guide to connect your first Google Sheet and create your first API endpoint. In the quickstart, you’ll: * Connect your Google account * Create your first Sheet Ninja endpoint * Read and write data from a Google Sheet *** ## Who uses Sheet Ninja? Sheet Ninja is built for anyone who wants to move fast while keeping their data simple and accessible. Use Google Sheets as a lightweight backend for APIs, prototypes, and internal tools. Manage workflows, approvals, and operational data directly from spreadsheets. Power automations and integrations using tools you already know. Ship faster without setting up databases, servers, or admin panels. *** ## What can you create? Everything you need to turn spreadsheets into production-ready systems. Automatically expose rows and columns as clean, structured API responses. Trigger workflows and sync data across your stack using webhooks and API calls. Work with attachments, links, and rich data stored directly in your sheets. Common recipes for syncing data, automation, and integrations. # Quickstart Source: https://docs.sheetninja.io/quickstart Create your first Sheet Ninja endpoint in minutes Get up and running with Sheet Ninja in just a few minutes.\ By the end of this guide, you’ll have a Google Sheet connected to Sheet Ninja and accessible via an API endpoint. *** ## Prerequisites Before you begin, make sure you have: * A Google Sheets workbook containing data you’d like to turn into an API * Column headers defined in the first row Example: | id | name | email | status | | -- | ---- | ------------------------------------------- | -------- | | 1 | Jane | [jane@example.com](mailto:jane@example.com) | active | | 2 | John | [john@example.com](mailto:john@example.com) | inactive | * The first row defines your schema * Each row represents a record *** ## 3 Simple Steps Sheet Ninja needs permission to access your Google Sheets in order to read and write data. 1. Click **Sign In** in the top-right corner 2. Select the Google account you want to use 3. Approve the requested permissions Once connected, Sheet Ninja will be able to list and access your spreadsheets. A project links a Google Sheets workbook to Sheet Ninja. 1. Sign in to your Sheet Ninja dashboard 2. Paste your **Google Sheets URL** into the input field 3. Click **Preview** to confirm you’ve selected the correct workbook 4. Click **Add Project** Your workbook is now connected and ready to use. Now let’s turn your sheet into an API endpoint. 1. Open your project in the Sheet Ninja dashboard 2. Select the sheet (tab) you want to expose 3. Enable the desired endpoints using the toggle controls 4. Copy your endpoint URL and start building. E.g. ``` https://api.sheetninja.io/98174693c7d743418d5dc614b6927270/workbook/sheet ``` 5. If required, configure access rules in the **Authentication** tab That’s it — your Google Sheet is now accessible via an API 🎉 *** ## What’s next? * Secure your endpoints with authentication * Explore available API methods and query options * Build automations and integrations on top of your data Head to the **API Reference** to see everything you can do with your new endpoint.