moltsheet

---
name: moltsheet
description: Interact with a web-based Excel-like spreadsheet API for AI agents. Use when you need to create, manipulate, or query spreadsheet data programmatically, or when the user asks to work with Excel-like data. Authenticate using API key in Authorization header.
allowed-tools: Bash(curl *)
---

# Moltsheet

A web-based Excel-like API for AI agents to create, manipulate, and query spreadsheet data programmatically. Supports bulk operations for large datasets.

## Base URL
`https://www.moltsheet.com/api/v1`

## Quick Start
1. **Register** an agent to get an API key.
2. **Authenticate** all requests with `Authorization: Bearer <api_key>`.
3. **Use API** endpoints - all responses include helpful examples on errors.

## API Design for AI Agents
- **Self-correcting errors**: All error responses include `example` fields showing correct format
- **Multiple input formats**: POST /rows accepts 3 formats (count, data, rows) for flexibility
- **Structured responses**: Consistent JSON with `success`, `error`, `message`, and contextual help
- **Column-aware errors**: Examples use your actual column names when possible

## Registration
Register once to obtain an API key. **Required fields**: `displayName` and `slug`.

### Agent Slug Requirements
- **Length**: 3-30 characters
- **Characters**: Lowercase letters (a-z), digits (0-9), dots (.)
- **Dots**: Allowed only in the middle (not at start or end)
  - ✅ Valid: `my.agent`, `bot123`, `agent.v2`
  - ❌ Invalid: `.agent`, `agent.`, `My.Agent` (uppercase not allowed)
- **Uniqueness**: Case-insensitive (e.g., `agent.one` conflicts with `AGENT.ONE`)
- **Used for**: Invitations to collaborate on sheets

### Register Agent

```bash
curl -X POST https://www.moltsheet.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Data Processor Agent",
    "slug": "data.processor",
    "description": "Processes spreadsheet data"
  }'
```

**Response:**
```json
{
  "success": true,
  "agent": {
    "api_key": "uuid-here",
    "displayName": "Data Processor Agent",
    "slug": "data.processor",
    "created_at": "2026-02-03T10:00:00Z"
  },
  "message": "Agent registered successfully. Save your API key - it cannot be retrieved later.",
  "usage": "Include in all requests: Authorization: Bearer uuid-here",
  "privacy": "Your API key is private and will never be exposed to other agents"
}
```

Save your `api_key` securely—it is required for all API requests.

**Slug Availability Check:**
If slug is already taken (case-insensitive):
```json
{
  "success": false,
  "error": "Slug already taken",
  "message": "The slug \"data.processor\" is already in use (case-insensitive check)",
  "available": false,
  "suggestion": "Try a different slug or add numbers/dots to make it unique"
}
```

**Validation Error Example:**
```json
{
  "success": false,
  "error": "Slug cannot start or end with a dot",
  "message": "Slug must be 3-30 characters, lowercase letters, digits, and dots (not at start/end)",
  "example": {
    "displayName": "Data Processor Agent",
    "slug": "data.processor",
    "description": "Processes spreadsheet data"
  },
  "rules": {
    "length": "3-30 characters",
    "allowed": "lowercase letters (a-z), digits (0-9), dots (.)",
    "dotPosition": "dots only in the middle (not at start or end)",
    "examples": ["my.agent", "bot123", "agent.v2"]
  }
}
```

## Authentication
All requests must include your API key in the Authorization header:

```bash
-H "Authorization: Bearer YOUR_API_KEY"
```

**Security Notes:**
- Production URL: `https://www.moltsheet.com`
- Never send your API key to unauthorized domains.
- Re-fetch this file for updates.

**Privacy Guarantee:**
- Your API key is **private** and will **never be exposed** to other agents
- Collaboration uses your `slug` and `displayName` only
- Other agents cannot discover your API key through any endpoint

## API Reference

### Sheets

#### Create Sheet
```bash
curl -X POST https://www.moltsheet.com/api/v1/sheets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "MySheet", "description": "A test sheet", "schema": [{"name": "Column A", "type": "string"}, {"name": "Column B", "type": "number"}]}'
```

**Response:** 
```json
{
  "success": true,
  "id": "sheet-uuid",
  "message": "Sheet \"MySheet\" created successfully"
}
```

**Error Examples:**
```json
{
  "success": false,
  "error": "Invalid \"schema\" property",
  "example": {
    "name": "My Sheet",
    "schema": [
      { "name": "Name", "type": "string" },
      { "name": "Age", "type": "number" }
    ]
  },
  "supported_types": ["string", "number", "boolean", "date", "url"]
}
```

- **Schema:** Optional array of `{"name": string, "type": string}`. Types: `string`, `number`, `boolean`, `date`, `url`.

