Configuration

The SDK needs four pieces of information to fetch a prompt:

Argument	Required	Description
api_key	Yes	Identifies who is calling. Created in the console.
project_id	Yes	The project the prompt lives under.
environment	Yes	The runtime environment of this code — e.g. "development".
base_url	On-prem only	The URL of your on-prem deployment.

This page walks through where each value comes from, and the recommended way to load them.

1. Create an API key

SaaS

1. Sign in to [instruction-manager.elsai.ai](https://instruction-manager.elsai.ai/)
2. Open API Keys in the sidebar.
3. Click Create key, give it a name (e.g. prod-api), and copy the key.

On-Prem

1. Sign in to your on-prem console (the URL your team gave you).
2. Open API Keys in the sidebar.
3. Click Create key and give it a name.

WARNING

The plaintext key is shown once at creation. Store it somewhere safe immediately — the platform stores only a hash and cannot retrieve it later.

On-prem: Keys are bound to you (the creating user) — at SDK call time, access to a project is decided by checking whether you're a current member of that project's organization. A single key works across every organization you belong to. See Authentication for the full model.

2. Find your project ID

In the console, open the project you want to read prompts from. The project ID is in the URL:

https://instruction-manager.elsai.ai/projects/c8bcaabe-b577-49a4-85da-e37d67652d0c
                                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                                this is your PROJECT_ID

You can also copy it from the project settings page.

3. Decide your environment

environment is a label for the runtime where the code you're writing is running — not the prompt's environment. Common values:

• "development" — local development, feature branches
• "testing" — CI, staging
• "production" — customer-facing deploys

The SDK uses this to decide whether the active prompt version has been released to your environment. If the prompt's active version isn't released to "production", a production call will raise PromptNotReleasedInEnvironmentError instead of silently serving a not-yet-approved prompt. See Environments for the full lifecycle.

INFO

The on-prem backend does strict string matching on environment names against the version's release tags. If your version is tagged ["development", "test"] and your SDK is initialized with environment="testing", that's a miss — the strings don't match. Settle on canonical names early (we recommend development / testing / production).

4. Wire credentials into your app

Hardcoding credentials in source is unsafe. Use a .env file plus python-dotenv:

Step 1 — Install python-dotenv

pip install python-dotenv

Step 2 — Create a .env file

SaaS (.env)

ELSAI_API_KEY=elsai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELSAI_PROJECT_ID=c8bcaabe-b577-49a4-85da-e37d67652d0c
ELSAI_ENVIRONMENT=development

On-Prem (.env)

ELSAI_API_KEY=elsai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELSAI_PROJECT_ID=c8bcaabe-b577-49a4-85da-e37d67652d0c
ELSAI_ENVIRONMENT=development
PROMPT_MANAGER_API_URL=https://prompts.your-company.com

Add .env to your .gitignore.

Step 3 — Load it at app start

import os
from dotenv import load_dotenv
from elsai_prompts.prompt_manager import PromptManager

load_dotenv()

pm = PromptManager(
    api_key=os.environ["ELSAI_API_KEY"],
    project_id=os.environ["ELSAI_PROJECT_ID"],
    environment=os.environ["ELSAI_ENVIRONMENT"],
    # base_url=os.environ.get("PROMPT_MANAGER_API_URL"),   # on-prem only
)

On-prem: setting base_url

On-prem deployments don't have a hardcoded URL — you must tell the SDK where your instance lives. Two equivalent ways:

# Constructor argument
pm = PromptManager(
    api_key=...,
    project_id=...,
    environment="development",
    base_url="https://prompts.your-company.com",
)

# Environment variable  (PROMPT_MANAGER_API_URL=https://prompts.your-company.com)
pm = PromptManager(
    api_key=...,
    project_id=...,
    environment="development",
)

If both are set, the constructor argument wins. If neither is set, the SDK raises ValueError immediately — fail fast.

Reusing a client

PromptManager is cheap to construct but has no internal state worth sharing between requests. Best pattern: construct one per process at startup, pass it around as a dependency.

# app/deps.py
pm = PromptManager(...)

# app/routes.py
from app.deps import pm

@app.get("/welcome")
def welcome():
    prompt = pm.get_active_prompt_version("welcome_email")
    return prompt.render({"name": "Ada"})