← Back to PDF & Documents
PDF & Documents by @youssefbm2008

moltsheet

Interact with a web-based Excel-like spreadsheet API for AI agents

0
Source Code

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

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:

{
  "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):

{
  "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:

{
  "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:

-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

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: 

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

Error Examples:

{
  "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.

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

Response:

{
  "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

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

Response:

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

Update Sheet Metadata

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:

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):

{
  "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

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)

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:

{
  "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:

{
  "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

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

Response:

{
  "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

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.agent"}'

Response:

{
  "success": true,
  "message": "Collaboration with Other Agent revoked successfully"
}

Access Levels:

  • read: View sheet data only
  • write: View and modify sheet data (rows, cells, columns)

Privacy Guarantee:

  • API keys are never exposed in any collaboration endpoint
  • Only slug and displayName are shared between agents
  • Invitations use slugs, not API keys

Data Operations

Update Cells

curl -X PUT https://www.moltsheet.com/api/v1/sheets/SHEET_ID/cells \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {"rowId": "row-123", "column": "Full Name", "value": "Updated Name"}
    ]
  }'

Response: {"success": true}

Add Empty Row(s)

Note: This endpoint creates empty rows. To add rows with data, use the Bulk Import endpoint below.

# Add 1 empty row (default)
curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \
  -H "Authorization: Bearer YOUR_API_KEY"

# Add multiple empty rows
curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 10}'

Response: {"success": true, "rowIds": [...], "message": "Created 10 empty row(s)"}

Add Single Row with Data

curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"Name": "John", "Role": "CEO"}}'

Response: {"success": true, "rowId": "row-uuid", "message": "Created 1 row with data"}

Add Multiple Rows with Data

curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows": [{"Name": "John", "Role": "CEO"}, {"Name": "Jane", "Role": "CTO"}]}'

Response: {"success": true, "rowIds": [...], "message": "Created 2 row(s) with data"}

Unified Endpoint: POST /rows now accepts three formats:

  • {"count": N} - Create N empty rows
  • {"data": {...}} - Create 1 row with data
  • {"rows": [...]} - Create multiple rows with data

Error Example:

{
  "success": false,
  "error": "Invalid request format",
  "message": "Use one of the supported formats",
  "formats": {
    "empty_rows": { "count": 10 },
    "single_row": { "data": { "Country": "USA", "Capital": "Washington" } },
    "multiple_rows": { "rows": [{ "Country": "USA" }, { "Country": "Canada" }] }
  }
}

Add Column

curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Column", "type": "string"}'

Response: {"success": true}

Rename Column

Preserves all data - use this instead of schema updates when renaming columns.

curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns/COL_INDEX/rename \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newName": "Contact"}'

Response:

{
  "success": true,
  "message": "Column \"CEO\" renamed to \"Contact\"",
  "oldName": "CEO",
  "newName": "Contact"
}

Error Examples:

{
  "success": false,
  "error": "Duplicate column name",
  "message": "A column named \"Contact\" already exists in this sheet",
  "existing_columns": ["Company", "Contact", "Industry"]
}
  • COL_INDEX: Zero-based column position (0, 1, 2, ...)
  • All cell data preserved when renaming
  • No data loss - cells remain linked to same column
  • Prevents duplicate column names

Delete Row

curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows/ROW_INDEX \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: {"success": true}

Delete Column

curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns/COL_INDEX \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: {"success": true}

Bulk Operations

Deprecated: POST /import still works but POST /rows now handles all row operations.

For compatibility, /import endpoint remains available:

curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {"Name": "John", "Role": "CEO"},
      {"Name": "Jane", "Role": "CTO"}
    ]
  }'

Response: {"success": true, "rowIds": ["row-...", ...]}

Error Example with Column Names:

{
  "success": false,
  "error": "Missing \"rows\" property in request body",
  "message": "Expected format: {\"rows\": [{...}, {...}]}",
  "example": { "rows": [{ "country": "country_value", "capital": "capital_value" }] },
  "available_columns": ["Country", "Capital", "Population"]
}
  • Maximum 1000 rows per request
  • Column names must match sheet schema
  • Errors show your actual column names in examples

Bulk Operations (Others)

curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 10}'

Response: {"success": true, "rowIds": ["row-...", ...]}

  • Maximum 1000 rows per request
  • Creates empty rows only; use /import for rows with data

Bulk Delete Rows

curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/rows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rowIds": ["row-123", "row-456"]}'

Response: {"success": true}

Bulk Add Columns

curl -X POST https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"columns": [{"name": "Col1", "type": "string"}, {"name": "Col2", "type": "number"}]}'

Response: {"success": true}

Bulk Delete Columns

curl -X DELETE https://www.moltsheet.com/api/v1/sheets/SHEET_ID/columns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"indices": [0, 2]}'

Response: {"success": true}

AI Agent Optimization Features

Self-Correcting Error Messages:

  • Every error includes example field with correct request format
  • Errors show your actual column names when applicable
  • message field provides human-readable context
  • formats or supported_types enumerate valid options

Data Loss Prevention:

  • Schema updates require ?confirmDataLoss=true when deleting columns with data
  • Rename endpoint (POST /columns/{index}/rename) preserves all data automatically
  • Error messages suggest safer alternatives (rename vs delete)

Flexible Input Formats:

  • POST /rows accepts 3 formats: {"count": N}, {"data": {...}}, {"rows": [...]}
  • No need to guess which endpoint to use
  • Wrong format? Error shows all supported formats with examples

AI-Friendly Design:

  • Consistent JSON structure across all endpoints
  • Named column access (not positional)
  • Strict type validation enforced on all data operations
  • Descriptive success messages confirm operations

Type Validation & Enforcement

All data operations (POST /rows, PUT /cells, POST /import) enforce strict type validation:

Validated Types:

  • string: Any non-object value (numbers/booleans auto-converted to strings)
  • number: Must be valid number (not NaN or Infinity). Accepts numeric strings.
  • boolean: Accepts true, false, "true", "false", 1, 0
  • url: Must be valid URL with http/https protocol (e.g., https://example.com)
  • date: Must parse to valid date. Use ISO 8601 format (e.g., 2026-02-01 or 2026-02-01T12:00:00Z)

Validation Behavior:

  • Empty/null values are allowed (no required field enforcement)
  • Invalid types rejected with 400 Bad Request
  • Errors include: field name, expected type, received value, and corrected example
  • Multiple rows: ALL rejected if ANY fail validation (atomic)

Example Validation Error:

{
  "success": false,
  "error": "Type validation failed",
  "message": "Column \"Age\" expects type \"number\" but received \"abc\" (type: string)",
  "field": "Age",
  "expected_type": "number",
  "received_value": "abc",
  "row_index": 0,
  "example": { "data": { "Age": 42 } }
}

Data Structure

  • Schema Types: string, number, boolean, date, url
  • Row Data: Named properties for AI-friendly access, e.g., {"Name": "John", "Role": "CEO"}
  • Type Enforcement: All values validated against schema before storage
  • Errors: Structured with examples using your actual schema

Rate Limits

  • 100 requests/minute

Usage Ideas for AI Agents

  • Parse data and self-correct on errors using provided examples
  • Single endpoint (POST /rows) handles all row creation scenarios
  • Error messages guide agents to proper format automatically
  • Column-aware examples eliminate guessing column names