SpreadAPI Documentation

Overview

SpreadAPI turns your Excel spreadsheets into secure REST APIs. Upload your Excel file, and instantly get an API endpoint that executes your formulas and returns results. Perfect for AI integration, web apps, and automation.

Quick Start

Get your Excel spreadsheet running as an API in 3 simple steps.

// JavaScript example
const response = await fetch('https://spreadapi.io/api/v1/services/my-calculator/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inputs: {
      quantity: 100,
      price: 50
    }
  })
});

const result = await response.json();
console.log(result.outputs); // Your Excel calculation results

Authentication

All API requests require authentication using your API key.

Getting Your API Key

1. Log in to your SpreadAPI dashboard
2. Navigate to API Keys section
3. Create a new API key
4. Copy and store it securely

Using Your API Key

Include your API key in the Authorization header of all requests:

Authorization: Bearer YOUR_API_KEY

How It Works

SpreadAPI uses an Excel-compatible calculation engine to execute your spreadsheet formulas server-side. Your Excel logic stays intact and works exactly as designed.

The Process

1. Upload: You upload your Excel file (.xlsx, .xls)
2. Configure: You manually select which cells are inputs and outputs
3. Publish: You publish the service to make it available
4. API Creation: A unique endpoint is created for your spreadsheet
5. Execution: When called, the engine runs your formulas
6. Results: Calculated values are returned as JSON

Services

Each Excel file you upload becomes a "service" - a standalone API endpoint that executes your spreadsheet calculations.

Service Properties

• Name: Unique identifier for your service (e.g., "pricing-calculator")
• Endpoint: REST API endpoint for executing calculations
• Inputs: Cell references that accept input values
• Outputs: Cell references that return calculated results

Managing Services

You can manage your services through the dashboard:

• View all services and their usage
• Update Excel files
• Configure input/output mappings
• Set permissions for AI access
• Monitor API calls and performance

Permissions

Control exactly what AI assistants and applications can do with your Excel data.

Permission Types

Create Your Excel Service

Upload an existing Excel file or create a new one directly in the SpreadAPI app, then define which cells or areas should be inputs and outputs.

Execute Calculations

Execute your Excel calculations by calling your service endpoint.

Execute Service

GET/POST /api/v1/services/{'service-id}/execute

GET Request Example

GET /api/v1/services/pricing-calculator/execute?quantity=100&discount=0.15&customer_type=enterprise

POST Request Body

{
  "inputs": {
    "quantity": 100,
    "discount": 0.15,
    "customer_type": "enterprise"
  }
}

Response

{
  "serviceId": "pricing-calculator",
  "inputs": {
    "quantity": 100,
    "discount": 0.15,
    "customer_type": "enterprise"
  },
  "outputs": [
    {
      "type": "output",
      "name": "total",
      "value": 8500
    },
    {
      "type": "output",
      "name": "unit_price",
      "value": 85
    },
    {
      "type": "output",
      "name": "savings",
      "value": 1500
    }
  ],
  "metadata": {
    "executionTime": 23,
    "totalTime": 45,
    "timestamp": "2024-01-20T10:30:00Z",
    "version": "v1"
  }
}

Notes

• Input keys must match your configured input cells
• Outputs will include all configured output cells
• Results are cached for better performance
• Excel errors (like #DIV/0!) are returned in the response

Error Handling

SpreadAPI returns detailed error information to help you debug issues.

API Errors

// 400 Bad Request
{
  "error": "Invalid request",
  "message": "Request body must contain "inputs" object",
  "serviceId": "pricing-calculator",
  "inputs": null
}

// 404 Not Found
{
  "error": "Not found",
  "message": "Service not found or not published"
}

// 500 Internal Server Error
{
  "error": "Internal server error",
  "message": "Error details here"
}

Excel Calculation Errors

When Excel formulas produce errors, they're returned in the response:

{
  "outputs": {
    "result": "#DIV/0!",
    "status": "#VALUE!"
  },
  "errors": {
    "result": "Division by zero in cell E10",
    "status": "Invalid value type in cell C5"
  }
}

MCP Protocol

The Model Context Protocol (MCP) enables AI assistants like Claude to interact with your Excel spreadsheets securely.

What is MCP?

MCP is a protocol that allows AI assistants to discover and use external tools. SpreadAPI implements MCP to let AI assistants execute your Excel calculations without seeing your formulas.

How It Works

1. Discovery: AI assistant discovers your available Excel services
2. Permissions: AI sees only what you've allowed (values, not formulas)
3. Execution: AI sends inputs, receives calculated outputs
4. Security: Your Excel logic stays on SpreadAPI servers

Install MCP Server

npm install -g spreadapi-mcp

Claude Setup

Configure Claude Desktop to use your SpreadAPI services.

Step 1: Locate Config File

Find your Claude Desktop configuration file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Step 2: Add SpreadAPI

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "spreadapi": {
      "command": "npx",
      "args": ["spreadapi-mcp"],
      "env": {
        "SPREADAPI_TOKEN": "YOUR_API_KEY",
        "SPREADAPI_URL": "https://spreadapi.io/api/mcp/v1"
      }
    }
  }
}

Step 3: Restart Claude

Restart Claude Desktop to load the configuration.

Usage Example

Once configured, you can ask Claude to use your Excel services:

User: "Calculate pricing for 500 units with enterprise discount"

Claude: "I'll calculate that using your pricing spreadsheet..."
[Executes pricing-calculator with quantity=500, customer_type=enterprise]

Claude: "Based on your Excel calculations:
- Unit price: $45
- Total: $22,500
- Savings: $2,500"

Limitations

SpreadAPI supports most Excel features, but there are some current limitations.

What IS Supported

• ✅ All standard Excel functions
• ✅ Array formulas and dynamic arrays
• ✅ Pivot tables (calculated values)
• ✅ Named ranges
• ✅ Multiple worksheets
• ✅ Data validation
• ✅ Conditional formatting (as metadata)

Pricing

Simple, transparent pricing that scales with your usage.

Need more? Contact us for Enterprise pricing.

Support

Getting Help

Common Issues