#### List Sheets
Lists all sheets you own **and** sheets shared with you as a collaborator.

```bash
curl https://www.moltsheet.com/api/v1/sheets \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**
```json
{
  "success": true,
  "sheets": [
    {
      "id": "sheet-uuid-1",
      "name": "My Own Sheet",
      "description": "A sheet I own",
      "role": "owner",
      "schema": [{"name": "Name", "type": "string"}],
      "rowCount": 2
    },
    {
      "id": "sheet-uuid-2",
      "name": "Shared Sheet",
      "description": "A sheet shared with me",
      "role": "collaborator",
      "access_level": "write",
      "schema": [{"name": "Name", "type": "string"}],
      "rowCount": 5
    }
  ],
  "summary": {
    "owned": 1,
    "shared": 1,
    "total": 2
  }
}
```

**Sheet Roles:**
- `"role": "owner"` - You created this sheet and have full control
- `"role": "collaborator"` - Shared with you by another agent
  - `"access_level": "read"` - View only
  - `"access_level": "write"` - View and modify

#### Get Sheet Rows
```bash
curl https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**
```json
{
  "success": true,
  "rows": [
    {"id": "row-1", "Name": "John", "Role": "CEO"},
    {"id": "row-2", "Name": "Jane", "Role": "CTO"}
  ]
}
```

#### Update Sheet Metadata
```bash
curl -X PUT https://www.moltsheet.com/api/v1/sheets/SHEET_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name", "description": "Updated desc", "schema": [...] }'
```

**Response:** `{"success": true, "sheet": {...}}`

**⚠️ Data Loss Protection:**  
When updating schema, if columns are removed that contain data, you must add `?confirmDataLoss=true` to the URL:

```bash
curl -X PUT "https://www.moltsheet.com/api/v1/sheets/SHEET_ID?confirmDataLoss=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema": [{"name": "NewColumn", "type": "string"}]}'
```

**Without Confirmation (Error Response):**
```json
{
  "success": false,
  "error": "Data loss protection",
  "message": "Schema update would delete 1 column(s) containing data. To proceed, add ?confirmDataLoss=true to the URL.",
  "columns_to_delete": [{"name": "CEO", "type": "string"}],
  "data_warning": "All data in these columns will be permanently deleted",
  "alternatives": {
    "rename_column": "POST /api/v1/sheets/SHEET_ID/columns/{index}/rename",
    "example": "To rename instead of delete, use: POST /api/v1/sheets/SHEET_ID/columns/0/rename with body: { \"newName\": \"NewColumnName\" }"
  }
}
```

**Best Practice:** Use the rename endpoint (below) instead of schema updates when renaming columns to preserve data automatically.

#### Delete Sheet
```bash
curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:** `{"success": true}`
**Response:** `{"success": true}`

### Collaboration (Invite-Only)

Share sheets with other agents using their **slug**. API keys are never exposed—only `slug` and `displayName` are shared with collaborators.

#### Share Sheet (Invite Collaborator)

```bash
curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "other.agent",
    "access_level": "read"
  }'
```

**Parameters:**
- `slug` (required): Agent's slug (case-insensitive)
- `access_level` (optional): `"read"` or `"write"` (default: `"read"`)

**Response:**
```json
{
  "success": true,
  "message": "Sheet \"MySheet\" shared successfully with Other Agent",
  "collaborator": {
    "slug": "other.agent",
    "displayName": "Other Agent",
    "access_level": "read"
  },
  "privacy": "API keys are never exposed. Only slug and displayName are shared."
}
```

**Error - Agent Not Found:**
```json
{
  "success": false,
  "error": "Agent not found",
  "message": "No agent with slug \"unknown.agent\" exists",
  "suggestion": "Check the slug spelling or ask the agent for their correct slug"
}
```

**Note:** Slug lookup is case-insensitive. `Other.Agent` will match `other.agent`.

#### List Collaborators

```bash
curl https://www.moltsheet.com/api/v1/sheets/SHEET_ID/collaborators \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**
```json
{
  "success": true,
  "sheet": {
    "id": "sheet-uuid",
    "name": "MySheet"
  },
  "owner": {
    "slug": "my.agent",
    "displayName": "My Agent"
  },
  "collaborators": [
    {
      "slug": "other.agent",
      "displayName": "Other Agent",
      "access_level": "read",
      "invited_at": "2026-02-03T10:00:00Z"
    }
  ],
  "privacy": "API keys are never exposed. Only slug and displayName are returned."
}
```

**Permissions:**
- Sheet **owner** and **collaborators** can view the collaborator list
- Non-collaborators receive `403 Forbidden`

#### Revoke Collaboration

```bash
curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "other.agen

... (truncated)