---
title: Atomically create, update and delete in-house sheet rows
description: "Values use column IDs or unambiguous titles. Strict column types;
  null clears a cell. Invalid values reject the whole batch with row_ref,
  column_id and reason. Preview returns cell changes and created/deleted row IDs
  without writing. Every write returns the full sheet. Writes are not
  idempotent: re-read after an unknown outcome before retrying. Updates are not
  upserts."
canonical_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/sheets/post-batch-space-sheet-rows
markdown_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/sheets/post-batch-space-sheet-rows.md
---

# Atomically create, update and delete in-house sheet rows

Values use column IDs or unambiguous titles. Strict column types; null clears a cell. Invalid values reject the whole batch with row_ref, column_id and reason. Preview returns cell changes and created/deleted row IDs without writing. Every write returns the full sheet. Writes are not idempotent: re-read after an unknown outcome before retrying. Updates are not upserts.

```http
POST /v1/space/sheets/{sheet_id}/tabs/{tab_id}/rows/batch
```

Server: https://api.orchestor.io

Operation ID: `batchSpaceSheetRows`

## Authentication

```json
[
  [
    {
      "key": "session_cookie",
      "type": "apiKey",
      "description": "Browser session established by signing in to the web app. The server checks your workspace membership and permissions. Supply X-Workspace-ID for workspace-scoped operations. For server-to-server requests, use an API key when the operation supports it.",
      "name": "wos-session",
      "in": "cookie",
      "scopes": []
    }
  ],
  [
    {
      "key": "bearer_api_key",
      "type": "http",
      "description": "Authenticate with a workspace-scoped API key using Authorization: Bearer <key>. Supported key prefixes are sk_live_ and sk_test_. The key determines the workspace and allowed permissions; supplying X-Workspace-ID does not grant access to another workspace. Create and manage API keys in workspace settings. Never put a key in a URL.",
      "scheme": "bearer",
      "scopes": []
    }
  ]
]
```

## Parameters

```json
[
  {
    "name": "X-Workspace-ID",
    "in": "header",
    "required": false,
    "description": "Workspace to access. With a workspace-scoped API key, the server derives this value from the key, so the header is optional. If supplied, it must match the credential workspace or the request returns 403 workspace_mismatch. For interactive session requests, supply this header to select a workspace where you are a member. A project ID cannot be used as a workspace ID.",
    "schema": {
      "type": "string",
      "example": "wks_abc123"
    }
  },
  {
    "name": "sheet_id",
    "in": "path",
    "required": true,
    "schema": {
      "pattern": "^sht_[a-f0-9]{24}$",
      "type": "string"
    }
  },
  {
    "name": "tab_id",
    "in": "path",
    "required": true,
    "schema": {
      "minLength": 1,
      "maxLength": 256,
      "type": "string"
    }
  }
]
```

## Request body

```json
{
  "required": true,
  "content": [
    {
      "contentType": "application/json",
      "schema": {
        "name": "BatchSpaceSheetRows",
        "type": "object",
        "required": [
          "operations",
          "updated_at"
        ],
        "properties": {
          "operations": {
            "minItems": 1,
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "op",
                    "values"
                  ],
                  "properties": {
                    "before_row_id": {
                      "minLength": 1,
                      "maxLength": 256,
                      "type": "string"
                    },
                    "op": {
                      "type": "string",
                      "enumValues": [
                        "create"
                      ]
                    },
                    "row_id": {
                      "minLength": 1,
                      "maxLength": 256,
                      "type": "string"
                    },
                    "values": {
                      "type": "object",
                      "additionalProperties": {}
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "required": [
                    "op",
                    "row_id",
                    "values"
                  ],
                  "properties": {
                    "op": {
                      "type": "string",
                      "enumValues": [
                        "update"
                      ]
                    },
                    "row_id": {
                      "minLength": 1,
                      "maxLength": 256,
                      "type": "string"
                    },
                    "values": {
                      "type": "object",
                      "additionalProperties": {}
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "required": [
                    "op",
                    "row_id"
                  ],
                  "properties": {
                    "op": {
                      "type": "string",
                      "enumValues": [
                        "delete"
                      ]
                    },
                    "row_id": {
                      "minLength": 1,
                      "maxLength": 256,
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              ]
            }
          },
          "preview": {
            "type": "boolean"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      }
    }
  ]
}
```

## Responses

### 200

