API Documentation

Integrate PipeSheets into your applications. Upload files, run transformation pipelines, and download clean data programmatically.

Getting Started

The PipeSheets API lets you automate data cleaning workflows. Here's the typical flow:

1. Get API Key

Generate an API key from your settings page

2. Upload File

Initialize upload, PUT to presigned URL, then confirm

3. Create Job

Run a pipeline on your file and poll for completion

4. Download

Get a presigned URL and download your cleaned file

Authentication

All API requests require authentication via the X-API-Key header.

X-API-Key: psh_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Generate API keys from your account settings. Keep your keys secure and never expose them in client-side code.

Upload Endpoints

Upload files to PipeSheets using a two-step process: initialize the upload to get a presigned URL, then confirm after uploading.

POST/api/v1/public/upload/init10/minute

Initialize Upload

Initialize a file upload and receive a presigned URL. Upload your file directly to the returned URL using a PUT request, then call the complete endpoint.

Request Body

Parameter	Type	Description
`filename`required	string	Original filename including extensionExample: `sales_data.csv`
`content_type`required	string	MIME type of the file (text/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)Example: `text/csv`
`file_size`required	integer	File size in bytesExample: `1048576`

Example Request

curl -X POST "https://pipesheets.com/api/v1/public/upload/init" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "sales_data.csv",
  "content_type": "text/csv",
  "file_size": 1048576
}'

POST/api/v1/public/upload/{file_id}/complete10/minute

Complete Upload

Confirm that a file has been successfully uploaded to storage. Call this after your PUT request to the presigned URL succeeds.

Path Parameters

Parameter	Type	Description
`file_id`required	uuid	The file ID returned from init uploadExample: `550e8400-e29b-41d4-a716-446655440000`

Example Request

curl -X POST "https://pipesheets.com/api/v1/public/upload/550e8400-e29b-41d4-a716-446655440000/complete" \
  -H "X-API-Key: YOUR_API_KEY"

Job Endpoints

Create transformation jobs to clean your data. Jobs run asynchronously - poll the status endpoint to check for completion.

POST/api/v1/public/jobs20/minute

Create Job

Create a new transformation job. The job will be processed asynchronously. Poll the job status endpoint to check for completion.

Request Body

Parameter	Type	Description
`file_id`required	uuid	ID of the file to processExample: `550e8400-e29b-41d4-a716-446655440000`
`pipeline_id`required	uuid	ID of the pipeline to apply (use Quick Clean preset or your custom pipeline)Example: `660e8400-e29b-41d4-a716-446655440001`
`output_format`	string	Output format: 'csv' or 'xlsx' (default: csv)Example: `csv`

Example Request

curl -X POST "https://pipesheets.com/api/v1/public/jobs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "pipeline_id": "660e8400-e29b-41d4-a716-446655440001",
  "output_format": "csv"
}'

GET/api/v1/public/jobs/{job_id}60/minute

Get Job Status

Retrieve the current status of a transformation job. Poll this endpoint to check when your job is complete.

Path Parameters

Parameter	Type	Description
`job_id`required	uuid	The job ID returned from create jobExample: `770e8400-e29b-41d4-a716-446655440002`

Example Request

curl -X GET "https://pipesheets.com/api/v1/public/jobs/770e8400-e29b-41d4-a716-446655440002" \
  -H "X-API-Key: YOUR_API_KEY"

GET/api/v1/public/jobs/{job_id}/download30/minute

Download Job Output

Get a presigned download URL for the completed job output. The URL is valid for 1 hour.

Path Parameters

Parameter	Type	Description
`job_id`required	uuid	The job ID of a completed jobExample: `770e8400-e29b-41d4-a716-446655440002`

Example Request

curl -X GET "https://pipesheets.com/api/v1/public/jobs/770e8400-e29b-41d4-a716-446655440002/download" \
  -H "X-API-Key: YOUR_API_KEY"

Rate Limits

API requests are rate limited per user (identified by API key). Limits vary by endpoint to balance resource usage.

Endpoint	Rate Limit
POST /upload/init	10 requests/minute
POST /upload/{id}/complete	10 requests/minute
POST /jobs	20 requests/minute
GET /jobs/{id}	60 requests/minute
GET /jobs/{id}/download	30 requests/minute

When you exceed a rate limit, you'll receive a 429 response. Wait and retry after the limit resets.

Error Handling

All errors return a consistent JSON structure with an error code, message, and request ID for debugging.

{
  "code": "VALIDATION_ERROR",
  "message": "File is not ready (status: pending)",
  "details": [],
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00Z"
}

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request data
FILE_TOO_LARGE	413	File exceeds size limit
QUOTA_EXCEEDED	429	Concurrent job limit reached
RATE_LIMITED	429	Too many requests