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

# Examples

> Code examples for using prompts.

## Listing Prompts

Use listing to discover available prompts, check their descriptions, and see which tags and versions exist.

### Basic Listing (sync)

```python theme={null}
from basalt import Basalt

basalt = Basalt(api_key="your-api-key")

# List all prompts
response = basalt.prompts.list_sync()

print(f"Total prompts: {response.total}")
print(f"Prompts returned: {len(response.prompts)}")

for prompt in response.prompts:
    print(f"\nSlug: {prompt.slug}")
    print(f"  Description: {prompt.description}")
    print(f"  Latest version: {prompt.latest_version}")
    print(f"  Tags: {', '.join(prompt.tags)}")

basalt.shutdown()
```

### Basic Listing (async)

```python theme={null}
import asyncio
from basalt import Basalt

async def list_prompts_async():
    basalt = Basalt(api_key="your-api-key")
    response = await basalt.prompts.list()
    for prompt in response.prompts:
        print(f"{prompt.slug}: {prompt.description}")
    basalt.shutdown()

# Run async function
asyncio.run(list_prompts_async())
```

## Getting Prompts

Use `get` when you want the actual prompt text and model configuration your app should use.

### Get Latest Version

```python theme={null}
from basalt import Basalt

basalt = Basalt(api_key="your-api-key")

# Get the latest version (usually used in dev environments)
prompt = basalt.prompts.get_sync(
    slug="customer-greeting",
    tag="latest",
)

print(f"Prompt text: {prompt.text}")
print(f"Model: {prompt.model.provider}/{prompt.model.model}")
print(f"Version: {prompt.version}")

basalt.shutdown()
```

### Get Specific Version

```python theme={null}
# Get a specific version by version number
prompt = basalt.prompts.get_sync(
    slug="customer-greeting",
    version="1.2.0",
)

print(f"Retrieved version: {prompt.version}")
```

### Get by Tag (environments)

Tags are ideal for mapping prompts to environments such as `production` and `staging` without changing your code.

```python theme={null}
# Get by environment tag
production_prompt = basalt.prompts.get_sync(
    slug="customer-greeting",
    tag="production",
)

staging_prompt = basalt.prompts.get_sync(
    slug="customer-greeting",
    tag="staging",
)
```

You can point `staging` to a new version first, test it, then move the `production` tag to that same version once you’re confident.

## Variable Substitution

Inject runtime data into your prompts using variables.

### Simple Variable Example

```python theme={null}
from basalt import Basalt

basalt = Basalt(api_key="your-api-key")

# Prompt in Basalt platform:
# "Hello {{ customer_name }}, welcome to {{ product_name }}!"

prompt = basalt.prompts.get_sync(
    slug="welcome-message",
    tag="latest",
    variables={
        "customer_name": "Alice",
        "product_name": "Premium Plan",
    },
)

print(prompt.text)
# Output: "Hello Alice, welcome to Premium Plan!"

basalt.shutdown()
```

You can pass any JSON-serializable values in `variables`. Use this to personalize responses, inject context, or conditionally render parts of your prompt via Jinja2.

## Async Usage in Applications

In async frameworks (e.g. FastAPI), prefer async methods to avoid blocking the event loop.

```python theme={null}
from fastapi import FastAPI
from basalt import Basalt

app = FastAPI()
basalt = Basalt(api_key="your-api-key")

@app.get("/greet/{customer_name}")
async def greet(customer_name: str):
    prompt = await basalt.prompts.get(
        slug="welcome-message",
        tag="production",
        variables={"customer_name": customer_name},
    )
    # Use prompt.text and prompt.model with your LLM client here
    return {"prompt": prompt.text}
```

This pattern scales cleanly as you add more prompt-dependent endpoints or background tasks.