API Reference

Programmatic access to your datasets, queries, and dashboards.

v1Pro & Enterprise

Quick Start

All API requests require a Bearer token. Create an API key from Settings → API Keys in the Sheetora app.

curl https://sheetora.app/api/v1/datasets \
  -H "Authorization: Bearer sk_live_your_api_key"

Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

API keys are scoped to a workspace and have a role (viewer, member, or admin) that controls which endpoints they can access.

Base URL

https://sheetora.app/api/v1

Rate Limits

Plan	Rate Limit
Pro	60 requests/minute
Enterprise	300 requests/minute

When rate limited, responses return HTTP 429 with a retry_after_seconds field.

Endpoints

GET/api/v1/datasetsmin role: viewer

List Datasets

Returns all datasets in your workspace with pagination.

Parameters

Name	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "monthly_p&l_report.xlsx",
      "status": "ready",
      "file_type": "xlsx",
      "row_count": 1847,
      "file_size_bytes": 245760,
      "description": null,
      "tags": [],
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-01T12:05:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 5 }
}

GET/api/v1/datasets/:idmin role: viewer

Get Dataset

Returns a single dataset with its tables and column metadata.

Parameters

Name	Type	Default	Description
id	uuid	required	Dataset ID (path parameter)

Response

{
  "data": {
    "id": "uuid",
    "name": "monthly_p&l_report.xlsx",
    "status": "ready",
    "tables": [
      {
        "id": "uuid",
        "name": "Sheet1",
        "row_count": 1847,
        "column_count": 12,
        "columns": [
          {
            "id": "uuid",
            "name": "revenue",
            "data_type": "numeric",
            "role": "measure",
            "nullable": false,
            "distinct_count": 1200,
            "sample_values": [24500, 31200, 28900]
          }
        ]
      }
    ]
  }
}

POST/api/v1/querymin role: member

Execute SQL Query

Run a read-only SQL query against a dataset table. Only SELECT statements are allowed; DDL and DML are blocked.

Request Body

{
  "dataset_id": "uuid",
  "table_id": "uuid",
  "sql": "SELECT revenue, month FROM \"Sheet1\" WHERE revenue > 20000 LIMIT 100"
}

Response

{
  "data": {
    "columns": ["revenue", "month"],
    "rows": [
      [24500, "January"],
      [31200, "February"]
    ]
  }
}

POST/api/v1/askmin role: member

Ask AI Question

Ask a natural language question about your data. The AI generates and executes SQL, then returns the answer.

Request Body

{
  "dataset_id": "uuid",
  "table_id": "uuid",
  "question": "What was the month with the highest revenue?"
}

Response

{
  "data": {
    "answer": "February had the highest revenue at $31,200.",
    "sql": "SELECT month, revenue FROM \"Sheet1\" ORDER BY revenue DESC LIMIT 1",
    "rows": [["February", 31200]],
    "usage": { "total_tokens": 450 }
  }
}

GET/api/v1/dashboards/:datasetIdmin role: viewer

Get Dashboard

Returns the auto-generated dashboard views for a dataset, including chart types, dimensions, and measures.

Parameters

Name	Type	Default	Description
datasetId	uuid	required	Dataset ID (path parameter)

Response

{
  "data": {
    "dataset_id": "uuid",
    "view_count": 6,
    "views": [
      {
        "id": "v-1",
        "title": "Revenue by Month",
        "description": "Monthly revenue trend",
        "chart_type": "line",
        "confidence": 0.92,
        "score": 85,
        "query": {
          "dimensions": [{ "column": "month", "alias": "Month" }],
          "measures": [{ "column": "revenue", "aggregate": "sum", "alias": "Total Revenue" }],
          "table_id": "uuid"
        }
      }
    ]
  }
}

Error Codes

All errors return a JSON body with an error field:

{ "error": "Description of what went wrong" }

Status	Description
400	Bad Request — Missing or invalid parameters
401	Unauthorized — Missing or invalid API key
403	Forbidden — Insufficient permissions or plan restriction
404	Not Found — Resource does not exist or belongs to another workspace
409	Conflict — Resource not in expected state (e.g. dataset not ready)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error
502	Bad Gateway — Data plane unavailable
504	Gateway Timeout — Query timed out

