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
| Plan | Limit |
|---|---|
| Professional | 100 requests/minute |
| Enterprise | 1,000 requests/minute |
Endpoints
An API key belongs to your organization and can reach every workspace in it.
Workspaces
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/workspaces | List your organization's workspaces, each with its geosheetCount |
GeoSheets
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/geosheets | List 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/:id | Get GeoSheet info, including its sheets |
POST | /v1/geosheets | Create a GeoSheet. Body: { "workspaceId": "...", "name": "..." } |
DELETE | /v1/geosheets/:id | Move a GeoSheet to the trash |
GET | /v1/geosheets/:id/sheets | List sheets |
GET | /v1/geosheets/:id/charts | List charts (optional sheetId) |
Cells
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/geosheets/:id/cells | Read cells. Query params: sheet (name), range (A1 notation, up to 1,000 rows × 26 columns) |
PUT | /v1/geosheets/:id/cells | Write 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
- In the dashboard sidebar, go to Admin > API Keys
- Click Create key
- Name the key and select scopes:
geosheets:read— list and read GeoSheet metadatageosheets:write— create and modify GeoSheetscells:read— read cell valuescells:write— write cell values
- Copy the key immediately — it's only shown once
- 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
| Tool | Description |
|---|---|
list_workspaces | List your organization's workspaces, with how many GeoSheets each holds |
list_geosheets | List GeoSheets, most recent first, across your organization or in one workspace; query finds them by name, offset pages past the first 50 |
create_geosheet | Create a new, empty GeoSheet in a workspace and return its link; fill it with set_cells |
get_geosheet_info | Get metadata for a GeoSheet, including its sheets |
list_sheets | List sheets within a GeoSheet |
get_cells | Read cell values from a range |
set_cells | Write values to cells |
search_cells | Search for values across sheets |
list_charts | List the charts and maps in a GeoSheet, optionally on one sheet |
list_functions | Find the spreadsheet functions you can use in formulas, by words (query, e.g. "driving time") or category |
get_function | Get 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.
Updated 27 days ago