add_sheet_conditional_format
Add a conditional formatting rule to a range: a boolean rule (the default) that formats the cells meeting a condition, or a 2- or 3-stop colour gradient.
writeGoogle Sheets, Docs & Drive
Call it
In an AI client (MCP)
{
"name": "add_sheet_conditional_format",
"arguments": {
"spreadsheet_id": "<spreadsheet_id>",
"range_": "<range_>"
}
}From code (Tool API)
curl -X POST https://api.sellersheetai.com/api/v1/tools/add_sheet_conditional_format \
-H "Authorization: Bearer $SELLERSHEET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spreadsheet_id":"<spreadsheet_id>","range_":"<range_>"}'Early access — the Tool API is open on request, contact us.
Arguments
| Name | Type | Description |
|---|---|---|
spreadsheet_idrequired | string | the spreadsheet ID (from its URL or get_sheet_metadata). |
range_required | string | A1 range with sheet name (e.g. 'VOC!C4:C18'). |
rule_type | string | the boolean condition; ignored when gradient is true. Allowed: NUMBER_GREATER (default), NUMBER_GREATER_THAN_EQ, NUMBER_LESS, NUMBER_LESS_THAN_EQ, NUMBER_EQ, NUMBER_NOT_EQ, NUMBER_BETWEEN, NUMBER_NOT_BETWEEN, TEXT_CONTAINS, TEXT_NOT_CONTAINS, TEXT_STARTS_WITH, TEXT_ENDS_WITH, TEXT_EQ, BLANK, NOT_BLANK, CUSTOM_FORMULA.Default: "NUMBER_GREATER" |
values | object[] | the condition's values — one for most types, two for NUMBER_BETWEEN / NUMBER_NOT_BETWEEN, one formula ('=…') for CUSTOM_FORMULA, none for BLANK / NOT_BLANK. |
background_color | object[] | the format a boolean rule applies; colours are RGB floats 0–1. |
font_color | object[] | the format a boolean rule applies; colours are RGB floats 0–1. |
bold | boolean | the format a boolean rule applies; colours are RGB floats 0–1. |
gradient | boolean | true for a colour-scale rule instead of a boolean one.Default: false |
min_color | object[] | RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop. |
mid_color | object[] | RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop. |
max_color | object[] | RGB floats 0–1. min_color and max_color are required when gradient is true; mid_color adds a third stop. |
min_value | string | where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given.Default: "MIN" |
mid_value | string | where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given. |
max_value | string | where each stop sits — 'MIN', 'MAX', 'NUMBER:5', 'PERCENT:50', 'PERCENTILE:90' or a plain number. mid_value defaults to 'PERCENT:50' when mid_color is given.Default: "MAX" |
Result
Every tool answers {notification, data, human_action}; data carries:
- { sheetId: int, applied: true }
Gotchas
- A boolean rule needs at least one of background_color, font_color or bold, or it is refused. The rule is inserted first (index 0), above every existing rule on the tab. Every range here must name its tab; an open end is allowed ('Tab!C7:C' runs to the bottom, 'Tab!A:D' is whole columns); a range without a tab ('A1:D10') is refused.
Example
# Green rows where rank ≤ 10
add_sheet_conditional_format(
spreadsheet_id='1ABC...',
range_='Competitors!A4:F18',
rule_type='NUMBER_LESS_THAN_EQ',
values=['10'],
background_color=[0.85, 0.92, 0.83],
bold=True,
)
# Green (low) → yellow → red (high) on the gap_ratio column
add_sheet_conditional_format(
spreadsheet_id='1ABC...',
range_='VOC!D4:D14',
gradient=True,
min_color=[0.57, 0.77, 0.49],
mid_color=[1.0, 0.95, 0.6],
max_color=[0.91, 0.26, 0.21],
min_value='MIN',
mid_value='NUMBER:5',
max_value='MAX',
)