API Key Roles

Role	Access
viewer	List datasets, get dataset details, get dashboards
member	Everything in viewer + execute SQL queries + ask AI questions
admin	Everything in member + workspace management operations

Plan

Rate Limit

Pro

60 requests/minute

Enterprise

300 requests/minute

Endpoints

GET/api/v1/datasetsmin role: viewer

List Datasets

Returns all datasets in your workspace with pagination.

Parameters

Name	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "monthly_p&l_report.xlsx",
      "status": "ready",
      "file_type": "xlsx",
      "row_count": 1847,
      "file_size_bytes": 245760,
      "description": null,
      "tags": [],
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-01T12:05:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 5 }
}

GET/api/v1/datasets/:idmin role: viewer

Get Dataset

Returns a single dataset with its tables and column metadata.

Parameters

Name	Type	Default	Description
id	uuid	required	Dataset ID (path parameter)

Response

{
  "data": {
    "id": "uuid",
    "name": "monthly_p&l_report.xlsx",
    "status": "ready",
    "tables": [
      {
        "id": "uuid",
        "name": "Sheet1",
        "row_count": 1847,
        "column_count": 12,
        "columns": [
          {
            "id": "uuid",
            "name": "revenue",
            "data_type": "numeric",
            "role": "measure",
            "nullable": false,
            "distinct_count": 1200,
            "sample_values": [24500, 31200, 28900]
          }
        ]
      }
    ]
  }
}

POST/api/v1/querymin role: member

Execute SQL Query

Run a read-only SQL query against a dataset table. Only SELECT statements are allowed; DDL and DML are blocked.

Request Body

{
  "dataset_id": "uuid",
  "table_id": "uuid",
  "sql": "SELECT revenue, month FROM \"Sheet1\" WHERE revenue > 20000 LIMIT 100"
}

Response

{
  "data": {
    "columns": ["revenue", "month"],
    "rows": [
      [24500, "January"],
      [31200, "February"]
    ]
  }
}

POST/api/v1/askmin role: member

Ask AI Question

Ask a natural language question about your data. The AI generates and executes SQL, then returns the answer.

Request Body

{
  "dataset_id": "uuid",
  "table_id": "uuid",
  "question": "What was the month with the highest revenue?"
}

Response

{
  "data": {
    "answer": "February had the highest revenue at $31,200.",
    "sql": "SELECT month, revenue FROM \"Sheet1\" ORDER BY revenue DESC LIMIT 1",
    "rows": [["February", 31200]],
    "usage": { "total_tokens": 450 }
  }
}

GET/api/v1/dashboards/:datasetIdmin role: viewer

Get Dashboard

Returns the auto-generated dashboard views for a dataset, including chart types, dimensions, and measures.

Parameters

Name	Type	Default	Description
datasetId	uuid	required	Dataset ID (path parameter)

Response

{
  "data": {
    "dataset_id": "uuid",
    "view_count": 6,
    "views": [
      {
        "id": "v-1",
        "title": "Revenue by Month",
        "description": "Monthly revenue trend",
        "chart_type": "line",
        "confidence": 0.92,
        "score": 85,
        "query": {
          "dimensions": [{ "column": "month", "alias": "Month" }],
          "measures": [{ "column": "revenue", "aggregate": "sum", "alias": "Total Revenue" }],
          "table_id": "uuid"
        }
      }
    ]
  }
}

Error Codes

All errors return a JSON body with an error field:

{ "error": "Description of what went wrong" }

Status	Description
400	Bad Request — Missing or invalid parameters
401	Unauthorized — Missing or invalid API key
403	Forbidden — Insufficient permissions or plan restriction
404	Not Found — Resource does not exist or belongs to another workspace
409	Conflict — Resource not in expected state (e.g. dataset not ready)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error
502	Bad Gateway — Data plane unavailable
504	Gateway Timeout — Query timed out

Role

Access

viewer

List datasets, get dataset details, get dashboards

member

Everything in viewer + execute SQL queries + ask AI questions

admin

Everything in member + workspace management operations