xlsx-for-ai public API — public-stable tools v1.0.0 · 0ce6bebd40bc

The stability-guaranteed subset of the xlsx-for-ai HTTP API. Each path is a stateless base64-in / base64-out tool. Request schemas are generated from the live server routes; a breaking change to any schema below requires an anchored SPM sign-off (see the change-review gate, scripts/public-contract-gate.mts). Auth: Authorization: Bearer <xfa_… key from POST /api/v1/clients>. Free tier: a monthly allowance of files you can process, no card required.

On-ramp — get an API key

Every call is authenticated with a bearer API key. There is no signup form: call POST /api/v1/clients with no authentication to mint an anonymous client_id / api_key pair, then send that key back as an Authorization: Bearer <api_key> header on every tool call below.

curl -sX POST https://api.xlsx-for-ai.dev/api/v1/clients \
  -H 'content-type: application/json' \
  -d '{"client_version":"1.0.0","platform":"cli"}'

The response is a JSON object shaped { "client_id": "...", "api_key": "xfa_..." }. Store the api_key — it is not shown again.

Then call any documented tool with that key:

curl -sX POST https://api.xlsx-for-ai.dev/api/v1/tools/csv_check \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <api_key>' \
  -d '{}'

Free tier: a monthly allowance of files you can process, no card required.

Tools

csv_check
xlsx_aggregate
xlsx_charts
xlsx_check
xlsx_comments
xlsx_conditional_formats
xlsx_convert
xlsx_data_clean
xlsx_data_validations
xlsx_describe
xlsx_diff
xlsx_doctor
xlsx_eval
xlsx_external_links
xlsx_filter
xlsx_form_controls
xlsx_formulas
xlsx_healer_cure
xlsx_healer_diagnose
xlsx_healer_intent
xlsx_healer_simulate
xlsx_hyperlinks
xlsx_images
xlsx_list_sheets
xlsx_macros
xlsx_merged_cells
xlsx_named_ranges
xlsx_pii_clean
xlsx_pii_scan
xlsx_pivot
xlsx_pivot_tables
xlsx_post_slack
xlsx_post_teams
xlsx_print_settings
xlsx_properties
xlsx_protection
xlsx_read
xlsx_read_handle
xlsx_receipt
xlsx_redact
xlsx_schema
xlsx_session_set_validations
xlsx_slicers_timelines
xlsx_sort
xlsx_stamp
xlsx_styles
xlsx_tables
xlsx_topology
xlsx_validate
xlsx_value_counts
xlsx_vault_cure
xlsx_vault_scan
xlsx_verify_receipt
xlsx_verify_stamp
xlsx_workbook_views
xlsx_write

`csv_check`

POST /api/v1/tools/csv_check — Verify CSV structure and injection safety before it is imported anywhere else.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_aggregate`

POST /api/v1/tools/xlsx_aggregate — Group-and-aggregate (sum/mean/min/max/count/count_distinct) on a spreadsheet — reshape rows into per-group summaries.

Auth: Authorization: Bearer <api_key> (required)

Request body required

aggs array required items: object
- as string optional
- column string required
- func string required enum: sum, mean, min, max, count, count_distinct
file_b64 string required
group_by array required items: string
options object optional
- header_row integer optional minimum: 0
- limit integer optional minimum: 1 · maximum: 1000
- sheet string optional
- sort string optional enum: asc, desc, none

Raw JSON Schema

{
  "properties": {
    "aggs": {
      "items": {
        "properties": {
          "as": {
            "type": "string"
          },
          "column": {
            "type": "string"
          },
          "func": {
            "enum": [
              "sum",
              "mean",
              "min",
              "max",
              "count",
              "count_distinct"
            ],
            "type": "string"
          }
        },
        "required": [
          "column",
          "func"
        ],
        "type": "object"
      },
      "maxItems": 16,
      "minItems": 1,
      "type": "array"
    },
    "file_b64": {
      "type": "string"
    },
    "group_by": {
      "items": {
        "type": "string"
      },
      "maxItems": 6,
      "minItems": 1,
      "type": "array"
    },
    "options": {
      "properties": {
        "header_row": {
          "minimum": 0,
          "type": "integer"
        },
        "limit": {
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        },
        "sort": {
          "enum": [
            "asc",
            "desc",
            "none"
          ],
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "aggs",
    "file_b64",
    "group_by"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_charts`

