Export your Prem API key as API_KEY before running any script.

Setup: Define your JSONL file

const API_KEY = process.env.API_KEY;

// Define your JSONL dataset file
const JSONL_FILE_PATH = 'sample_data.jsonl';

import os
import time
import requests

API_KEY = os.getenv("API_KEY")

# Define your JSONL dataset file
JSONL_FILE_PATH = "sample_data.jsonl"

Define the path to your JSONL dataset file. Make sure the file exists and is properly formatted.

Create a project

const res = await fetch('https://studio.premai.io/api/v1/public/projects/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'Test Project', goal: 'Test finetuning' })
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const { project_id } = await res.json();

response = requests.post(
    "https://studio.premai.io/api/v1/public/projects/create",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"name": "Test Project", "goal": "Test finetuning"}
)
response.raise_for_status()
project_id = response.json()["project_id"]

Start by creating a project workspace. The project_id is required for all subsequent operations.

Upload JSONL dataset

const formData = new FormData();
formData.append('project_id', project_id);
formData.append('name', 'Test Dataset');
const jsonlFile = file(JSONL_FILE_PATH);
formData.append('file', jsonlFile, JSONL_FILE_PATH);

const res = await fetch('https://studio.premai.io/api/v1/public/datasets/create-from-jsonl', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: formData
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const { dataset_id } = await res.json();

with open(JSONL_FILE_PATH, 'rb') as f:
    files = {'file': (JSONL_FILE_PATH, f, 'application/json')}
    data = {'project_id': project_id, 'name': 'Test Dataset'}
    response = requests.post(
        "https://studio.premai.io/api/v1/public/datasets/create-from-jsonl",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files=files,
        data=data
    )
response.raise_for_status()
dataset_id = response.json()["dataset_id"]

Upload your pre-formatted JSONL file. Each line should contain a chat conversation in the expected format. For details on the required dataset structure, see Dataset Structure.

Wait for dataset processing

let dataset;
do {
  await sleep(2000);
  const res = await fetch(`https://studio.premai.io/api/v1/public/datasets/${dataset_id}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  dataset = await res.json();
} while (dataset.status === 'processing');

while True:
    time.sleep(2)
    response = requests.get(
        f"https://studio.premai.io/api/v1/public/datasets/{dataset_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    response.raise_for_status()
    dataset = response.json()
    if dataset["status"] != "processing":
        break

Poll the dataset status until processing completes. JSONL uploads are typically fast.

Create snapshot

const res = await fetch('https://studio.premai.io/api/v1/public/snapshots/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ dataset_id, split_percentage: 80 })
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const { snapshot_id } = await res.json();

response = requests.post(
    "https://studio.premai.io/api/v1/public/snapshots/create",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"dataset_id": dataset_id, "split_percentage": 80}
)
response.raise_for_status()
snapshot_id = response.json()["snapshot_id"]

Split the dataset into training and validation sets. The default 80/20 split works well for most cases.

Generate recommendations

const res = await fetch('https://studio.premai.io/api/v1/public/recommendations/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ snapshot_id })
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);

let recs;
do {
  await sleep(5000);
  const res2 = await fetch(`https://studio.premai.io/api/v1/public/recommendations/${snapshot_id}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  if (!res2.ok) throw new Error(`${res2.status}: ${await res2.text()}`);
  recs = await res2.json();
} while (recs.status === 'processing');

response = requests.post(
    "https://studio.premai.io/api/v1/public/recommendations/generate",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"snapshot_id": snapshot_id}
)
response.raise_for_status()

while True:
    time.sleep(5)
    response = requests.get(
        f"https://studio.premai.io/api/v1/public/recommendations/{snapshot_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    response.raise_for_status()
    recs = response.json()
    if recs["status"] != "processing":
        break

Request model recommendations for your snapshot. Poll until recommendations are ready, then filter for recommended models.

Create fine-tuning job

const experiments = recs.recommended_experiments
  .filter((e: any) => e.recommended)
  .map(({ recommended, reason_for_recommendation, ...experiment }: any) => experiment);

const res = await fetch('https://studio.premai.io/api/v1/public/finetuning/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ snapshot_id, name: 'Test Job', experiments })
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const { job_id } = await res.json();

experiments = [
    {k: v for k, v in exp.items() if k not in ["recommended", "reason_for_recommendation"]}
    for exp in recs["recommended_experiments"] if exp["recommended"]
]

response = requests.post(
    "https://studio.premai.io/api/v1/public/finetuning/create",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"snapshot_id": snapshot_id, "name": "Test Job", "experiments": experiments}
)
response.raise_for_status()
job_id = response.json()["job_id"]

Filter recommended experiments and use them directly to launch the fine-tuning job.

Monitor job progress

for (let i = 0; i < 30; i++) {
  await sleep(10000);
  const res = await fetch(`https://studio.premai.io/api/v1/public/finetuning/${job_id}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  const job = await res.json();
  console.log(`Status: ${job.status}`);
  job.experiments.forEach((e: any) => {
    console.log(`  - Exp #${e.experiment_number}: ${e.status} ${e.model_id || ''}`);
  });
  if (job.status !== 'processing') break;
}

for i in range(30):
    time.sleep(10)
    response = requests.get(
        f"https://studio.premai.io/api/v1/public/finetuning/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    response.raise_for_status()
    job = response.json()
    print(f"Status: {job['status']}")
    for exp in job["experiments"]:
        print(f"  - Exp #{exp['experiment_number']}: {exp['status']} {exp.get('model_id', '')}")
    if job["status"] != "processing":
        break

Poll the job status every 10 seconds. Each experiment shows its status and final model ID when complete.

Full Example

#!/usr/bin/env bun

/**
 * Example 1: JSONL dataset workflow
 * 1. Create project → 2. Upload JSONL → 3. Create snapshot → 4. Get recommendations → 5. Run finetuning
 */

import { file } from 'bun';

const API_KEY = process.env.API_KEY;
const JSONL_FILE_PATH = 'sample_data.jsonl';

if (!API_KEY) {
	console.error('Error: API_KEY environment variable is required');
	console.error('Please create a .env file based on .env.example');
	process.exit(1);
}

function sleep(ms: number) {
	return new Promise((r) => setTimeout(r, ms));
}

async function main() {
	console.log('\n=== JSONL Workflow ===\n');

	// 1. Create project
	console.log('1. Creating project...');
	const res1 = await fetch('https://studio.premai.io/api/v1/public/projects/create', {
		method: 'POST',
		headers: {
			'Authorization': `Bearer ${API_KEY}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({ name: 'Test Project', goal: 'Test finetuning' }),
	});
	if (!res1.ok) throw new Error(`${res1.status}: ${await res1.text()}`);
	const { project_id } = await res1.json();
	console.log(`   ✓ Project: ${project_id}\n`);

	// 2. Upload JSONL
	console.log('2. Uploading JSONL dataset...');
	const formData = new FormData();
	formData.append('project_id', project_id);
	formData.append('name', 'Test Dataset');
	const jsonlFile = file(JSONL_FILE_PATH);
	formData.append('file', jsonlFile, JSONL_FILE_PATH);

	const res2 = await fetch('https://studio.premai.io/api/v1/public/datasets/create-from-jsonl', {
		method: 'POST',
		headers: { 'Authorization': `Bearer ${API_KEY}` },
		body: formData,
	});
	if (!res2.ok) throw new Error(`${res2.status}: ${await res2.text()}`);
	const { dataset_id } = await res2.json();
	console.log(`   ✓ Dataset: ${dataset_id}`);

	// Wait for dataset
	console.log('   Waiting for dataset...');
	let dataset;
	do {
		await sleep(2000);
		const res = await fetch(`https://studio.premai.io/api/v1/public/datasets/${dataset_id}`, {
			headers: { 'Authorization': `Bearer ${API_KEY}` }
		});
		if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
		dataset = await res.json();
	} while (dataset.status === 'processing');
	console.log(`   ✓ Ready: ${dataset.datapoints_count} datapoints\n`);

	// 3. Create snapshot
	console.log('3. Creating snapshot...');
	const res3 = await fetch('https://studio.premai.io/api/v1/public/snapshots/create', {
		method: 'POST',
		headers: {
			'Authorization': `Bearer ${API_KEY}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({ dataset_id, split_percentage: 80 }),
	});
	if (!res3.ok) throw new Error(`${res3.status}: ${await res3.text()}`);
	const { snapshot_id } = await res3.json();
	console.log(`   ✓ Snapshot: ${snapshot_id}\n`);

	// 4. Generate recommendations
	console.log('4. Generating recommendations...');
	const res4 = await fetch('https://studio.premai.io/api/v1/public/recommendations/generate', {
		method: 'POST',
		headers: {
			'Authorization': `Bearer ${API_KEY}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({ snapshot_id }),
	});
	if (!res4.ok) throw new Error(`${res4.status}: ${await res4.text()}`);

	let recs;
	do {
		await sleep(5000);
		const res = await fetch(`https://studio.premai.io/api/v1/public/recommendations/${snapshot_id}`, {
			headers: { 'Authorization': `Bearer ${API_KEY}` }
		});
		if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
		recs = await res.json();
	} while (recs.status === 'processing');

	console.log(`   ✓ Recommended experiments:`);
	const recommendedCount = recs.recommended_experiments.filter((e: any) => e.recommended).length;
	console.log(`   Total experiments: ${recs.recommended_experiments.length}, Recommended: ${recommendedCount}`);
	recs.recommended_experiments.forEach((e: any) => {
		if (e.recommended) console.log(`     - ${e.base_model_id} (LoRA: ${e.lora})`);
	});
	console.log();

	// 5. Create finetuning job
	console.log('5. Creating finetuning job...');
	const experiments = recs.recommended_experiments
		.filter((e: any) => e.recommended)
		.map(({ recommended, reason_for_recommendation, ...experiment }: any) => experiment);

	if (experiments.length === 0) {
		console.error('\n✗ Error: No recommended experiments found. Cannot create finetuning job.');
		process.exit(1);
	}

	const res5 = await fetch('https://studio.premai.io/api/v1/public/finetuning/create', {
		method: 'POST',
		headers: {
			'Authorization': `Bearer ${API_KEY}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({ snapshot_id, name: 'Test Job', experiments }),
	});
	if (!res5.ok) throw new Error(`${res5.status}: ${await res5.text()}`);
	const { job_id } = await res5.json();
	console.log(`   ✓ Job: ${job_id}\n`);

	// 6. Monitor (5 minutes max)
	console.log('6. Monitoring job...');
	for (let i = 0; i < 30; i++) {
		await sleep(10000);
		const res = await fetch(`https://studio.premai.io/api/v1/public/finetuning/${job_id}`, {
			headers: { 'Authorization': `Bearer ${API_KEY}` }
		});
		if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
		const job = await res.json();
		console.log(`   Status: ${job.status}`);
		job.experiments.forEach((e: any) => {
			console.log(`     - Exp #${e.experiment_number}: ${e.status} ${e.model_id || ''}`);
		});
		if (job.status !== 'processing') break;
	}

	console.log('\n✓ Done!\n');
}

main().catch((err) => {
	console.error('\n✗ Error:', err.message);
	process.exit(1);
});

#!/usr/bin/env python3

"""
Example 1: JSONL dataset workflow
1. Create project → 2. Upload JSONL → 3. Create snapshot → 4. Get recommendations → 5. Run finetuning
"""

import os
import time
import requests

API_KEY = os.getenv("API_KEY")
JSONL_FILE_PATH = "sample_data.jsonl"

if not API_KEY:
    print("Error: API_KEY environment variable is required")
    exit(1)


def api(endpoint: str, method: str = "GET", **kwargs):
    response = requests.request(
        method=method,
        url=f"https://studio.premai.io{endpoint}",
        headers={"Authorization": f"Bearer {API_KEY}", **kwargs.pop("headers", {})},
        **kwargs
    )
    if not response.ok:
        err = response.json() if response.content else {}
        error_msg = err.get("error", str(err)) if isinstance(err, dict) else str(err)
        raise Exception(f"{response.status_code}: {error_msg}")
    return response.json()


def main():
    print("\n=== JSONL Workflow ===\n")

    #  Create project
    print("1. Creating project...")
    result = api("/api/v1/public/projects/create", method="POST", headers={"Content-Type": "application/json"}, json={"name": "Test Project", "goal": "Test finetuning"})
    project_id = result["project_id"]
    print(f"   ✓ Project: {project_id}\n")

    #  Upload JSONL
    print("2. Uploading JSONL dataset...")
    with open(JSONL_FILE_PATH, "rb") as f:
        files = {"file": (JSONL_FILE_PATH, f, "application/json")}
        data = {"project_id": project_id, "name": "Test Dataset"}
        result = api("/api/v1/public/datasets/create-from-jsonl", method="POST", files=files, data=data)
    dataset_id = result["dataset_id"]
    print(f"   ✓ Dataset: {dataset_id}")

    # Wait for dataset
    print("   Waiting for dataset...")
    while True:
        time.sleep(2)
        dataset = api(f"/api/v1/public/datasets/{dataset_id}")
        if dataset["status"] != "processing":
            break
    print(f"   ✓ Ready: {dataset['datapoints_count']} datapoints\n")

    #  Create snapshot
    print("3. Creating snapshot...")
    result = api("/api/v1/public/snapshots/create", method="POST", headers={"Content-Type": "application/json"}, json={"dataset_id": dataset_id, "split_percentage": 80})
    snapshot_id = result["snapshot_id"]
    print(f"   ✓ Snapshot: {snapshot_id}\n")

    #  Generate recommendations
    print("4. Generating recommendations...")
    api("/api/v1/public/recommendations/generate", method="POST", headers={"Content-Type": "application/json"}, json={"snapshot_id": snapshot_id})

    while True:
        time.sleep(5)
        recs = api(f"/api/v1/public/recommendations/{snapshot_id}")
        if recs["status"] != "processing":
            break

    print("   ✓ Recommended experiments:")
    recommended_count = sum(1 for e in recs["recommended_experiments"] if e["recommended"])
    print(f"   Total experiments: {len(recs['recommended_experiments'])}, Recommended: {recommended_count}")
    for e in recs["recommended_experiments"]:
        if e["recommended"]:
            print(f"     - {e['base_model_id']} (LoRA: {e['lora']})")
    print()

    #  Create finetuning job
    print("5. Creating finetuning job...")
    experiments = [
        {k: v for k, v in exp.items() if k not in ["recommended", "reason_for_recommendation"]}
        for exp in recs["recommended_experiments"] if exp["recommended"]
    ]

    if not experiments:
        print("\n✗ Error: No recommended experiments found. Cannot create finetuning job.")
        exit(1)

    result = api("/api/v1/public/finetuning/create", method="POST", headers={"Content-Type": "application/json"}, json={"snapshot_id": snapshot_id, "name": "Test Job", "experiments": experiments})
    job_id = result["job_id"]
    print(f"   ✓ Job: {job_id}\n")

    #  Monitor (5 minutes max)
    print("6. Monitoring job...")
    for i in range(30):
        time.sleep(10)
        job = api(f"/api/v1/public/finetuning/{job_id}")
        print(f"   Status: {job['status']}")
        for exp in job["experiments"]:
            print(f"     - Exp #{exp['experiment_number']}: {exp['status']} {exp.get('model_id', '')}")
        if job["status"] != "processing":
            break

    print("\n✓ Done!\n")


if __name__ == "__main__":
    try:
        main()
    except Exception as err:
        print(f"\n✗ Error: {err}")
        exit(1)

API Get Started

Walkthroughs 🎯

Projects API

Datasets API

Snapshots API

Recommendations API

Fine-Tuning API

Chat API

Models API

Traces API

JSONL Dataset Workflow

Setup: Define your JSONL file

Create a project

Upload JSONL dataset

Wait for dataset processing

Create snapshot

Generate recommendations

Create fine-tuning job

Monitor job progress

Full Example

​Setup: Define your JSONL file

​Create a project

​Upload JSONL dataset

​Wait for dataset processing

​Create snapshot

​Generate recommendations

​Create fine-tuning job

​Monitor job progress

​Full Example

Setup: Define your JSONL file

Create a project

Upload JSONL dataset

Wait for dataset processing

Create snapshot

Generate recommendations

Create fine-tuning job

Monitor job progress

Full Example