Getting Started with MLStack

Get up and running with MLStack in 5 minutes. Learn how to authenticate, make your first request, and understand the async job-based flow.

Quick Start

1. Get Your API Key

Log in or sign up to MLStack
Go to Account Settings → API Keys
Click Create API Key and give it a name
Copy and securely store your key (starts with mlsk_)

🚨 Security Warning:
Never commit API keys to version control or share them publicly. Regenerate immediately if compromised.

2. Make Your First Request

MLStack uses an async job-based approach to handle long-running inference:

Submit - Send request, get job ID back immediately
Poll - Check job status until complete
Retrieve - Get the final result

Python Example

import requests
import time

API_KEY = "mlsk_your_key_here"
BASE_URL = "https://mlstack.io"

# Step 1: Submit job
response = requests.post(
    f"{BASE_URL}/api/llm/predict",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Explain quantum computing in simple terms",
        "base_model": "meta-llama/Llama-3.1-8B-Instruct",
        "max_new_tokens": 150,
        "temperature": 0.7
    }
)

job_id = response.json()["job_id"]
print(f"✓ Job submitted: {job_id}")

# Step 2: Poll for results
while True:
    result = requests.get(
        f"{BASE_URL}/api/llm/result/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )

    data = result.json()

    if data["status"] == "completed":
        print(f"✓ Output: {data['output']}")
        break
    elif data["status"] == "failed":
        print(f"✗ Error: {data['error']}")
        break
    else:
        print("⏳ Processing...")
        time.sleep(1)

cURL Example

# Submit job
JOB_ID=$(curl -X POST https://mlstack.io/api/llm/predict \
  -H "Authorization: Bearer mlsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is machine learning?",
    "base_model": "meta-llama/Llama-3.1-8B-Instruct",
    "max_new_tokens": 100
  }' | jq -r '.job_id')

# Poll for result
curl https://mlstack.io/api/llm/result/$JOB_ID \
  -H "Authorization: Bearer mlsk_your_key_here"

JavaScript Example

const API_KEY = "mlsk_your_key_here";
const BASE_URL = "https://mlstack.io";

// Submit job
const submitResponse = await fetch(`${BASE_URL}/api/llm/predict`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Explain neural networks",
    base_model: "meta-llama/Llama-3.1-8B-Instruct",
    max_new_tokens: 150
  })
});

const { job_id } = await submitResponse.json();
console.log(`✓ Job submitted: ${job_id}`);

// Poll for results
while (true) {
  const resultResponse = await fetch(`${BASE_URL}/api/llm/result/${job_id}`, {
    headers: { "Authorization": `Bearer ${API_KEY}` }
  });

  const data = await resultResponse.json();

  if (data.status === "completed") {
    console.log(`✓ Output: ${data.output}`);
    break;
  } else if (data.status === "failed") {
    console.error(`✗ Error: ${data.error}`);
    break;
  }

  await new Promise(resolve => setTimeout(resolve, 1000));
}

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer mlsk_your_api_key_here

Managing API Keys

Multiple Keys

Create separate keys for different environments:

Development - For local testing
Production - For your live application
CI/CD - For automated deployments

Regenerating Keys

If a key is compromised:

Go to Account Settings → API Keys
Click Regenerate next to the key
Update your application with the new key

The old key is immediately invalidated.

Deleting Keys

To permanently delete an API key:

Go to Account Settings → API Keys
Click Delete next to the key
Confirm deletion

⚠️ Rate Limits:
- API key creation: 5 per hour - API key regeneration: 10 per hour

Request Parameters

Common Parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	Input text for the model
`adapter_name`	string	No*	Use a specific LoRA adapter
`base_model`	string	No*	Use a base model directly
`schema_name`	string	No	Apply structured output schema
`max_new_tokens`	integer	No	Max tokens to generate (default: 256)
`temperature`	float	No	Sampling temperature 0-1 (default: 0.7)

You must specify either* adapter_name OR base_model (not both).

Response Format

Submit Response (200 OK)

{
  "job_id": "fc-abc123",
  "status": "submitted"
}

Poll Response - Processing (202 Accepted)

{
  "job_id": "fc-abc123",
  "status": "processing"
}

Poll Response - Completed (200 OK)

{
  "job_id": "fc-abc123",
  "status": "completed",
  "output": "Generated text response...",
  "metadata": {
    "duration": 2.5,
    "tokens_generated": 150
  }
}

Poll Response - Failed (500 Internal Server Error)

{
  "job_id": "fc-abc123",
  "status": "failed",
  "error": "Error description"
}

Next Steps

Create LoRA Adapters - Train and register fine-tuned models
Create AI Agents - Build AI agents with tool access
Structured Output - Enforce JSON schemas for reliable parsing
API Reference - Complete endpoint documentation

Common Issues

401 Unauthorized

Check that your API key is correct
Ensure the Authorization header is properly formatted
Verify the key hasn't been deleted or regenerated

402 Payment Required

Your account has insufficient credits
Go to Account Settings → Billing to add credits

429 Rate Limit Exceeded

LLM API: 60 requests/minute
Agent API: 30 requests/minute
Wait before retrying again

404 Not Found

Job ID doesn't exist or has expired
Verify you're using the correct endpoint URL

Documentation