> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbasalt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Detailed API reference for prompt operations.

## 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:

```python theme={null}
# 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:**

```python theme={null}
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).