Skip to main content

​
List Prompts

basalt.prompts.list_sync(feature_slug=None) / await basalt.prompts.list(feature_slug=None) Lists all prompts accessible to your API key. Description: Use this to discover prompts, show them in internal tools, or drive admin UIs. Parameters:
  • feature_slug (str, optional): Filter prompts by feature slug.
Returns: A list of prompt metadata objects. Each prompt object has:
  • slug (str): Unique identifier.
  • name (str): Human-readable name.
  • status (str): Status of the prompt.
  • description (str): Human-readable description.
  • available_versions (list[str]): All available version numbers.
  • available_tags (list[str]): Tags pointing to versions (e.g. ["production", "latest"]).

​
Get Prompt

basalt.prompts.get_sync(slug, version=None, tag=None, variables=None, cache_enabled=True)
await basalt.prompts.get(slug, version=None, tag=None, variables=None, cache_enabled=True) Retrieves a specific prompt with its full content and configuration. Returns a context manager wrapper around the Prompt object. Description: Use this when you need the actual prompt text and model configuration to send to an LLM. The returned object can be used directly or as a context manager to scope tracing to the prompt. Parameters:
  • slug (str, required): Prompt identifier.
  • version (str, optional): Specific version number (e.g. "1.2.0").
    Use this for pinning in tests or for reproducing historical behavior.
  • tag (str, optional): Tag to resolve (e.g. "latest", "production").
    Use this to decouple your code from concrete version numbers.
  • variables (dict, optional): Variables for Jinja2 substitution inside the prompt text.
  • cache_enabled (bool, optional, default=True): Enable or disable caching for this request.
Exactly one of tag or version should usually be provided. If both are omitted, the SDK defaults to the latest version. Returns: A PromptContextManager (or AsyncPromptContextManager for async) wrapping the Prompt object. Can be used as: 
# Imperative: access prompt directly
prompt = basalt.prompts.get_sync("slug")
print(prompt.text)

# Context manager: scope tracing to the prompt
with basalt.prompts.get_sync("slug") as prompt:
    response = llm.generate(prompt.text)
The Prompt object itself has:
  • slug (str): Prompt identifier.
  • version (str): Resolved version number (e.g. "1.2.0").
  • tag (str, optional): Tag that was resolved.
  • text (str): Final prompt text (after substitution if variables were provided).
  • raw_text (str): Original template text (before variable substitution).
  • system_text (str, optional): System/instruction text (after variable substitution).
  • raw_system_text (str, optional): Original system template text.
  • model.provider (str): e.g. "openai", "anthropic".
  • model.model (str): e.g. "gpt-4", "claude-3-opus".
  • model.version (str): Model version.
  • model.parameters.temperature (float): Sampling temperature.
  • model.parameters.max_length (int): Maximum completion tokens.
  • model.parameters.top_p (float): Nucleus sampling parameter.
  • model.parameters.top_k (float, optional): Top-k sampling parameter.
  • model.parameters.frequency_penalty (float, optional): Frequency penalty.
  • model.parameters.presence_penalty (float, optional): Presence penalty.
  • model.parameters.response_format (str): Response format (e.g., "text", "json").
  • model.parameters.json_object (dict, optional): JSON schema for structured output.
  • model.parameters.tools (PromptTools, optional): Function/tool definitions for function-calling.
  • tools (PromptTools, optional): Shorthand for model.parameters.tools.
  • variables (dict, optional): Variables that were used in compilation.

​
Describe Prompt

basalt.prompts.describe_sync(slug, version=None, tag=None)
await basalt.prompts.describe(slug, version=None, tag=None) Gets metadata about a prompt, including available versions and tags, without fetching the full prompt text. Description: Use this for admin tooling, dashboards, or CLI commands that need to inspect the lifecycle of a prompt. Parameters:
  • slug (str, required): Prompt identifier.
  • version (str, optional): Specific version to describe (optional).
  • tag (str, optional): Tag to describe (optional).
Returns:
  • slug (str): Prompt identifier.
  • name (str): Human-readable name.
  • status (str): Status of the prompt.
  • description (str): Human-readable description.
  • available_versions (list[str]): All known versions for this prompt.
  • available_tags (list[str]): Tags currently pointing to versions (e.g. ["production", "staging", "latest"]).
  • variables (list[dict[str, str]]): Variables defined in the prompt template.

​
Publish Prompt

basalt.prompts.publish_sync(slug, new_tag, version=None, tag=None)
await basalt.prompts.publish(slug, new_tag, version=None, tag=None) Assigns or updates tags for prompt versions. Description: Use this to control which version a tag (such as production or staging) points to.
This is the core mechanism for rolling out, promoting, or rolling back prompt changes. Parameters:
  • slug (str, required): Prompt identifier.
  • new_tag (str, required): Tag to assign or move (e.g. "production", "staging").
  • version (str, optional): Version to tag (e.g. "1.3.0").
  • tag (str, optional): Existing tag to publish from (e.g. resolve the version from an existing tag, then tag it).
Either version or tag should be provided to identify which version to tag. Returns:
  • id (str): The deployment tag ID.
  • label (str): The label/tag name that was assigned.

​
Exceptions

The following exceptions can be raised by any of the methods above: API Errors (all inherit from BasaltAPIError):
  • NotFoundError: The prompt, tag, or version does not exist (HTTP 404).
  • UnauthorizedError: The API key is missing, invalid, or lacks permissions (HTTP 401).
  • BadRequestError: Invalid request parameters or validation failure (HTTP 400).
  • ForbiddenError: API key is valid but lacks permissions for this resource (HTTP 403).
  • BasaltAPIError: Other API-level errors (server errors, etc.). Use .status_code to check HTTP status.
Connection Errors:
  • NetworkError: Network connectivity issues when calling the Basalt API (timeouts, connection refused, etc.).
Base Exception:
  • BasaltError: Base class for all Basalt SDK errors.
Example: 
from basalt.types.exceptions import NotFoundError, UnauthorizedError, NetworkError

try:
    prompt = basalt.prompts.get_sync("my-prompt", version="1.0.0")
except NotFoundError:
    print("Prompt or version does not exist")
except UnauthorizedError:
    print("Invalid or missing API key")
except NetworkError:
    print("Network error - check connectivity")
    # Could retry or use fallback
Wrap calls in try/except blocks to implement appropriate fallbacks (e.g. default prompts, safe error responses, or retries).