Uploading a File

curl --request POST \
  --url https://api.sutro.sh/upload-to-dataset \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset_id": "<string>"
}
'

import requests

url = "https://api.sutro.sh/upload-to-dataset"

payload = { "dataset_id": "<string>" }
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({dataset_id: '<string>'})
};

fetch('https://api.sutro.sh/upload-to-dataset', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sutro.sh/upload-to-dataset",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dataset_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sutro.sh/upload-to-dataset"

	payload := strings.NewReader("{\n  \"dataset_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sutro.sh/upload-to-dataset")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dataset_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sutro.sh/upload-to-dataset")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dataset_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "file_id": "file_abc123def456"
}

{
  "error": "File with this name already exists in the dataset"
}

POST

upload-to-dataset

Uploading a File

curl --request POST \
  --url https://api.sutro.sh/upload-to-dataset \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset_id": "<string>"
}
'

import requests

url = "https://api.sutro.sh/upload-to-dataset"

payload = { "dataset_id": "<string>" }
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({dataset_id: '<string>'})
};

fetch('https://api.sutro.sh/upload-to-dataset', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sutro.sh/upload-to-dataset",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dataset_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sutro.sh/upload-to-dataset"

	payload := strings.NewReader("{\n  \"dataset_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sutro.sh/upload-to-dataset")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dataset_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sutro.sh/upload-to-dataset")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dataset_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "file_id": "file_abc123def456"
}

{
  "error": "File with this name already exists in the dataset"
}

Using the API directly is not recommended for most users. Instead, we recommend using the Python SDK.

Upload a file to a dataset.

Usage Notes

Currently, only parquet files are supported. Snappy compression is supported.
You can only upload one file at a time via the API. You must make multiple requests to upload multiple files. The Python SDK supports uploading multiple files at once.
All files must have the same schema. Files with schemas that do not match will be rejected.
Names must be unique. If you upload a file with a name that already exists in the dataset, it will be rejected.
When you upload to a dataset, the ordering will be preserved. If you upload multiple files to a dataset, they will be added to the dataset in the order you provide them.

Request Body

dataset_id

string

required

The ID of the dataset to upload the file to

file

required

The file to upload (must be a parquet file)

Headers

Authorization

string

required

Your Sutro API key using Key authentication scheme.Format: Key YOUR_API_KEYExample: Authorization: Key sk_live_abc123...

Response

Returns the file ID of the uploaded file.

file_id

string

The unique identifier for the uploaded file

{
  "file_id": "file_abc123def456"
}

{
  "error": "File with this name already exists in the dataset"
}

Code Examples

import requests

# Upload a parquet file
with open('data.parquet', 'rb') as file:
    response = requests.post(
        'https://api.sutro.sh/upload-to-dataset',
        headers={
            'Authorization': 'Key YOUR_SUTRO_API_KEY'
        },
        json={
            'dataset_id': 'dataset_12345'
        },
        files={
            'file': file
        }
    )

result = response.json()
if 'file_id' in result:
    print(f"File uploaded successfully: {result['file_id']}")
else:
    print(f"Upload failed: {result.get('error', 'Unknown error')}")

const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('dataset_id', 'dataset_12345');
form.append('file', fs.createReadStream('data.parquet'));

const response = await fetch('https://api.sutro.sh/upload-to-dataset', {
  method: 'POST',
  headers: {
    'Authorization': 'Key YOUR_SUTRO_API_KEY',
    ...form.getHeaders()
  },
  body: form
});

const result = await response.json();
if (result.file_id) {
  console.log(`File uploaded successfully: ${result.file_id}`);
} else {
  console.log(`Upload failed: ${result.error || 'Unknown error'}`);
}

curl -X POST https://api.sutro.sh/upload-to-dataset \
  -H "Authorization: Key YOUR_SUTRO_API_KEY" \
  -F "dataset_id=dataset_12345" \
  -F "[email protected]"

Important Considerations

File Format: Only parquet files are currently supported
Schema Consistency: All files in a dataset must share the same schema
Unique Names: File names must be unique within each dataset
Ordering: Files are processed in the order they are uploaded
Compression: Snappy compression is supported for parquet files
Single File Limit: API supports one file per request (use Python SDK for batch uploads)

​Usage Notes

​Request Body

​Headers

​Response

​Code Examples

​Important Considerations

Usage Notes

Request Body

Headers

Response

Code Examples

Important Considerations