Documentation

Introduction

Build and operate Paladin voice AI agents programmatically from Python or TypeScript

Paladin ships official SDKs for Python and TypeScript that wrap the Paladin REST API and the workflow builder. Use them to create or edit agents, place outbound calls, and inspect runs from your own code.

Python — paladin-sdk on PyPI
TypeScript — @paladin/sdk on npm

Both packages are generated from the same backend OpenAPI spec, so the method surface is equivalent — only the naming convention differs (snake_case in Python, camelCase in TypeScript).

Install#

Python

pip install paladin-sdk

TypeScript

npm install @paladin/sdk

Authenticate#

Generate an API key from /api-keys in your Paladin dashboard. See API Keys for details.

Both SDKs read the API key from the PALADIN_API_KEY environment variable by default, and the base URL from PALADIN_API_URL. You can also pass them explicitly.

Python

from paladin_sdk import PaladinClient

client = PaladinClient(
    base_url="https://paladin.northmanngrp.com",
    api_key="YOUR_API_KEY",
)

TypeScript

import { PaladinClient } from "@paladin/sdk";

const client = new PaladinClient({
    baseUrl: "https://paladin.northmanngrp.com",
    apiKey: "YOUR_API_KEY",
});

Quick tour#

List the agents in your workspace:

Python

workflows = client.list_workflows()
for wf in workflows:
    print(wf.id, wf.name)

TypeScript

const workflows = await client.listWorkflows();
for (const wf of workflows) {
    console.log(wf.id, wf.name);
}

Next steps#

Build an agent — assemble nodes and edges, save as a draft
Place an outbound call — trigger a call from an agent to a phone number
MCP Server — let Claude and other coding agents drive the SDK for you

When to use the SDKs#

Use the SDKs when your backend needs to create, update, list, or run Paladin agents from application code.
Use direct dashboard workflows first when a non-technical user needs to manage prompts, nodes, or telephony settings.
Keep API keys on the server side and pass only your own application state to the client.

Typical integration flow#

Create or identify the agent in Paladin.
Generate an API key in the dashboard and store it securely.
Configure the SDK base URL for the Paladin app environment you are calling.
Run a small list/get request before creating calls or campaigns from code.