API Reference

File processing API powered by DuckDB. Upload files or pass a URL directly to convert formats, run SQL queries, and profile data.

https://chatdb.ai/api

Discovery

GET/health

Health check

curl "https://chatdb.ai/api/health"

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "duckdb_version": "1.2.0"
}

GET/formats

Supported formats and limits

curl "https://chatdb.ai/api/formats"

Response

{
  "success": true,
  "data": {
    "version": "1.0.0",
    "supported_formats": [
      "csv",
      "json",
      "parquet",
      "txt",
      "xlsx",
      "csv.gz"
    ],
    "conversion_matrix": {
      "csv": [
        "json",
        "parquet",
        "csv.gz"
      ],
      "json": [
        "csv",
        "parquet",
        "csv.gz"
      ],
      "parquet": [
        "csv",
        "json",
        "csv.gz"
      ]
    },
    "compression_formats": [
      "gzip",
      "zstd",
      "snappy"
    ],
    "limits": {
      "max_file_size_bytes": 1500000000,
      "max_query_rows": 10000,
      "max_query_timeout_seconds": 120
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 42.5
  }
}

Files

POST/files

Upload a file

Body

filestring

File

Upload a file

curl -X POST "https://chatdb.ai/api/files" \
  -F "file=@data.csv"

Response

{
  "success": true,
  "data": {
    "file_id": "f_a1b2c3d4e5f6",
    "filename": "sales_data.csv",
    "format": "csv",
    "size_bytes": 524288,
    "row_count": 10000,
    "column_count": 5,
    "columns": [
      {
        "name": "id",
        "type": "INTEGER"
      },
      {
        "name": "name",
        "type": "VARCHAR"
      },
      {
        "name": "amount",
        "type": "DOUBLE"
      }
    ],
    "download_url": "https://r2.cloudflarestorage.com/...",
    "created_at": "2026-02-27T12:00:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 42.5
  }
}

GET/files/{file_id}

Get file info

Path Parameters

file_idstringrequired

Get file info

curl "https://chatdb.ai/api/files/{file_id}"

Response

{
  "success": true,
  "data": {
    "file_id": "f_a1b2c3d4e5f6",
    "filename": "sales_data.csv",
    "format": "csv",
    "status": "confirmed",
    "size_bytes": 524288,
    "row_count": 10000,
    "column_count": 5,
    "columns": [
      {
        "name": "id",
        "type": "INTEGER"
      },
      {
        "name": "name",
        "type": "VARCHAR"
      }
    ],
    "download_url": "https://r2.cloudflarestorage.com/..."
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 42.5
  }
}

Conversion

POST/convert

Convert a file between formats

Body

file_idstring

ID of a previously uploaded file

file_urlstring

URL to fetch the file from directly

All possible output formats: data formats + compression.

optionsobject

Format-specific conversion options

Convert a file between formats

curl -X POST "https://chatdb.ai/api/convert" \
  -H "Content-Type: application/json" \
  -d '{
  "file_url": "https://example.com/data.csv",
  "output_format": "csv"
}'

Response

{
  "success": true,
  "data": {
    "output": {
      "format": "parquet",
      "filename": "converted.parquet",
      "size_bytes": 262144,
      "row_count": 10000,
      "download_url": "https://r2.cloudflarestorage.com/..."
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 1250.8
  }
}

Query

POST/query

Run a SQL query

Body

file_idstring

ID of a previously uploaded file

file_urlstring

URL to fetch the file from directly

sqlstringrequired

SQL query (file is available as table 'data')

limitinteger= 1000

Max rows to return

timeout_secondsinteger= 30

Query timeout in seconds

formatstring= "records"

Result format: 'records' (array of objects) or 'columnar'

export_format"csv" | "json" | "parquet" | "csv.gz"

If set, export results as a downloadable file instead of inline rows (csv, json, parquet, csv.gz)

Run a SQL query

curl -X POST "https://chatdb.ai/api/query" \
  -H "Content-Type: application/json" \
  -d '{
  "file_url": "https://example.com/data.csv",
  "sql": "SELECT * FROM data LIMIT 10",
  "limit": 1000,
  "timeout_seconds": 30,
  "format": "records",
  "export_format": "csv"
}'

Response

{
  "success": true,
  "data": {
    "columns": [
      {
        "name": "name",
        "type": "VARCHAR"
      },
      {
        "name": "total",
        "type": "DOUBLE"
      }
    ],
    "rows": [
      {
        "name": "Alice",
        "total": 1500
      },
      {
        "name": "Bob",
        "total": 2300.5
      }
    ],
    "row_count": 2,
    "truncated": false
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 85.2
  }
}

Profiling

POST/profile

Profile a dataset

Body

file_idstring

ID of a previously uploaded file

file_urlstring

URL to fetch the file from directly

sample_sizeinteger

Rows to sample (null = full scan)

include_distributionsboolean= true

Include histogram/value_count data

columnsstring[]

Specific columns to profile (null = all)

Profile a dataset

curl -X POST "https://chatdb.ai/api/profile" \
  -H "Content-Type: application/json" \
  -d '{
  "file_url": "https://example.com/data.csv",
  "include_distributions": true
}'

Response

