Workspace Spreadsheet — API and MCP reference

The Workspace Spreadsheet is fully accessible via the REST API and MCP. This article covers the endpoints, MCP tools, required scopes, filter syntax, and how to work with saved views, per-view sort, and dropdown option colours programmatically.

For an overview of what the Workspace Spreadsheet does and how to use it in the browser, see https://trustpager.com/help-center/export-crm-data.

API scopes

Your API key needs the following scopes depending on what you are doing:

• exports:read — list templates, get a template, preview rows, list/get views
• exports:write — create and update templates and views, run exports
• exports:delete — delete templates and views

Manage scopes at https://app.trustpager.com/settings/api.

REST endpoints — templates

• GET /api/v1/exports/templates — list all templates
• GET /api/v1/exports/templates/:id — get a single template (includes views)
• POST /api/v1/exports/templates — create a template
• PATCH /api/v1/exports/templates/:id — update a template
• DELETE /api/v1/exports/templates/:id — delete a template
• POST /api/v1/exports/templates/:id/preview — preview the first 10 rows (returns JSON)
• POST /api/v1/exports/templates/:id/run — run the full export and download the file (XLSX or CSV)

REST endpoints — views

Each template has one or more saved views. A view holds its own filter set and its own sort; the column configuration belongs to the template.

• GET /api/v1/exports/templates/:id/views — list views for a template
• GET /api/v1/exports/templates/:id/views/:view_id — get a single view
• POST /api/v1/exports/templates/:id/views — create a view
• PATCH /api/v1/exports/templates/:id/views/:view_id — update a view (name, filters, or sort)
• DELETE /api/v1/exports/templates/:id/views/:view_id — delete a view

When you run or preview a template, pass view_id in the request body to apply a specific view’s filters and sort. If omitted, the most recently updated view is used.

MCP tools

All template and view operations are available as MCP tools:

• list_export_templates
• get_export_template
• create_spreadsheet_template
• update_spreadsheet_template
• delete_export_template
• preview_export_template
• run_export_template

View CRUD is handled via the REST API endpoints above. MCP tool coverage for views will expand in a future release.

Dropdown option colours

When creating or updating a template via create_spreadsheet_template or update_spreadsheet_template, each option in a dropdown column accepts a color field alongside its value. The colour renders as a chip in the grid cell so status values stand out at a glance.

{
  "columns": [
    {
      "label": "Status",
      "type": "dropdown",
      "options": [
        { "value": "Todo",        "color": "slate" },
        { "value": "In Progress", "color": "amber" },
        { "value": "Completed",   "color": "green" },
        { "value": "Blocked",     "color": "red" }
      ]
    }
  ]
}

The color field is optional — options without a colour render as plain text chips. Supported palette keys: slate, red, orange, amber, yellow, green, teal, blue, indigo, purple, pink. The MCP tool inputSchema enumerates these values so AI agents can introspect them without guessing. The same palette is used in the browser UI — clicking a colour swatch on any dropdown option in the Column settings panel picks from the same 11 keys.

Per-view sort

Each saved view stores its own sort configuration, independent of other views on the same template. Sort is applied to both preview and export output for that view. Set it via PATCH /api/v1/exports/templates/:id/views/:view_id with a sort array in the body:

{
  "sort": [
    { "column_id": "<uuid>", "direction": "asc" },
    { "column_id": "<uuid>", "direction": "desc" }
  ]
}

Each entry references column_id (the UUID of the column on the template, not the column header string) and a direction of “asc” or “desc”. Entries are applied in order — the second breaks ties on the first. The field is stored on crm_export_template_views.sort as a JSONB array. When no sort is configured, the view falls back to created_at DESC. Column IDs are returned in the GET /api/v1/exports/templates/:id response.

Filter syntax

Filters are applied at the view level. Each filter is an object with a field, operator, and value.

Supported operators:

• eq — equals
• neq — not equals
• in — value is in list
• between — value is between two bounds (date range or numeric)
• contains — string contains substring
• is_null — field has no value
• is_not_null — field has a value
• gt — greater than
• lt — less than

The field value is a dot-path. Standard fields use the entity field name directly (e.g. stage, value, lead_source, tags). Custom fields use metadata.<custom_field_id>.

Example filter object:

{
  "field": "metadata.cf_loan_type",
  "operator": "eq",
  "value": "variable"
}

Date fields accept ISO 8601 strings. The between operator takes an array of two values: "value": ["2024-01-01", "2024-12-31"].

Working with saved views and the ?view= URL param

Every saved view has a stable id. When you construct a URL to a Workspace Spreadsheet in the browser, you can deep-link to a specific view:

https://app.trustpager.com/tools/spreadsheets/<template-id>?view=<view-id>

If you open a template URL with no ?view param, the browser automatically redirects (replace-nav, no history entry) to the most recently updated view. Bookmarks and shared links that include ?view=<view-id> will always land on the correct view regardless of which view was last edited.

To get the template ID and view IDs for a URL you want to construct, call GET /api/v1/exports/templates and inspect the views array on each template.

Large datasets

Exports return your complete result set. When you run a template (POST /api/v1/exports/templates/:id/run) or use the legacy GET /api/v1/crm/export, the API pages through the entire dataset server-side, so there is no 1,000-row ceiling: a workspace with thousands of opportunities or contacts exports in full in a single call. Filtering by a pipeline or stage works the same way no matter how many records it holds. (The preview endpoint still returns just the first 10 rows by design.)

Legacy note — GET /api/v1/crm/export

The older GET /api/v1/crm/export?type=... endpoint still works for existing integrations during this release cycle. New integrations should use POST /api/v1/exports/templates/:id/run, which supports saved views, per-view sort, all filter operators, and XLSX output.