Skip to main content
Use this endpoint to commit a write that was returned by POST /agent/chat. GridOS uses a two-step preview-then-apply model: the chat endpoint shows you what the agent would write, and this endpoint makes it permanent. You should pass the agent_id, target_cell, values, and chart_spec fields directly from the chat response — do not modify them, as the kernel uses them to resolve any cell collisions consistently with what was previewed.
If the requested target_cell is already occupied, GridOS shifts the write in the direction specified by shift_direction and reports the actual destination in actual_target. A status of "Collision Resolved" means the write landed somewhere other than the cell originally requested.

​
Request

​
agent_id
string
required
The agent ID from the chat response. Pass the agent_id field through unchanged.
​
target_cell
string
required
The top-left cell where the write should begin, in A1 notation. Use the target_cell value from the chat response — not original_request.
​
values
array
required
A 2-D array of cell values to write, in row-major order. This is the values field from the chat response. Each inner array represents one row; values can be strings, numbers, booleans, or null.
​
sheet
string
Name of the sheet to write to. Defaults to the active sheet when omitted. Use the sheet value from the chat response to ensure consistency.
​
shift_direction
string
default:"right"
Direction to shift data when the target region is already occupied.
  • "right" — shift data to the right by the required number of columns (default)
  • "down" — shift data downward by the required number of rows
​
chart_spec
object
The chart specification from the chat response. Pass this through unchanged if the agent proposed a chart; omit or set to null if it did not. When provided, GridOS creates or updates the chart after writing the cell data.

​
Response

​
status
string
The outcome of the write operation.
  • "Success" — data was written to the exact cell requested
  • "Collision Resolved" — the target was occupied; data was shifted and written at actual_target
  • "Partial" — cell data was written successfully but chart creation failed; see chart_error
​
sheet
string
The name of the sheet that was written to.
​
actual_target
string
The cell address where data was actually written, in A1 notation. When status is "Success" this matches the requested target_cell. When status is "Collision Resolved" this will differ.
​
chart
object | null
The created or updated chart object when a chart_spec was provided and chart creation succeeded. Contains the full chart metadata including its assigned id. null when no chart was requested.
​
chart_error
string | null
An error message describing why chart creation failed, when status is "Partial". The cell data was still written; only the chart was skipped. null on success.
Only apply a preview once. Calling this endpoint multiple times with the same payload will write duplicate data. If you need to undo a write, use the clear or cell-update endpoints to revert the affected cells manually.

​
Example

The typical pattern is to take the fields from a POST /agent/chat response and forward them directly to this endpoint.

​
Request

{
  "agent_id": "finance",
  "target_cell": "B3",
  "values": [[100, 110, 121, 133.1]],
  "sheet": "Sheet1",
  "shift_direction": "right",
  "chart_spec": null
}

​
Response — success, no collision

{
  "status": "Success",
  "sheet": "Sheet1",
  "actual_target": "B3",
  "chart": null
}

​
Response — collision resolved

{
  "status": "Collision Resolved",
  "sheet": "Sheet1",
  "actual_target": "F3",
  "chart": null
}

​
Request with chart

{
  "agent_id": "finance",
  "target_cell": "B3",
  "values": [
    ["Q1", "Q2", "Q3", "Q4"],
    [100, 110, 121, 133.1]
  ],
  "sheet": "Sheet1",
  "shift_direction": "right",
  "chart_spec": {
    "data_range": "B3:E4",
    "chart_type": "bar",
    "title": "Quarterly Revenue Forecast",
    "anchor_cell": "G3",
    "orientation": "columns"
  }
}

​
Response with chart

{
  "status": "Success",
  "sheet": "Sheet1",
  "actual_target": "B3",
  "chart": {
    "id": "chart-a1b2c3",
    "anchor_cell": "G3",
    "data_range": "B3:E4",
    "chart_type": "bar",
    "title": "Quarterly Revenue Forecast",
    "width": 400,
    "height": 280,
    "orientation": "columns"
  }
}