Filling tables through the API

Fill a table from an external integration and update its structure through the API.

First create a table in the required project.

Prepare access

An external integration can fill even an empty table without uploading CSV or XLSX first. Use a project API key or OAuth token with the can_manage_knowledge_base permission. Exact request bodies and response models are available in the Knowledge Base API section, while client setup is covered in API SDK.

A project key or app token must belong to the same project as the table. OAuth access on behalf of a user requires both the token permission and the user's own access to manage the knowledge base.

Writing data

Separate operations are available for different tasks:

• POST /api/knowledge-base/tables/:id/rows appends a rectangular block after the last used row;
• PATCH /api/knowledge-base/tables/:id/cells changes individual cells;
• PUT /api/knowledge-base/tables/:id/range writes a rectangular block starting at a specified cell.

For row append and range write operations, set the block size with row_count and column_count. Supply values separately in text_cells, number_cells, and boolean_cells; row_index and column_index are zero-based within that block. Unspecified positions are written as empty, including over existing data when writing a range.

For individual-cell updates, use addresses such as A2 or B3. In addition to text, numbers, and booleans, this operation accepts formula_cells for formulas and empty_cells for clearing cells. It changes only the listed positions. An address cannot appear more than once, even across different type lists.

A request handles at most 10,000 cells; a rectangular block is also limited to 5,000 rows. sheet_id selects the worksheet; without it, the first sheet is used. Send dry_run: true first to validate the request without changing the table. To write data, omit the flag or set it to false.

A range write uses a physical table address; it does not find a row by SKU, email, or another business key and is not an upsert.

A successful response means the table accepted the mutation. The workbook_snapshot used for reading and search is updated asynchronously and may still contain the previous data immediately after a write. When an integration must read the new result, poll the table for a limited time until version or sheet_revision increases; do not poll indefinitely.