Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Configure the SDK

Set the Haystack Platform API key, API URL, and default workspace to use with the SDK.

About This Task​

info

When using the Haystack Enterprise SDK on Windows, if haystack-enterprise isn't on your PATH, replace it with python -m haystack_enterprise_sdk.cli, for example:

haystack-enterprise validate pipeline.py

becomes

python -m haystack_enterprise_sdk.cli validate pipeline.py

The SDK reads these settings:

VariableWhat it isDefaultRequired
API_KEYYour Haystack Enterprise Platform API key.NoneYes
API_URLBase URL of the platform API. A trailing version segment (/api/v1, /v2) is stripped, so pasting a full URL works.https://api.cloud.deepset.aiNo
DEFAULT_WORKSPACE_NAMEHaystack Platform workspace used when a command takes no --workspace-name.None (login suggests default)No
ASYNC_CLIENT_TIMEOUTTimeout in seconds for the async client.300No

Where Settings Come From​

The SDK resolves each setting separately, in this order. The first source that supplies a value takes precedence:

  1. Explicit arguments: a CLI flag such as --workspace-name, or a parameter passed in Python.
  2. Environment variables set in your shell.
  3. A local .env in the directory you run the command from.
  4. The global ~/.haystack-enterprise/.env written by login.
  5. Built-in defaults, where a setting has one.

Because each setting resolves on its own, a local .env doesn't replace the global one. Any key you leave out of the local file still comes from the global file. This means a project can override just the workspace in its own .env and keep using the API key from login.

If a local .env exists when you run login, the CLI warns you that the local file takes precedence over the global file it's about to write.

Prerequisites​

  • Haystack Platform API key. You can get an API key from API Keys in Haystack Enterprise Platform. For more on API keys, see Generate an API Key.
  • Haystack Platform API URL. The base URL of the Haystack Platform API. The default is https://api.cloud.deepset.ai.
  • Haystack Platform workspace name. The default workspace name is default.

Configure the SDK With the CLI​

Log In​

  1. Run the following command to log in:

    haystack-enterprise login

  2. When prompted, enter your API key, API URL, and the name of the workspace you want to set as default for all operations.

Running the login command creates a global configuration file at ~/.haystack-enterprise/.env that stores the API key, API URL, and default workspace name.

Log Out​

Logging out deletes the global configuration file. To do this, run:

haystack-enterprise logout

Configure the SDK With the Python API​

Pass credentials directly:

from haystack_enterprise_sdk import PipelineClient

client = PipelineClient(api_key="...", api_url="https://api.cloud.deepset.ai")

If you omit them, the same cascade applies.

Use a Different Environment​

To point at a non-production environment, set API_URL in your shell, in a local .env, or by answering n to the URL question during login:

export API_URL=https://api.dev.cloud.dpst.dev

Examples​

login is interactive and has no flags. To change the saved defaults, run login again or edit ~/.haystack-enterprise/.env. To override settings for one command, pass a flag or set an environment variable.

  • Override the workspace for one command:
haystack-enterprise validate pipeline.py --workspace-name my-workspace
  • Set the API key, API URL, and workspace in your shell:
export API_KEY=my-api-key
export API_URL=https://api.dev.cloud.dpst.dev
export DEFAULT_WORKSPACE_NAME=my-workspace

What To Do Next​

  • Check the SDK version installed: 
    haystack-enterprise --version