{
  "success": true,
  "data": {
    "row_count": 10000,
    "column_count": 5,
    "sample_size": 10000,
    "columns": [
      {
        "name": "amount",
        "type": "DOUBLE",
        "stats": {
          "count": 10000,
          "null_count": 12,
          "null_percent": 0.12,
          "unique_count": 8542,
          "min": 0.5,
          "max": 9999.99,
          "mean": 2450.32,
          "median": 1890,
          "std": 1823.45
        }
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 520.1
  }
}

API Reference

File processing API powered by DuckDB. Upload files or pass a URL directly to convert formats, run SQL queries, and profile data.

https://chatdb.ai/api

Discovery

GET/health

Health check

curl "https://chatdb.ai/api/health"

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "duckdb_version": "1.2.0"
}

GET/formats

Supported formats and limits

curl "https://chatdb.ai/api/formats"

Response

{
  "success": true,
  "data": {
    "version": "1.0.0",
    "supported_formats": [
      "csv",
      "json",
      "parquet",
      "txt",
      "xlsx",
      "csv.gz"
    ],
    "conversion_matrix": {
      "csv": [
        "json",
        "parquet",
        "csv.gz"
      ],
      "json": [
        "csv",
        "parquet",
        "csv.gz"
      ],
      "parquet": [
        "csv",
        "json",
        "csv.gz"
      ]
    },
    "compression_formats": [
      "gzip",
      "zstd",
      "snappy"
    ],
    "limits": {
      "max_file_size_bytes": 1500000000,
      "max_query_rows": 10000,
      "max_query_timeout_seconds": 120
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 42.5
  }
}

Files

POST/files

Upload a file

Body

filestring

File

Upload a file

curl -X POST "https://chatdb.ai/api/files" \
  -F "file=@data.csv"

Response

{
  "success": true,
  "data": {
    "file_id": "f_a1b2c3d4e5f6",
    "filename": "sales_data.csv",
    "format": "csv",
    "size_bytes": 524288,
    "row_count": 10000,
    "column_count": 5,
    "columns": [
      {
        "name": "id",
        "type": "INTEGER"
      },
      {
        "name": "name",
        "type": "VARCHAR"
      },
      {
        "name": "amount",
        "type": "DOUBLE"
      }
    ],
    "download_url": "https://r2.cloudflarestorage.com/...",
    "created_at": "2026-02-27T12:00:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 42.5
  }
}

GET/files/{file_id}

Get file info

Path Parameters

file_idstringrequired

Get file info

curl "https://chatdb.ai/api/files/{file_id}"

Response

{
  "success": true,
  "data": {
    "file_id": "f_a1b2c3d4e5f6",
    "filename": "sales_data.csv",
    "format": "csv",
    "status": "confirmed",
    "size_bytes": 524288,
    "row_count": 10000,
    "column_count": 5,
    "columns": [
      {
        "name": "id",
        "type": "INTEGER"
      },
      {
        "name": "name",
        "type": "VARCHAR"
      }
    ],
    "download_url": "https://r2.cloudflarestorage.com/..."
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 42.5
  }
}

Conversion

POST/convert

Convert a file between formats

Body

file_idstring

ID of a previously uploaded file

file_urlstring

URL to fetch the file from directly

All possible output formats: data formats + compression.

optionsobject

Format-specific conversion options

Convert a file between formats

curl -X POST "https://chatdb.ai/api/convert" \
  -H "Content-Type: application/json" \
  -d '{
  "file_url": "https://example.com/data.csv",
  "output_format": "csv"
}'

Response

{
  "success": true,
  "data": {
    "output": {
      "format": "parquet",
      "filename": "converted.parquet",
      "size_bytes": 262144,
      "row_count": 10000,
      "download_url": "https://r2.cloudflarestorage.com/..."
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 1250.8
  }
}

Query

POST/query

Run a SQL query

Body

file_idstring

ID of a previously uploaded file

file_urlstring

URL to fetch the file from directly

sqlstringrequired

SQL query (file is available as table 'data')

limitinteger= 1000

Max rows to return

timeout_secondsinteger= 30

Query timeout in seconds

formatstring= "records"

Result format: 'records' (array of objects) or 'columnar'

export_format"csv" | "json" | "parquet" | "csv.gz"

If set, export results as a downloadable file instead of inline rows (csv, json, parquet, csv.gz)

Run a SQL query

curl -X POST "https://chatdb.ai/api/query" \
  -H "Content-Type: application/json" \
  -d '{
  "file_url": "https://example.com/data.csv",
  "sql": "SELECT * FROM data LIMIT 10",
  "limit": 1000,
  "timeout_seconds": 30,
  "format": "records",
  "export_format": "csv"
}'

Response

{
  "success": true,
  "data": {
    "columns": [
      {
        "name": "name",
        "type": "VARCHAR"
      },
      {
        "name": "total",
        "type": "DOUBLE"
      }
    ],
    "rows": [
      {
        "name": "Alice",
        "total": 1500
      },
      {
        "name": "Bob",
        "total": 2300.5
      }
    ],
    "row_count": 2,
    "truncated": false
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 85.2
  }
}

Profiling

POST/profile

Profile a dataset

Body

file_idstring

ID of a previously uploaded file

file_urlstring

URL to fetch the file from directly

sample_sizeinteger

Rows to sample (null = full scan)

include_distributionsboolean= true

Include histogram/value_count data

columnsstring[]

Specific columns to profile (null = all)

Profile a dataset

curl -X POST "https://chatdb.ai/api/profile" \
  -H "Content-Type: application/json" \
  -d '{
  "file_url": "https://example.com/data.csv",
  "include_distributions": true
}'

Response

{
  "success": true,
  "data": {
    "row_count": 10000,
    "column_count": 5,
    "sample_size": 10000,
    "columns": [
      {
        "name": "amount",
        "type": "DOUBLE",
        "stats": {
          "count": 10000,
          "null_count": 12,
          "null_percent": 0.12,
          "unique_count": 8542,
          "min": 0.5,
          "max": 9999.99,
          "mean": 2450.32,
          "median": 1890,
          "std": 1823.45
        }
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123def456",
    "processing_time_ms": 520.1
  }
}