Skip to Content
Core Concepts

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 .