Python SDK

enprompta

Async-first Python SDK with httpx, pydantic models, and comprehensive type hints.

Async First

Built on httpx for async/await support.

Type Hints

Full type annotations for IDE support.

Pydantic

Data validation with pydantic models.

Subscription Required

The SDK requires an API key from a Pro, Team, or Enterprise subscription. Free tier users cannot access the API programmatically. View pricing →

Requirements: Python 3.8+ | httpx 0.25+ | pydantic 2.0+

Installation

pip

pip install enprompta

poetry

poetry add enprompta

pipenv

pipenv install enprompta

Quick Start

Python (async)

import asyncio
from enprompta import Enprompta

async def main():
    # Initialize with API key
    client = Enprompta(api_key="ep_your_api_key")

    # Or with OAuth2 credentials
    client = Enprompta(
        client_id="your_client_id",
        client_secret="your_client_secret"
    )

    # List all prompts
    prompts = await client.prompts.list()
    for prompt in prompts.data:
        print(prompt.title)

    # Create a new prompt
    prompt = await client.prompts.create(
        title="Email Assistant",
        content="Write a professional email about {{topic}} to {{recipient}}",
        visibility="PRIVATE",
        variables=[
            {"name": "topic", "type": "text", "required": True},
            {"name": "recipient", "type": "text", "required": True}
        ]
    )

    # Execute the prompt
    result = await client.prompts.execute(
        prompt.id,
        variables={
            "topic": "project deadline extension",
            "recipient": "the project manager"
        },
        provider="openai",
        model="gpt-4"
    )

    print(result.output)

# Run the async function
asyncio.run(main())

Authentication

The SDK supports both API key and OAuth2 client credentials authentication.

API Key Authentication

import os
from enprompta import Enprompta

client = Enprompta(
    api_key=os.environ["ENPROMPTA_API_KEY"],
    # Optional: custom base URL
    base_url="https://enprompta.com/api/v1"
)

OAuth2 Client Credentials

from enprompta import Enprompta

client = Enprompta(
    client_id="your_client_id",
    client_secret="your_client_secret",
    scopes=["prompts:read", "prompts:write", "executions:write"]
)

# Tokens are automatically managed and refreshed

Environment Variables

# The SDK automatically reads these environment variables:
# ENPROMPTA_API_KEY
# ENPROMPTA_CLIENT_ID
# ENPROMPTA_CLIENT_SECRET
# ENPROMPTA_BASE_URL

from enprompta import Enprompta

# No arguments needed if env vars are set
client = Enprompta()

Working with Prompts

List Prompts

# List with pagination
response = await client.prompts.list(
    limit=20,
    visibility="PRIVATE",
    search="email"
)

for prompt in response.data:
    print(f"{prompt.id}: {prompt.title}")

# Check for more pages
if response.pagination.has_more:
    next_page = await client.prompts.list(
        cursor=response.pagination.next_cursor
    )

# Iterate through all prompts (auto-pagination)
async for prompt in client.prompts.list_all():
    print(prompt.title)

Create Prompt

prompt = await client.prompts.create(
    title="Code Reviewer",
    content="""Review the following {{language}} code and provide feedback:

```{{language}}
{{code}}
```

Focus on: {{focus_areas}}""",
    description="AI-powered code review assistant",
    category="development",
    tags=["code", "review", "development"],
    visibility="TEAM",
    team_id="team_abc123",
    variables=[
        {
            "name": "language",
            "type": "select",
            "options": ["javascript", "python", "go"]
        },
        {
            "name": "code",
            "type": "text",
            "required": True
        },
        {
            "name": "focus_areas",
            "type": "text",
            "default_value": "best practices, performance"
        }
    ]
)

print(f"Created prompt: {prompt.id}")

Update and Delete

# Update a prompt
updated = await client.prompts.update(
    "prompt_abc123",
    title="Updated Title",
    content="New prompt content with {{variable}}",
    visibility="PUBLIC"
)

# Delete a prompt
await client.prompts.delete("prompt_abc123")

Executions

Execute a Prompt

result = await client.prompts.execute(
    "prompt_abc123",
    variables={
        "topic": "quarterly review",
        "tone": "professional"
    },
    provider="openai",
    model="gpt-4-turbo",
    temperature=0.7,
    max_tokens=1000
)

print(result.output)           # Generated text
print(result.tokens_used)      # Token count
print(result.cost)             # Estimated cost
print(result.latency_ms)       # Response time

List Executions

# Get execution history
executions = await client.executions.list(
    prompt_id="prompt_abc123",
    provider="openai",
    start_date="2024-01-01",
    end_date="2024-01-31"
)

for execution in executions.data:
    print(f"{execution.id}: {execution.tokens_used} tokens")

# Get aggregated statistics
stats = await client.executions.get_stats(group_by="day")

Teams

# List teams
teams = await client.teams.list()
for team in teams.data:
    print(f"{team.id}: {team.name}")

# Create a team
team = await client.teams.create(
    name="Engineering",
    description="Engineering team prompts"
)

# Get team details
team = await client.teams.get("team_abc123")

# Update team
await client.teams.update(
    "team_abc123",
    name="Engineering Team"
)

Webhooks

# Create a webhook
webhook = await client.webhooks.create(
    name="Slack Notifications",
    url="https://your-server.com/webhooks/enprompta",
    events=[
        "prompt.created",
        "prompt.updated",
        "execution.completed"
    ],
    secret="whsec_your_webhook_secret"
)

# List webhooks
webhooks = await client.webhooks.list()

# Get delivery history
deliveries = await client.webhooks.get_deliveries("webhook_abc123")

Verifying Webhook Signatures

from enprompta.webhooks import verify_signature

# In your webhook handler (e.g., FastAPI)
@app.post("/webhooks/enprompta")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-Enprompta-Signature")

    if not verify_signature(payload, signature, webhook_secret):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = json.loads(payload)
    print(f"Received event: {event['event']}")

    return {"status": "ok"}

Error Handling

The SDK provides typed exception classes for different failure scenarios.

from enprompta.exceptions import (
    EnpromptaError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    NotFoundError,
    NetworkError,
    TimeoutError
)

try:
    await client.prompts.get("invalid_id")
except NotFoundError:
    print("Prompt not found")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Validation errors: {e.errors}")
except NetworkError as e:
    print(f"Network error: {e}")
except TimeoutError:
    print("Request timed out")
except EnpromptaError as e:
    print(f"API error {e.code}: {e.message}")

Synchronous Client

For non-async code, use the synchronous client wrapper.

from enprompta import EnpromptaSync

# Synchronous client
client = EnpromptaSync(api_key="ep_your_api_key")

# All methods work without await
prompts = client.prompts.list()
for prompt in prompts.data:
    print(prompt.title)

prompt = client.prompts.create(
    title="My Prompt",
    content="Hello {{name}}"
)

result = client.prompts.execute(
    prompt.id,
    variables={"name": "World"},
    provider="openai",
    model="gpt-4"
)

print(result.output)

Context Manager

Use the client as a context manager to ensure proper cleanup.

# Async context manager
async with Enprompta(api_key="ep_your_api_key") as client:
    prompts = await client.prompts.list()
    # Client is automatically closed after the block

# Sync context manager
with EnpromptaSync(api_key="ep_your_api_key") as client:
    prompts = client.prompts.list()
    # Client is automatically closed after the block

Next Steps

TypeScript SDK API Reference