API Reference

Use the statboy API to create a request with an attached file, then poll that request until it finishes.

This API is designed for teams that start in the Statboy UI, prove a cleanup or analysis workflow, and then automate the same CSV and spreadsheet work through code.

Overview

Base URL: https://data-transform-api.fly.dev

Authenticate every request with x-api-key.

Uploads are sent directly on POST /api/v1/requests usingmultipart/form-data and a singlefile field.

Current file size limit: 25 MB per request.

A typical flow is: upload a file, let Statboy plan the work, monitor task progress, and inspect result metadata for datasets, quality checks, and downstream actions.

Endpoints

Method	Path	Auth	Description
POST	/api/v1/requests	API Key	Create a new request, upload one input file with the request, and start the worker.
GET	/api/v1/requests/:id	API Key	Read the current request status, timestamps, task progress, summary, and any result metadata.

Create Request

Send a prompt and a file in the same request. The response gives you the new request id and the URL to poll.

curl -X POST "https://data-transform-api.fly.dev/api/v1/requests" \
  -H "x-api-key: $STATBOY_API_KEY" \
  -F "prompt=Clean this CSV, normalize the headers, and build a dataset." \
  -F "model=sonnet" \
  -F "file=@./sales.csv;type=text/csv"

Response

{
  "id": "wr_123",
  "status": "PLANNED",
  "summary": "Planning request...",
  "createdAt": "2026-04-03T14:05:00Z",
  "statusUrl": "/api/v1/requests/wr_123"
}

Get Request Status

Poll the request until status reaches a terminal state likeSUCCEEDED orFAILED.

curl -H "x-api-key: $STATBOY_API_KEY" \
  "https://data-transform-api.fly.dev/api/v1/requests/wr_123"

Response

{
  "id": "wr_123",
  "title": "Normalize Sales Export and Build Dataset",
  "prompt": "Clean this CSV, normalize the headers, and build a dataset.",
  "status": "SUCCEEDED",
  "summary": "Dataset created successfully.",
  "createdAt": "2026-04-03T14:05:00Z",
  "updatedAt": "2026-04-03T14:06:12Z",
  "startedAt": "2026-04-03T14:05:03Z",
  "completedAt": "2026-04-03T14:06:12Z",
  "result": {
    "dataset_id": "ds_123",
    "dataset_ingestion_id": "ing_123",
    "quality_grade": "HIGH"
  },
  "tasks": [
    {
      "id": "task_1",
      "type": "REQUEST_PLAN",
      "status": "SUCCEEDED"
    },
    {
      "id": "task_2",
      "type": "DATASET_WRITE",
      "status": "SUCCEEDED"
    }
  ]
}

If you are evaluating the API for a recurring spreadsheet workflow, start in the product first, confirm the prompt and output shape you want, then move the same pattern into automation once the workflow is stable.