POST /api/v1/tools/xlsx_charts — List every chart in a workbook — type, title, axis titles, and the cell ranges each series pulls from.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- limit integer optional minimum: 1 · maximum: 500
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "limit": {
          "maximum": 500,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_check`

POST /api/v1/tools/xlsx_check — Verify a workbook with an independent engine — cross-checks the primary parser against a second renderer.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_comments`

POST /api/v1/tools/xlsx_comments — List every cell comment — legacy notes and modern threaded comments — with author, text, and reply thread.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- limit integer optional minimum: 1 · maximum: 5000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "limit": {
          "maximum": 5000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_conditional_formats`

POST /api/v1/tools/xlsx_conditional_formats — List every conditional formatting rule (color scales, data bars, icon sets, formula-based highlights, …) with range, type, and priority.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- limit integer optional minimum: 1 · maximum: 5000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "limit": {
          "maximum": 5000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_convert`

POST /api/v1/tools/xlsx_convert — Convert a spreadsheet between formats — reads xlsx, xls, xlsb, ods/fods, csv/tsv, dbf, sylk, dif and prn (25+ inputs), plus a file exported or downloaded from Google Sheets; emits xlsx, csv, tsv, json, md, or html. Often the only way to get a legacy .xls or .dbf into an agent that can't upload one directly. Deterministic and structural, no LLM mapping; exact formula/structure preservation holds on the own-engine path only, so check served_engine in the response (and decline_reason if it reads "incumbent") — a compatibility-engine fallback may not preserve charts, pivots, or other advanced features.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- flatten string optional enum: dot, index, explode
  JSON input only: how to flatten a nested array into columns — "dot" (default) stringifies it into one cell, "index" gives one column per array position, "explode" repeats the record across one output row per element.
- sheet string optional
  Render only this sheet (text outputs only).
- sheets string optional enum: all, first
to string required enum: csv, tsv, txt, html, md, json, dif, sylk, eth, prn, rtf, xlsx, xlsb, xlsm, xls, ods, fods, dbf
Target format. Binary formats return bytes in _meta.file_b64; text formats render in body.

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "flatten": {
          "description": "JSON input only: how to flatten a nested array into columns — \"dot\" (default) stringifies it into one cell, \"index\" gives one column per array position, \"explode\" repeats the record across one output row per element.",
          "enum": [
            "dot",
            "index",
            "explode"
          ],
          "type": "string"
        },
        "sheet": {
          "description": "Render only this sheet (text outputs only).",
          "type": "string"
        },
        "sheets": {
          "enum": [
            "all",
            "first"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "to": {
      "description": "Target format. Binary formats return bytes in _meta.file_b64; text formats render in body.",
      "enum": [
        "csv",
        "tsv",
        "txt",
        "html",
        "md",
        "json",
        "dif",
        "sylk",
        "eth",
        "prn",
        "rtf",
        "xlsx",
        "xlsb",
        "xlsm",
        "xls",
        "ods",
        "fods",
        "dbf"
      ],
      "type": "string"
    }
  },
  "required": [
    "file_b64",
    "to"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_data_clean`

POST /api/v1/tools/xlsx_data_clean — Scan for the common data-grime issues (NA variants, merged-cell residue, type-coercion mistakes, stray header/footer rows, mojibake, duplicate headers) and either flag or fix them.

Auth: Authorization: Bearer <api_key> (required)

Request body required

accept_findings array optional items: string
detectors array optional items: string
file_b64 string required
mode string optional enum: diagnose, execute
options object optional additionalProperties: false
- auto_accept_above number optional minimum: 0 · maximum: 1
- column_roles object optional additionalProperties: string
- date_ratio_threshold number optional minimum: 0 · maximum: 1
- dedup_compare_columns array optional items: string
- dedup_ignore_case boolean optional
- header_scan_depth integer optional minimum: 2 · maximum: 50
- identity_uniqueness_threshold number optional minimum: 0 · maximum: 1
- impute_fixed_value number optional
- impute_strategy string optional enum: mean, median, mode, fixed
- na_canonical string optional
- numeric_ratio_threshold number optional minimum: 0 · maximum: 1
- trailing_threshold integer optional minimum: 1 · maximum: 100

overrides array optional items: object

action string required enum: skip, flag_only, force, accept
detector string required
params object optional

scope object required additionalProperties: false

{
  "additionalProperties": false,
  "properties": {
    "column_letter": {
      "type": "string"
    },
    "region": {
      "additionalProperties": false,
      "properties": {
        "bottom_right": {
          "type": "string"
        },
        "top_left": {
          "type": "string"
        }
      },
      "required": [
        "bottom_right",
        "top_left"
      ],
      "type": "object"
    },
    "sheet": {
      "type": "string"
    }
  },
  "required": [
    "sheet"
  ],
  "type": "object"
}

reject_findings array optional items: string
sheets array optional items: string

Raw JSON Schema

{
  "properties": {
    "accept_findings": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "detectors": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "file_b64": {
      "type": "string"
    },
    "mode": {
      "enum": [
        "diagnose",
        "execute"
      ],
      "type": "string"
    },
    "options": {
      "additionalProperties": false,
      "properties": {
        "auto_accept_above": {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        "column_roles": {
          "additionalProperties": {
            "enum": [
              "numeric_measurement",
              "categorical",
              "identity_pii",
              "date",
              "free_text"
            ],
            "type": "string"
          },
          "type": "object"
        },
        "date_ratio_threshold": {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        "dedup_compare_columns": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "dedup_ignore_case": {
          "type": "boolean"
        },
        "header_scan_depth": {
          "maximum": 50,
          "minimum": 2,
          "type": "integer"
        },
        "identity_uniqueness_threshold": {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        "impute_fixed_value": {
          "type": "number"
        },
        "impute_strategy": {
          "enum": [
            "mean",
            "median",
            "mode",
            "fixed"
          ],
          "type": "string"
        },
        "na_canonical": {
          "type": "string"
        },
        "numeric_ratio_threshold": {
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        "trailing_threshold": {
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "overrides": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "action": {
            "enum": [
              "skip",
              "flag_only",
              "force",
              "accept"
            ],
            "type": "string"
          },
          "detector": {
            "type": "string"
          },
          "params": {
            "type": "object"
          },
          "scope": {
            "additionalProperties": false,
            "properties": {
              "column_letter": {
                "type": "string"
              },
              "region": {
                "additionalProperties": false,
                "properties": {
                  "bottom_right": {
                    "type": "string"
                  },
                  "top_left": {
                    "type": "string"
                  }
                },
                "required": [
                  "bottom_right",
                  "top_left"
                ],
                "type": "object"
              },
              "sheet": {
                "type": "string"
              }
            },
            "required": [
              "sheet"
            ],
            "type": "object"
          }
        },
        "required": [
          "action",
          "detector",
          "scope"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "reject_findings": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "sheets": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_data_validations`

POST /api/v1/tools/xlsx_data_validations — List every cell-level data validation rule (dropdowns, numeric/date bounds, text-length caps, custom formulas) Excel enforces on entry.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_describe`

POST /api/v1/tools/xlsx_describe — Pandas-style summary statistics per column: count, nulls, unique, min/max/mean/std for numerics.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- header_row integer optional minimum: 0
- max_rows integer optional minimum: 1 · maximum: 100000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "header_row": {
          "minimum": 0,
          "type": "integer"
        },
        "max_rows": {
          "maximum": 100000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_diff`

POST /api/v1/tools/xlsx_diff — Compute a deterministic semantic diff between two workbooks — cell-level deltas, formula changes, added/removed rows.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_a_b64 string required
file_b_b64 string required
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_a_b64": {
      "type": "string"
    },
    "file_b_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_a_b64",
    "file_b_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_doctor`

POST /api/v1/tools/xlsx_doctor — One-call workbook health report: macros, external refs, hidden sheets, missing metadata, oversized images, ranked HIGH/MEDIUM/LOW findings.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_eval`

POST /api/v1/tools/xlsx_eval — Evaluate Excel formulas against a workbook via a formula engine — pass ad-hoc formulas or re-evaluate specific cell refs, never trusting a stale cached value.

Auth: Authorization: Bearer <api_key> (required)

Request body required

cells array optional items: string
file_b64 string required
formulas array optional items: string
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "cells": {
      "items": {
        "maxLength": 64,
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 100,
      "type": "array"
    },
    "file_b64": {
      "type": "string"
    },
    "formulas": {
      "items": {
        "maxLength": 4096,
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 100,
      "type": "array"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_external_links`

POST /api/v1/tools/xlsx_external_links — List every external workbook reference this file depends on, classified (http / network share / absolute / relative) with cached-value counts.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_filter`

POST /api/v1/tools/xlsx_filter — Row filter with AND-combined predicates (eq/ne/gt/gte/lt/lte/contains/in/is_null/not_null) on real, formula-evaluated cell values.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- header_row integer optional minimum: 0
- limit integer optional minimum: 1 · maximum: 1000
- sheet string optional
predicates array required items: object
- column string required
- op string required enum: eq, ne, gt, gte, lt, lte, contains, not_contains, in, not_in, is_null, not_null
- value any optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "header_row": {
          "minimum": 0,
          "type": "integer"
        },
        "limit": {
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "predicates": {
      "items": {
        "properties": {
          "column": {
            "type": "string"
          },
          "op": {
            "enum": [
              "eq",
              "ne",
              "gt",
              "gte",
              "lt",
              "lte",
              "contains",
              "not_contains",
              "in",
              "not_in",
              "is_null",
              "not_null"
            ],
            "type": "string"
          },
          "value": {}
        },
        "required": [
          "column",
          "op"
        ],
        "type": "object"
      },
      "maxItems": 16,
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "file_b64",
    "predicates"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_form_controls`

POST /api/v1/tools/xlsx_form_controls — List every form control (checkbox, button, dropdown, list box, option button, scroll bar, spinner, …) with its linked cell and current value.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_formulas`

POST /api/v1/tools/xlsx_formulas — Extract every formula in a workbook — cell coordinate, formula text, cached result — for auditing or bulk transformation.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- include_results boolean optional
- limit integer optional minimum: 1 · maximum: 5000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "include_results": {
          "type": "boolean"
        },
        "limit": {
          "maximum": 5000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_healer_cure`

POST /api/v1/tools/xlsx_healer_cure — Apply one specific repair to a diagnosed workbook. For broken external references: rewrite ref paths, freeze / redirect / localize a deleted source, strip embedded credentials, or collapse multi-hop chains. For Google-Sheets-to-Excel export damage: flag each dead Sheets-only formula with an in-cell note so the loss is visible (it does NOT recompute the function — a Sheets-only function has no Excel equivalent to compute), trim an oversized used-range, and compact repeated formulas into Excel shared-formula form.

Auth: Authorization: Bearer <api_key> (required)

Request body required

cure_params object optional
file_b64 string required
intent string optional
mode string optional enum: as_copy, in_place
operation string required

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "cure_params": {
      "type": "object"
    },
    "file_b64": {
      "type": "string"
    },
    "intent": {
      "type": "string"
    },
    "mode": {
      "enum": [
        "as_copy",
        "in_place"
      ],
      "type": "string"
    },
    "operation": {
      "type": "string"
    }
  },
  "required": [
    "file_b64",
    "operation"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_healer_diagnose`

POST /api/v1/tools/xlsx_healer_diagnose — Produce a structured report of repairable damage in a workbook, keyed to the cure operations. Two families: (1) broken or at-risk external references — moved, deleted, or permission-denied sources and #REF! chains; (2) Google-Sheets-to-Excel export damage — Sheets-only functions such as QUERY, ARRAYFORMULA, IMPORTRANGE, or GOOGLEFINANCE that Excel cannot evaluate and that arrive as dead formula text or a #NAME? error (surfaced as an unverified value to double-check), an oversized used-range, and repeated formulas left un-compacted. Every finding is reported, not altered in place.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_healer_intent`

POST /api/v1/tools/xlsx_healer_intent — Goal-driven healing: declare an intent (make-it-work / make-standalone / migrate) and let the healer plan + apply the operation sequence.

Auth: Authorization: Bearer <api_key> (required)

Request body required

confirm boolean optional
file_b64 string required
intent string required
intent_params object optional additionalProperties: false
- from string optional
- to string optional
mode string optional enum: as_copy, in_place
operation string optional

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "confirm": {
      "type": "boolean"
    },
    "file_b64": {
      "type": "string"
    },
    "intent": {
      "type": "string"
    },
    "intent_params": {
      "additionalProperties": false,
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "mode": {
      "enum": [
        "as_copy",
        "in_place"
      ],
      "type": "string"
    },
    "operation": {
      "type": "string"
    }
  },
  "required": [
    "file_b64",
    "intent"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_healer_simulate`

POST /api/v1/tools/xlsx_healer_simulate — Simulate recipient-side accessibility of a workbook's external references — read-only, no output workbook.

Auth: Authorization: Bearer <api_key> (required)

Request body required

accessible_paths array required items: string
file_b64 string required

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "accessible_paths": {
      "items": {
        "type": "string"
      },
      "maxItems": 1000,
      "type": "array"
    },
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "accessible_paths",
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_hyperlinks`

POST /api/v1/tools/xlsx_hyperlinks — List every hyperlink with its anchor cell, target, display text, tooltip, and a kind classifier (external / internal / mailto).

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- limit integer optional minimum: 1 · maximum: 5000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "limit": {
          "maximum": 5000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_images`

POST /api/v1/tools/xlsx_images — List every embedded image with format, size, sheet attribution, and the cell range it floats over.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- limit integer optional minimum: 1 · maximum: 1000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "limit": {
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_list_sheets`

POST /api/v1/tools/xlsx_list_sheets — List every sheet in a spreadsheet with its name, dimensions, and visibility.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_macros`

POST /api/v1/tools/xlsx_macros — Inspect an xlsm/xlsb workbook for VBA macro presence, module size, and likely module names, with a short safety note.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_merged_cells`

POST /api/v1/tools/xlsx_merged_cells — List every merged-cell region with its master value, range, and a layout-kind heuristic (header / horizontal / vertical / block).

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- limit integer optional minimum: 1 · maximum: 5000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "limit": {
          "maximum": 5000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_named_ranges`

POST /api/v1/tools/xlsx_named_ranges — List every defined name (named range) in a workbook — name, scope, kind, and reference.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_pii_clean`

POST /api/v1/tools/xlsx_pii_clean — Redact personal or sensitive data from a spreadsheet.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required maxLength: 279685803
mode string optional enum: as_copy, in_place
selection object optional additionalProperties: false
- all boolean optional
- finding_ids array optional items: string
- type_keys array optional items: string
simulate boolean optional

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "file_b64": {
      "maxLength": 279685803,
      "type": "string"
    },
    "mode": {
      "enum": [
        "as_copy",
        "in_place"
      ],
      "type": "string"
    },
    "selection": {
      "additionalProperties": false,
      "properties": {
        "all": {
          "type": "boolean"
        },
        "finding_ids": {
          "items": {
            "pattern": "^[0-9a-f]{64}$",
            "type": "string"
          },
          "maxItems": 10000,
          "type": "array"
        },
        "type_keys": {
          "items": {
            "maxLength": 64,
            "type": "string"
          },
          "maxItems": 64,
          "type": "array"
        }
      },
      "type": "object"
    },
    "simulate": {
      "type": "boolean"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_pii_scan`

POST /api/v1/tools/xlsx_pii_scan — Scan a spreadsheet for personal or sensitive data.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required maxLength: 279685803

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "file_b64": {
      "maxLength": 279685803,
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_pivot`

POST /api/v1/tools/xlsx_pivot — Pivot-table reshape — reshape a flat table into a 2D matrix of index × columns with an aggregated value per cell.

Auth: Authorization: Bearer <api_key> (required)

Request body required

agg string optional enum: sum, mean, min, max, count, count_distinct
columns array optional items: string
file_b64 string required
index array required items: string
options object optional
- fill_value any optional
- header_row integer optional minimum: 0
- sheet string optional
values array required items: string

Raw JSON Schema

{
  "properties": {
    "agg": {
      "enum": [
        "sum",
        "mean",
        "min",
        "max",
        "count",
        "count_distinct"
      ],
      "type": "string"
    },
    "columns": {
      "items": {
        "type": "string"
      },
      "maxItems": 4,
      "type": "array"
    },
    "file_b64": {
      "type": "string"
    },
    "index": {
      "items": {
        "type": "string"
      },
      "maxItems": 4,
      "minItems": 1,
      "type": "array"
    },
    "options": {
      "properties": {
        "fill_value": {},
        "header_row": {
          "minimum": 0,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "values": {
      "items": {
        "type": "string"
      },
      "maxItems": 8,
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "file_b64",
    "index",
    "values"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_pivot_tables`

POST /api/v1/tools/xlsx_pivot_tables — List every pre-existing pivot table an Excel user already built — source range, row/column/page fields, and each data field's aggregation.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_post_slack`

POST /api/v1/tools/xlsx_post_slack — Post a spreadsheet to a Slack channel as a file attachment, with an optional accompanying message.

Auth: Authorization: Bearer <api_key> (required)

Request body required

channel string required minLength: 1 · maxLength: 128
file_b64 string optional
filename string optional maxLength: 128
message string optional maxLength: 4000
slack_token string required minLength: 10 · maxLength: 256
workbook_handle string optional minLength: 1 · maxLength: 128

Raw JSON Schema

{
  "properties": {
    "channel": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    },
    "file_b64": {
      "type": "string"
    },
    "filename": {
      "maxLength": 128,
      "type": "string"
    },
    "message": {
      "maxLength": 4000,
      "type": "string"
    },
    "slack_token": {
      "maxLength": 256,
      "minLength": 10,
      "type": "string"
    },
    "workbook_handle": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "channel",
    "slack_token"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_post_teams`

POST /api/v1/tools/xlsx_post_teams — Post a spreadsheet to a Microsoft Teams channel as a file attachment, with an optional accompanying message.

Auth: Authorization: Bearer <api_key> (required)

Request body required

channel_id string required minLength: 1 · maxLength: 128
file_b64 string optional
filename string optional maxLength: 128
graph_token string required minLength: 100 · maxLength: 8192
message string optional maxLength: 4000
team_id string required minLength: 1 · maxLength: 128
workbook_handle string optional minLength: 1 · maxLength: 128

Raw JSON Schema

{
  "properties": {
    "channel_id": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    },
    "file_b64": {
      "type": "string"
    },
    "filename": {
      "maxLength": 128,
      "type": "string"
    },
    "graph_token": {
      "maxLength": 8192,
      "minLength": 100,
      "type": "string"
    },
    "message": {
      "maxLength": 4000,
      "type": "string"
    },
    "team_id": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    },
    "workbook_handle": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "channel_id",
    "graph_token",
    "team_id"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_print_settings`

POST /api/v1/tools/xlsx_print_settings — Surface exactly what Excel would print for each sheet — print area, orientation, paper size, margins, headers/footers, page breaks.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_properties`

POST /api/v1/tools/xlsx_properties — Surface a workbook's identity card — creator, timestamps, title/subject/company, and every custom Info > Properties entry.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_protection`

POST /api/v1/tools/xlsx_protection — Surface every protection setting — workbook lock, per-sheet protection, per-action allow/block list, and which cells stay editable.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_read`

POST /api/v1/tools/xlsx_read — Read a spreadsheet as text (markdown, JSON, or SQL) — from an uploaded .xlsx/.xls/.csv file, or from a live Google Sheet read by ID; for a Google Sheet pass source:"gsheets", spreadsheet_id, and a readonly access_token (connects directly, no upload).

Auth: Authorization: Bearer <api_key> (required)

Request body required

access_token string optional
evaluate boolean optional
file_b64 string optional
options object optional
- format string optional
- maxRows integer optional minimum: 1 · maximum: 100000
- sheet string optional
source string optional enum: gsheets
spreadsheet_id string optional

Raw JSON Schema

{
  "properties": {
    "access_token": {
      "type": "string"
    },
    "evaluate": {
      "type": "boolean"
    },
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "format": {
          "type": "string"
        },
        "maxRows": {
          "maximum": 100000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "source": {
      "enum": [
        "gsheets"
      ],
      "type": "string"
    },
    "spreadsheet_id": {
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_read_handle`

POST /api/v1/tools/xlsx_read_handle — [Stateful · session/handle-based] Read a workbook already uploaded via the chunked cache flow, by its server-side handle — skips re-sending the bytes.

Auth: Authorization: Bearer <api_key> (required)

Request body required

options object optional
- format string optional enum: md, json
- sheet string optional
workbook_handle string required minLength: 1 · maxLength: 128 · pattern: ^[^\u0000-\u001f\u007f\s:*?\[\]]+$

Raw JSON Schema

{
  "properties": {
    "options": {
      "properties": {
        "format": {
          "enum": [
            "md",
            "json"
          ],
          "type": "string"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "workbook_handle": {
      "maxLength": 128,
      "minLength": 1,
      "pattern": "^[^\\u0000-\\u001f\\u007f\\s:*?\\[\\]]+$",
      "type": "string"
    }
  },
  "required": [
    "workbook_handle"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_receipt`

POST /api/v1/tools/xlsx_receipt — Attach a cryptographic AI-generation receipt to a workbook — who/what/when generated it, against which inputs.

Auth: Authorization: Bearer <api_key> (required)

Request body required

agent object required
- display_name string optional maxLength: 256
- identity_url string optional maxLength: 512
- name string required minLength: 1 · maxLength: 128 · pattern: ^[a-z0-9][a-z0-9\-_/.:]{0,127}$
covers_sheets array optional items: string
description string optional maxLength: 256
file_b64 string optional

inputs object optional

custom object optional
mcp_tools_called array optional items: string
prompt_hash string optional pattern: ^[a-f0-9]{64}$

source_file_hashes array optional items: object

{
  "properties": {
    "name": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "sha256": {
      "pattern": "^[a-f0-9]{64}$",
      "type": "string"
    }
  },
  "required": [
    "name",
    "sha256"
  ],
  "type": "object"
}

workbook_handle string optional minLength: 1 · maxLength: 128

Raw JSON Schema

{
  "properties": {
    "agent": {
      "properties": {
        "display_name": {
          "maxLength": 256,
          "type": "string"
        },
        "identity_url": {
          "maxLength": 512,
          "type": "string"
        },
        "name": {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[a-z0-9][a-z0-9\\-_/.:]{0,127}$",
          "type": "string"
        }
      },
      "required": [
        "name"
      ],
      "type": "object"
    },
    "covers_sheets": {
      "items": {
        "maxLength": 128,
        "type": "string"
      },
      "maxItems": 100,
      "type": "array"
    },
    "description": {
      "maxLength": 256,
      "type": "string"
    },
    "file_b64": {
      "type": "string"
    },
    "inputs": {
      "properties": {
        "custom": {
          "type": "object"
        },
        "mcp_tools_called": {
          "items": {
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "maxItems": 100,
          "type": "array"
        },
        "prompt_hash": {
          "pattern": "^[a-f0-9]{64}$",
          "type": "string"
        },
        "source_file_hashes": {
          "items": {
            "properties": {
              "name": {
                "maxLength": 256,
                "minLength": 1,
                "type": "string"
              },
              "sha256": {
                "pattern": "^[a-f0-9]{64}$",
                "type": "string"
              }
            },
            "required": [
              "name",
              "sha256"
            ],
            "type": "object"
          },
          "maxItems": 200,
          "type": "array"
        }
      },
      "type": "object"
    },
    "workbook_handle": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_redact`

POST /api/v1/tools/xlsx_redact — Redact PII and sensitive values from a spreadsheet before sharing or archiving, preserving formulas/comments/styles by default.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- mode string optional enum: pii, scaffold, none
- strip_comments boolean optional
- strip_formulas boolean optional
- strip_macros boolean optional
- strip_metadata boolean optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "mode": {
          "enum": [
            "pii",
            "scaffold",
            "none"
          ],
          "type": "string"
        },
        "strip_comments": {
          "type": "boolean"
        },
        "strip_formulas": {
          "type": "boolean"
        },
        "strip_macros": {
          "type": "boolean"
        },
        "strip_metadata": {
          "type": "boolean"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_schema`

POST /api/v1/tools/xlsx_schema — Infer per-column types from the first rows of a sheet, with sample values and confidence.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- range string optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "range": {
          "type": "string"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_session_set_validations`

POST /api/v1/tools/xlsx_session_set_validations — [Stateful · session/handle-based] Configure per-session data-validation rules the server applies to subsequent calls in the same session.

Auth: Authorization: Bearer <api_key> (required)

Request body required

session_id string required minLength: 16 · maxLength: 128
validations array required items: object
- ref string required
- sheet string required
- type string required

Raw JSON Schema

{
  "properties": {
    "session_id": {
      "maxLength": 128,
      "minLength": 16,
      "type": "string"
    },
    "validations": {
      "items": {
        "additionalProperties": true,
        "properties": {
          "ref": {
            "type": "string"
          },
          "sheet": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "ref",
          "sheet",
          "type"
        ],
        "type": "object"
      },
      "maxItems": 5000,
      "minItems": 1,
      "type": "array"
    }
  },
  "required": [
    "session_id",
    "validations"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_slicers_timelines`

POST /api/v1/tools/xlsx_slicers_timelines — List every slicer and timeline (interactive filter controls) in a workbook with their source bindings.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_sort`

POST /api/v1/tools/xlsx_sort — Multi-column sort with per-column direction — stable, type-aware, nulls last.

Auth: Authorization: Bearer <api_key> (required)

Request body required

by array required items: object
- column string required
- direction string optional enum: asc, desc
file_b64 string required
options object optional
- header_row integer optional minimum: 0
- limit integer optional minimum: 1 · maximum: 1000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "by": {
      "items": {
        "properties": {
          "column": {
            "type": "string"
          },
          "direction": {
            "enum": [
              "asc",
              "desc"
            ],
            "type": "string"
          }
        },
        "required": [
          "column"
        ],
        "type": "object"
      },
      "maxItems": 8,
      "minItems": 1,
      "type": "array"
    },
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "header_row": {
          "minimum": 0,
          "type": "integer"
        },
        "limit": {
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "by",
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_stamp`

POST /api/v1/tools/xlsx_stamp — Sign a workbook with a cryptographic integrity-verification stamp — which checks it passed, when, tamper-evident.

Auth: Authorization: Bearer <api_key> (required)

Request body required

checks array required items: object
- detail string optional maxLength: 1024
- id string required minLength: 1 · maxLength: 128
- name string required minLength: 1 · maxLength: 256
- status string required enum: passed, failed, skipped
exclude_sheets array optional items: string
file_b64 string optional
generated_by object optional
- npm string optional maxLength: 128
- supervisor string optional maxLength: 128
workbook_handle string optional minLength: 1 · maxLength: 128

Raw JSON Schema

{
  "properties": {
    "checks": {
      "items": {
        "properties": {
          "detail": {
            "maxLength": 1024,
            "type": "string"
          },
          "id": {
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "name": {
            "maxLength": 256,
            "minLength": 1,
            "type": "string"
          },
          "status": {
            "enum": [
              "passed",
              "failed",
              "skipped"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "status"
        ],
        "type": "object"
      },
      "maxItems": 200,
      "minItems": 0,
      "type": "array"
    },
    "exclude_sheets": {
      "items": {
        "maxLength": 128,
        "type": "string"
      },
      "maxItems": 100,
      "type": "array"
    },
    "file_b64": {
      "type": "string"
    },
    "generated_by": {
      "properties": {
        "npm": {
          "maxLength": 128,
          "type": "string"
        },
        "supervisor": {
          "maxLength": 128,
          "type": "string"
        }
      },
      "type": "object"
    },
    "workbook_handle": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "checks"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_styles`

POST /api/v1/tools/xlsx_styles — Surface cell formatting (number formats, fonts, fills, alignment) — what a cell LOOKS like, not just its raw value.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- detailed boolean optional
- limit integer optional minimum: 1 · maximum: 1000
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "detailed": {
          "type": "boolean"
        },
        "limit": {
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_tables`

POST /api/v1/tools/xlsx_tables — List every Excel ListObject ("Format as Table") in a workbook — name, sheet, range, header/totals flags, columns.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- include_columns boolean optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "include_columns": {
          "type": "boolean"
        },
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_topology`

POST /api/v1/tools/xlsx_topology — One-call workbook orientation — sheets, formulas, named ranges, tables, validations, hyperlinks, merges, and feature flags in one shot.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_validate`

POST /api/v1/tools/xlsx_validate — Cross-engine consistency check — parse the same workbook with two independent renderers and report cell-level divergences.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_value_counts`

POST /api/v1/tools/xlsx_value_counts — Per-column value counts — each unique value, sorted by frequency, with percentage.

Auth: Authorization: Bearer <api_key> (required)

Request body required

column string required
file_b64 string required
options object optional
- header_row integer optional minimum: 0
- include_nulls boolean optional
- sheet string optional
- top_n integer optional minimum: 1 · maximum: 1000

Raw JSON Schema

{
  "properties": {
    "column": {
      "type": "string"
    },
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "header_row": {
          "minimum": 0,
          "type": "integer"
        },
        "include_nulls": {
          "type": "boolean"
        },
        "sheet": {
          "type": "string"
        },
        "top_n": {
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "column",
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_vault_cure`

POST /api/v1/tools/xlsx_vault_cure — Clean hidden or risky content out of a spreadsheet.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required maxLength: 279685803
mode string optional enum: as_copy, in_place
selection object optional additionalProperties: false
- finding_actions object optional additionalProperties: object
- finding_ids array optional items: string
- risk_tiers array optional items: string
simulate boolean optional

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "file_b64": {
      "maxLength": 279685803,
      "type": "string"
    },
    "mode": {
      "enum": [
        "as_copy",
        "in_place"
      ],
      "type": "string"
    },
    "selection": {
      "additionalProperties": false,
      "properties": {
        "finding_actions": {
          "additionalProperties": {
            "properties": {
              "sub_action": {
                "type": "string"
              }
            },
            "required": [
              "sub_action"
            ],
            "type": "object"
          },
          "type": "object"
        },
        "finding_ids": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "risk_tiers": {
          "items": {
            "enum": [
              "high",
              "medium",
              "low"
            ],
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "simulate": {
      "type": "boolean"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_vault_scan`

POST /api/v1/tools/xlsx_vault_scan — Scan a spreadsheet for hidden or risky content (macros, external links, embedded objects).

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required maxLength: 279685803

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "file_b64": {
      "maxLength": 279685803,
      "type": "string"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_verify_receipt`

POST /api/v1/tools/xlsx_verify_receipt — Verify a workbook's embedded AI-generation receipt — signature validity, content-hash match, and the full declared claims.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string optional
workbook_handle string optional minLength: 1 · maxLength: 128

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "workbook_handle": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_verify_stamp`

POST /api/v1/tools/xlsx_verify_stamp — Verify a workbook's embedded integrity stamp — signature validity, content-hash match, and the recorded check results.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string optional
workbook_handle string optional minLength: 1 · maxLength: 128

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "workbook_handle": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_workbook_views`

POST /api/v1/tools/xlsx_workbook_views — Surface the UI state of a workbook — per-sheet visibility/zoom/frozen-panes/tab color, and which sheet is active on open.

Auth: Authorization: Bearer <api_key> (required)

Request body required

file_b64 string required
options object optional
- sheet string optional

Raw JSON Schema

{
  "properties": {
    "file_b64": {
      "type": "string"
    },
    "options": {
      "properties": {
        "sheet": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "file_b64"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.

`xlsx_write`

POST /api/v1/tools/xlsx_write — Create or update a spreadsheet from a structured spec ({sheets: [{name, cells: [{address, value | formula}]}]}) — server-validated before writing.

Auth: Authorization: Bearer <api_key> (required)

Request body required

base_file_b64 string optional
cache_handle string optional minLength: 1 · maxLength: 128 · pattern: ^[^\u0000-\u001f\u007f\s:*?\[\]]+$
spec object required

Raw JSON Schema

{
  "properties": {
    "base_file_b64": {
      "type": "string"
    },
    "cache_handle": {
      "maxLength": 128,
      "minLength": 1,
      "pattern": "^[^\\u0000-\\u001f\\u007f\\s:*?\\[\\]]+$",
      "type": "string"
    },
    "spec": {
      "type": "object"
    }
  },
  "required": [
    "spec"
  ],
  "type": "object"
}

Responses

200 — Tool result (base64-in / base64-out; stateless).
400 — Bad request. `error.code` is one of: `bad_request` (malformed or oversized JSON body, invalid base64, or a missing/invalid field), `hardening_rejected` (the upload failed an ingest safety guard — e.g. an encrypted workbook, a non-OOXML zip, a truncated file, or a legacy .xls on a route that does not accept it), `unparseable_input` (no readable CSV header row), or `malformed_csv` (a structurally broken CSV — an unclosed or mid-field quote). A sheet- or column-not-found request also carries `available_sheets` / `available_columns`.
401 — Missing or invalid API key. `error.code`: `unauthorized`.
402 — Payment required. `error.code`: `tier_upgrade_required`. A forward-compatible response for a capability gated to a paid subscription; it is driven by the account/consent surface (POST /api/v1/consent), not by the stateless tool inputs. No action is needed for standard tool calls on the free tier.
413 — Payload too large. `error.code`: `file_too_large` (the input exceeds the per-format upload ceiling, or expands past the content-processing ceiling once parsed) or `write_output_too_large` (the requested output would exceed the format write cap). These are capacity ceilings — identical for every caller, never a paywall lever.
429 — Free-tier file allowance reached for the current period. `error.code`: `rate_limit_exceeded`.
500 — Internal server error — an unexpected fault on our side. `error.code`: `internal_error`.
503 — Service temporarily unavailable — retryable; a `Retry-After` header is sent when known. `error.code` is one of: `service_unavailable` (a backing service is down, or parse capacity is momentarily saturated), `rate_limit_backend_unavailable`, or `cache_backend_unavailable`.