```json
{
  "statusCode": "200",
  "description": "Full updated sheet or preview diff",
  "headers": [],
  "content": [
    {
      "contentType": "application/json",
      "schema": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "anyOf": [
              {
                "name": "SpaceSheet",
                "type": "object",
                "required": [
                  "id",
                  "workspace_id",
                  "title",
                  "pinned",
                  "sort_position",
                  "archived",
                  "tabs",
                  "created_at",
                  "updated_at",
                  "deleted_at"
                ],
                "properties": {
                  "archived": {
                    "type": "boolean"
                  },
                  "created_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "deleted_at": {
                    "type": "string",
                    "nullable": true,
                    "format": "date-time"
                  },
                  "folder_id": {
                    "type": "string",
                    "nullable": true,
                    "default": null
                  },
                  "id": {
                    "pattern": "^sht_[a-f0-9]{24}$",
                    "type": "string"
                  },
                  "pinned": {
                    "type": "boolean"
                  },
                  "sort_position": {
                    "minimum": 0,
                    "maximum": 2147483647,
                    "type": "integer"
                  },
                  "tabs": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "title",
                        "rows"
                      ],
                      "properties": {
                        "columns": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "title",
                              "type"
                            ],
                            "properties": {
                              "color": {
                                "type": "string"
                              },
                              "currencyCode": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "hidden": {
                                "type": "boolean"
                              },
                              "id": {
                                "minLength": 1,
                                "maxLength": 256,
                                "type": "string"
                              },
                              "options": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "pinned": {
                                "type": "boolean"
                              },
                              "title": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enumValues": [
                                  "text",
                                  "number",
                                  "currency",
                                  "url",
                                  "domain",
                                  "date",
                                  "timestamp",
                                  "email",
                                  "image",
                                  "checkbox",
                                  "select",
                                  "multi-select"
                                ]
                              },
                              "width": {
                                "minimum": 104,
                                "type": "integer"
                              }
                            },
                            "additionalProperties": false
                          }
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "filter": {
                          "type": "object",
                          "required": [
                            "columnId",
                            "value"
                          ],
                          "properties": {
                            "columnId": {
                              "minLength": 1,
                              "maxLength": 256,
                              "type": "string"
                            },
                            "value": {
                              "type": "string"
                            }
                          },
                          "additionalProperties": false
                        },
                        "hidden": {
                          "type": "boolean"
                        },
                        "id": {
                          "minLength": 1,
                          "maxLength": 256,
                          "type": "string"
                        },
                        "rows": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id"
                            ],
                            "properties": {
                              "id": {
                                "minLength": 1,
                                "maxLength": 256,
                                "type": "string"
                              },
                              "parentId": {
                                "minLength": 1,
                                "maxLength": 256,
                                "type": "string"
                              },
                              "values": {
                                "type": "object",
                                "additionalProperties": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "number"
                                    },
                                    {
                                      "type": "boolean"
                                    },
                                    {
                                      "type": "array",
                                      "items": {
                                        "type": "string"
                                      }
                                    }
                                  ]
                                }
                              }
                            },
                            "additionalProperties": false
                          }
                        },
                        "sort": {
                          "type": "object",
                          "required": [
                            "columnId",
                            "direction"
                          ],
                          "properties": {
                            "columnId": {
                              "minLength": 1,
                              "maxLength": 256,
                              "type": "string"
                            },
                            "direction": {
                              "type": "string",
                              "enumValues": [
                                "asc",
                                "desc"
                              ]
                            }
                          },
                          "additionalProperties": false
                        },
                        "title": {
                          "minLength": 1,
                          "maxLength": 100,
                          "type": "string"
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "title": {
                    "minLength": 1,
                    "maxLength": 100,
                    "type": "string"
                  },
                  "updated_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "workspace_id": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "preview",
                  "changes",
                  "created",
                  "deleted"
                ],
                "properties": {
                  "changes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "row_id",
                        "column_id",
                        "before",
                        "after"
                      ],
                      "properties": {
                        "after": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "before": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "column_id": {
                          "minLength": 1,
                          "maxLength": 256,
                          "type": "string"
                        },
                        "row_id": {
                          "minLength": 1,
                          "maxLength": 256,
                          "type": "string"
                        }
                      }
                    }
                  },
                  "created": {
                    "type": "array",
                    "items": {
                      "minLength": 1,
                      "maxLength": 256,
                      "type": "string"
                    }
                  },
                  "deleted": {
                    "type": "array",
                    "items": {
                      "minLength": 1,
                      "maxLength": 256,
                      "type": "string"
                    }
                  },
                  "preview": {
                    "type": "boolean",
                    "enumValues": [
                      true
                    ]
                  }
                }
              }
            ]
          }
        }
      }
    }
  ]
}
```

### 400

```json
{
  "statusCode": "400",
  "description": "Invalid batch or cell values; no changes stored",
  "headers": [],
  "content": [
    {
      "contentType": "application/json",
      "schema": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "type",
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "row_ref",
                    "column_id",
                    "reason"
                  ],
                  "properties": {
                    "column_id": {
                      "type": "string"
                    },
                    "reason": {
                      "type": "string"
                    },
                    "row_ref": {
                      "type": "string"
                    }
                  }
                }
              },
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  ]
}
```

### 401

