​
Basalt API Reference

Welcome to the Basalt API reference documentation. This section provides detailed information about the Basalt API endpoints, request formats, and response structures to help you integrate Basalt’s capabilities directly into your applications.

​
API Structure

The Basalt API is organized into several functional areas:

Prompts

Endpoints for managing and retrieving prompts, versions, and tags

Monitor

Endpoints for logging, tracing, and monitoring AI interactions

Experiments

Endpoints for creating and managing experiments

Datasets

Endpoints to interact with datasets

​
Getting Started

Before using the API, you’ll need to:
  1. Obtain an API Key: All API requests require authentication using your API key
  2. Understand Base URL: All API requests are made to https://api.getbasalt.ai
  3. Review Authentication: See our Authentication guide for details on how to use your API key

​
Using the API

The Basalt API follows RESTful principles with these standard conventions:
  • All requests and responses use JSON format
  • HTTP status codes indicate success or failure of requests
  • Error responses include a consistent structure with error details
  • Rate limits apply to protect the stability of the service

​
Example Request

curl https://api.getbasalt.ai/prompts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "welcome-message",
    "tag": "production"
  }'

​
API vs SDK

While the API gives you direct access to Basalt’s capabilities, we also offer SDKs for TypeScript/JavaScript and Python that provide a more convenient, language-specific interface.

API Benefits

  • Direct access to all Basalt features
  • Language-agnostic integration
  • Fine-grained control over requests and responses
  • Useful for custom integrations and platforms

SDK Benefits

  • Higher-level abstractions
  • Type safety and autocomplete
  • Built-in error handling
  • Automatic retries and caching
  • Simplified authentication
For most use cases, we recommend using our SDKs, but the API is available for scenarios where direct access is preferred.

​
Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests:
  • 2xx codes indicate success
  • 4xx codes indicate client errors (invalid requests)
  • 5xx codes indicate server errors

​
Next Steps

Explore the API reference documentation for each endpoint: