Skip to main content

​
Listing Prompts

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

​
Basic Listing (sync)

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)

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

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

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

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