API & Integrations

Public REST API, MCP server, and API key management

GeoSheet provides a public REST API and an MCP server for integrating with external tools and AI assistants.

Public REST API

The REST API allows you to read and write GeoSheet data programmatically.

Requirements

  • Professional plan or higher
  • An API key (created under Admin > API Keys in the dashboard sidebar; organization owners and admins only)

Authentication

All API requests require a Bearer token:

Authorization: Bearer gs_live_abc123...

Base URL

https://geosheet.app/v1

Rate Limits

PlanLimit
Professional100 requests/minute
Enterprise1,000 requests/minute

Endpoints

An API key belongs to your organization and can reach every workspace in it.

Workspaces

MethodEndpointDescription
GET/v1/workspacesList your organization's workspaces, each with its geosheetCount

GeoSheets

MethodEndpointDescription
GET/v1/geosheetsList GeoSheets, most recently updated first. Query params: workspaceId (optional; without it, every workspace in your organization, and each item includes workspaceName), q (name contains, case-insensitive), limit (default 50), offset
GET/v1/geosheets/:idGet GeoSheet info, including its sheets
POST/v1/geosheetsCreate a GeoSheet. Body: { "workspaceId": "...", "name": "..." }
DELETE/v1/geosheets/:idMove a GeoSheet to the trash
GET/v1/geosheets/:id/sheetsList sheets
GET/v1/geosheets/:id/chartsList charts (optional sheetId)

Cells

MethodEndpointDescription
GET/v1/geosheets/:id/cellsRead cells. Query params: sheet (name), range (A1 notation, up to 1,000 rows × 26 columns)
PUT/v1/geosheets/:id/cellsWrite up to 1,000 cells. Body: { "sheet": "Sheet1", "cells": [{ "cell": "A1", "value": "Paris" }] }; null clears a cell

Example: find a GeoSheet by name

curl -H "Authorization: Bearer gs_live_..." \
  "https://geosheet.app/v1/geosheets?q=stores"

API Key Management

  1. In the dashboard sidebar, go to Admin > API Keys
  2. Click Create key
  3. Name the key and select scopes:
    • geosheets:read — list and read GeoSheet metadata
    • geosheets:write — create and modify GeoSheets
    • cells:read — read cell values
    • cells:write — write cell values
  4. Copy the key immediately — it's only shown once
  5. Keys can be revoked at any time

Response Format

Responses wrap their payload in data:

{
  "data": { ... }
}

List endpoints that paginate add the total and the page window:

{
  "data": [...],
  "total": 120,
  "limit": 50,
  "offset": 0
}

Errors return the HTTP status with:

{
  "error": "Not Found",
  "message": "GeoSheet not found",
  "statusCode": 404
}

Validation errors (400) may also include details.


MCP Server

GeoSheet provides an MCP (Model Context Protocol) server so AI clients like Claude Desktop, Cursor, and other MCP-compatible tools can interact with your spreadsheets.

Hosted MCP (Recommended)

No installation needed. The server is at https://geosheet.app/mcp (Streamable HTTP) and authenticates with your API key as a Bearer token. Requires a Professional plan API key.

Claude Code

claude mcp add --transport http geosheet https://geosheet.app/mcp \
  --header "Authorization: Bearer gs_live_..."

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "geosheet": {
      "url": "https://geosheet.app/mcp",
      "headers": {
        "Authorization": "Bearer gs_live_..."
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json, via mcp-remote, since Claude Desktop can't send a custom header to a remote server)

{
  "mcpServers": {
    "geosheet": {
      "command": "npx",
      "args": ["mcp-remote", "https://geosheet.app/mcp", "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer gs_live_..." }
    }
  }
}

OpenAI Codex (~/.codex/config.toml, with the key in the GEOSHEET_API_KEY environment variable)

[mcp_servers.geosheet]
url = "https://geosheet.app/mcp"
bearer_token_env_var = "GEOSHEET_API_KEY"

Other MCP clients: use the URL above and send the header Authorization: Bearer gs_live_....

Available MCP Tools

ToolDescription
list_workspacesList your organization's workspaces, with how many GeoSheets each holds
list_geosheetsList GeoSheets, most recent first, across your organization or in one workspace; query finds them by name, offset pages past the first 50
create_geosheetCreate a new, empty GeoSheet in a workspace and return its link; fill it with set_cells
get_geosheet_infoGet metadata for a GeoSheet, including its sheets
list_sheetsList sheets within a GeoSheet
get_cellsRead cell values from a range
set_cellsWrite values to cells
search_cellsSearch for values across sheets
list_chartsList the charts and maps in a GeoSheet, optionally on one sheet
list_functionsFind the spreadsheet functions you can use in formulas, by words (query, e.g. "driving time") or category
get_functionGet one spreadsheet function's syntax, arguments, return type, examples and notes

Anywhere a tool asks for a GeoSheet ID, you can paste the GeoSheet's link instead (for example https://geosheet.app/dashboard/sheet/...), so you can tell your assistant "summarize this sheet" and paste the URL.

The tools need these API key scopes: geosheets:read for listing, metadata and charts, geosheets:write to create GeoSheets, cells:read to read or search cells, cells:write to write them. list_functions and get_function need no scope.

Spreadsheet functions such as DRIVE_TIME are not MCP tools: your assistant writes them into cells as formulas (for example =DRIVE_TIME(A2, B2)) with set_cells, and the GeoSheet keeps the results up to date.

Try it

Once connected, ask your assistant things like:

  • "Which GeoSheet workspaces do I have?"
  • "Find my GeoSheet about Paris stores and show me the first 20 rows."
  • "In https://geosheet.app/dashboard/sheet/..., add a column with each store's city."
  • "Create a GeoSheet called Paris stores in my Retail workspace and add these addresses."

Use Cases

  • Claude Desktop: Ask Claude to read your GeoSheet data, analyze it, and write results back
  • Cursor/IDE: Reference spreadsheet data while coding
  • Custom AI agents: Build agents that interact with GeoSheet data
  • Automation: Use MCP-compatible tools to automate spreadsheet workflows

Webhooks (Coming Soon)

Webhook support for real-time notifications on spreadsheet events is planned for a future release.


Did this page help you?