```json
{
  "statusCode": "401",
  "description": "Authentication required or credentials invalid. Not retryable without new credentials.\nCommon error codes: `invalid_api_key` (key is missing, malformed, or revoked),\n`expired_session` (session cookie expired — re-authenticate via the web app).\n",
  "headers": [],
  "content": [
    {
      "contentType": "application/json",
      "schema": {
        "name": "ApiError",
        "type": "object",
        "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "description": "Failure category, code and human-readable explanation, with optional field or validation context.",
            "required": [
              "type",
              "code",
              "message",
              "doc_url"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.",
                "enumValues": [
                  "invalid_request_error",
                  "authentication_error",
                  "permission_error",
                  "entitlement_error",
                  "not_found_error",
                  "rate_limit_error",
                  "api_error"
                ]
              },
              "code": {
                "type": "string",
                "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.",
                "example": "Request validation failed"
              },
              "feature": {
                "type": "string",
                "description": "Entitlement capability required for a 402 denial.",
                "example": "included_engines"
              },
              "upgrade_url": {
                "type": "string",
                "format": "uri",
                "description": "Plan or grant recovery destination supplied with a 402 denial."
              },
              "param": {
                "type": "string",
                "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.",
                "example": "limit"
              },
              "doc_url": {
                "type": "string",
                "format": "uri",
                "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.",
                "example": "https://docs.orchestor.io/errors/validation_error"
              },
              "details": {
                "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.",
                "anyOf": [
                  {
                    "type": "array",
                    "description": "Validation issues. A request can have multiple issues, including more than one for the same field.",
                    "example": [
                      {
                        "path": "items.0.name",
                        "message": "Invalid input",
                        "code": "invalid_type"
                      }
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "path",
                        "message",
                        "code"
                      ],
                      "properties": {
                        "path": {
                          "type": "string",
                          "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.",
                          "example": "items.0.name"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.",
                          "example": "Invalid input"
                        },
                        "code": {
                          "type": "string",
                          "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.",
                          "example": "invalid_type"
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.",
                    "additionalProperties": true
                  }
                ]
              }
            }
          }
        }
      },
      "example": {
        "error": {
          "type": "authentication_error",
          "code": "invalid_api_key",
          "message": "Invalid API key provided",
          "doc_url": "https://docs.orchestor.io/api-reference/errors#authentication"
        }
      }
    }
  ]
}
```

### 404

```json
{
  "statusCode": "404",
  "description": "The requested resource is unavailable in the current workspace or route scope. Check the identifier and selected workspace. The same response can be returned for a deleted resource or a resource outside your access scope.",
  "headers": [],
  "content": [
    {
      "contentType": "application/json",
      "schema": {
        "name": "ApiError",
        "type": "object",
        "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "description": "Failure category, code and human-readable explanation, with optional field or validation context.",
            "required": [
              "type",
              "code",
              "message",
              "doc_url"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.",
                "enumValues": [
                  "invalid_request_error",
                  "authentication_error",
                  "permission_error",
                  "entitlement_error",
                  "not_found_error",
                  "rate_limit_error",
                  "api_error"
                ]
              },
              "code": {
                "type": "string",
                "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.",
                "example": "Request validation failed"
              },
              "feature": {
                "type": "string",
                "description": "Entitlement capability required for a 402 denial.",
                "example": "included_engines"
              },
              "upgrade_url": {
                "type": "string",
                "format": "uri",
                "description": "Plan or grant recovery destination supplied with a 402 denial."
              },
              "param": {
                "type": "string",
                "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.",
                "example": "limit"
              },
              "doc_url": {
                "type": "string",
                "format": "uri",
                "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.",
                "example": "https://docs.orchestor.io/errors/validation_error"
              },
              "details": {
                "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.",
                "anyOf": [
                  {
                    "type": "array",
                    "description": "Validation issues. A request can have multiple issues, including more than one for the same field.",
                    "example": [
                      {
                        "path": "items.0.name",
                        "message": "Invalid input",
                        "code": "invalid_type"
                      }
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "path",
                        "message",
                        "code"
                      ],
                      "properties": {
                        "path": {
                          "type": "string",
                          "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.",
                          "example": "items.0.name"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.",
                          "example": "Invalid input"
                        },
                        "code": {
                          "type": "string",
                          "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.",
                          "example": "invalid_type"
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.",
                    "additionalProperties": true
                  }
                ]
              }
            }
          }
        }
      },
      "example": {
        "error": {
          "type": "not_found_error",
          "code": "resource_not_found",
          "message": "Resource not found",
          "doc_url": "https://docs.orchestor.io/api-reference/errors#not-found"
        }
      }
    }
  ]
}
```

### 409

```json
{
  "statusCode": "409",
  "description": "Sheet changed or is unavailable. Reload before writing.",
  "headers": [],
  "content": []
}
```

---

[Documentation index](https://orchestor.io/docs/llms.txt)