Skip to main content

​
Overview

This guide will walk you through the basics of using the Blast API to:
  1. Authenticate with JWT tokens
  2. Create a benchmark
  3. Add tests to your benchmark
  4. Run tests and view results
  5. Execute simulations

​
Prerequisites

Before you begin, you’ll need:
  • A client ID and client secret from your organization admin
  • Access to at least one project

​
Step 1: Authentication

All API requests require a JWT Bearer token in the Authorization header. To obtain a token, use the OAuth2 client credentials flow: 
import requests

# OAuth2 client credentials parameters
params = {
    'client_id': '<YOUR_CLIENT_ID>',
    'client_secret': '<YOUR_CLIENT_SECRET>',
    'grant_type': 'client_credentials',
    'scope': 'openid profile email',
}

# Request access token
response = requests.post(
    'https://auth.withblast.com/oauth2/token',
    headers={'Content-Type': 'application/x-www-form-urlencoded'},
    data=params
)

# Extract and use the access token
token_data = response.json()
access_token = token_data['access_token']

# Example: Use token in API request
headers = {'Authorization': f'Bearer {access_token}'}
projects_response = requests.get('https://api.withblast.com/projects', headers=headers)
Contact your administrator for client credentials if you don’t have them.
Store your client credentials securely and never commit them to version control.

​
Step 2: Get Your Project ID

First, list all projects accessible to your organization: 
curl --location 'https://api.withblast.com/projects' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN'
Response: 
{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Support Chatbot",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
Save the project id - you’ll need it for all subsequent requests.

​
Step 3: Create a Benchmark

Create a benchmark to organize your tests: 
curl --location 'https://api.withblast.com/projects/550e8400-e29b-41d4-a716-446655440000/benchmarks' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Customer Support Quality",
  "description": "Tests for evaluating customer support responses",
  "metadata": {
    "category": "support",
    "version": "1.0"
  }
}'
Response: 
{
  "benchmark_id": "7d9c8f90-1234-5678-9abc-def012345678",
  "name": "Customer Support Quality",
  "description": "Tests for evaluating customer support responses",
  "metadata": {
    "version": "1.0"
  },
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-23T11:30:00Z"
}

​
Step 4: Add Tests

Add test cases to your benchmark: 
import requests

# Add multiple tests
base_url = "https://api.withblast.com"
project_id = "550e8400-e29b-41d4-a716-446655440000"
benchmark_id = "7d9c8f90-1234-5678-9abc-def012345678"

headers = {
    "Authorization": "Bearer YOUR_JWT_TOKEN",
    "Content-Type": "application/json"
}

test_prompts = [
    "How do I reset my password?",
    "My order hasn't arrived yet, what should I do?",
    "Can I get a refund for a damaged product?",
    "How do I update my billing information?"
]

test_ids = []
for prompt in test_prompts:
    response = requests.post(
        f"{base_url}/projects/{project_id}/benchmarks/{benchmark_id}/tests",
        json={"prompt": prompt},
        headers=headers
    )
    test_ids.append(response.json()["test_id"])

print(f"Created {len(test_ids)} tests")

​
Step 5: Execute Tests

Run all tests in your benchmark: 
curl --location 'https://api.withblast.com/projects/550e8400-e29b-41d4-a716-446655440000/benchmarks/7d9c8f90-1234-5678-9abc-def012345678/tests/execute' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{}'
Response: 
{
  "queued_count": 4,
  "test_ids": [1234, 1235, 1236, 1237],
  "message": "Successfully queued 4 tests for execution"
}