Core Concepts
This section covers the fundamental concepts for using the DataDistill API: authentication and our credit-based metering system.
Authentication
All requests to the /api/v1 gateway (excluding the public health check endpoint) must be authenticated using HTTP Basic Authentication.
- Username: Your API Key
- Password: Your API Secret (You must use the original, unhashed secret provided when you first created the key.)
You can generate and manage your API credentials from the “API Keys” section within your project settings on the DataDistill dashboard.
The Authorization header must be formatted as Basic <credentials>, where <credentials> is the Base64-encoded string of your-api-key:your-api-secret.
Authentication & Dynamic URL Examples
Python (requests)
This example demonstrates setting up credentials and dynamically building the URL for any endpoint.
import requests
import os
import json
# --- Configuration ---
# Best practice: Store credentials as environment variables
API_KEY = os.environ.get("DATADISTILL_API_KEY", "YOUR_API_KEY")
API_SECRET = os.environ.get("DATADISTILL_API_SECRET", "YOUR_API_SECRET")
# Base URL for all API v1 endpoints
BASE_URL = "https://api.datadistill.co/api/v1"
# The library handles the Base64 encoding for you.
auth_credentials = (API_KEY, API_SECRET)
# --- Dynamic Request Function ---
def make_api_request(method, endpoint_path, params=None, json_payload=None, files=None):
"""A helper function to make authenticated API requests."""
full_url = f"{BASE_URL}{endpoint_path}"
print(f"Making {method} request to: {full_url}")
try:
response = requests.request(
method,
full_url,
auth=auth_credentials,
params=params,
json=json_payload,
files=files
)
response.raise_for_status() # Raises an exception for bad status codes (4xx or 5xx)
print(f"Status Code: {response.status_code}")
# For 204 No Content, there is no body
if response.status_code != 204:
print("Response JSON:")
print(json.dumps(response.json(), indent=2))
except requests.exceptions.HTTPError as http_err:
print(f"HTTP error occurred: {http_err}")
print(f"Response body: {response.text}")
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")JavaScript (fetch)
This example shows a reusable function for making authenticated requests with dynamic URLs.
// Best practice: Store credentials securely on your server
const API_KEY = process.env.DATADISTILL_API_KEY || "YOUR_API_KEY";
const API_SECRET = process.env.DATADISTILL_API_SECRET || "YOUR_API_SECRET";
// Base URL for all API v1 endpoints
const BASE_URL = "https://api.datadistill.co/api/v1";
// Manually encode the credentials for the Authorization header
const credentials = btoa(`${API_KEY}:${API_SECRET}`);
async function makeApiRequest(method, endpointPath, body = null, isJson = true) {
const fullUrl = `${BASE_URL}${endpointPath}`;
console.log(`Making ${method} request to: ${fullUrl}`);
const headers = { 'Authorization': `Basic ${credentials}` };
const options = { method, headers };
if (body) {
if (isJson) {
headers['Content-Type'] = 'application/json';
options.body = JSON.stringify(body);
} else {
// For file uploads (FormData), don't set Content-Type; the browser will handle it.
options.body = body;
}
}
try {
const response = await fetch(fullUrl, options);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}, message: ${await response.text()}`);
}
console.log(`Status Code: ${response.status}`);
if (response.status !== 204) {
console.log('Success:', await response.json());
}
} catch (error) {
console.error('Error fetching data:', error);
}
}cURL (Command Line)
This example sets up variables for reusable, dynamic requests.
# --- Configuration ---
API_KEY="YOUR_API_KEY"
API_SECRET="YOUR_API_SECRET"
BASE_URL="https://api.datadistill.co/api/v1"
# --- Example Usage ---
# The -u flag formats the credentials and the Authorization header for you
# ENDPOINT_PATH="/api-testing/test/protected_data"
# curl -u "${API_KEY}:${API_SECRET}" "${BASE_URL}${ENDPOINT_PATH}"Metering and Credit System
API usage is metered through a credit-based system. Each request consumes credits, which are automatically debited from your account. If your balance is insufficient, the API will respond with an HTTP 402 Payment Required. You can manage your credits at https://app.datadistill.co .