PromptRails JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for PromptRails — the AI agent orchestration platform.

Ships as both ESM and CJS. Requires Node.js 18+ (uses native fetch).

Installation

npm install @promptrails/sdk
# or
pnpm add @promptrails/sdk

Quick Start

import { PromptRails } from "@promptrails/sdk";

const client = new PromptRails({ apiKey: "pr_key_..." });

// Execute an agent
const result = await client.agents.execute("agent-id", {
  input: { query: "Summarise this week's sales" },
});
console.log(result.output);

Error Handling

import {
  NotFoundError,
  ValidationError,
  RateLimitError,
  QuotaExceededError,
} from "@promptrails/sdk";

try {
  const result = await client.agents.execute("agent-id", { input: {} });
} catch (e) {
  if (e instanceof QuotaExceededError) {
    console.log("Execution limit reached — upgrade your plan");
  } else if (e instanceof RateLimitError) {
    console.log("Too many requests");
  } else if (e instanceof NotFoundError) {
    console.log(`Not found: ${e.message}`);
  }
}

Available Resources

| Resource | Methods | | ------------------------ | ------------------------------------------------------------------------ | | client.agents | list, get, create, update, delete, execute, listVersions, createVersion, listGuardrails, createGuardrail, listMemories, createMemory, searchMemories, deleteAllMemories | | client.prompts | list, get, create, update, delete, listVersions, createVersion | | client.executions | list, get | | client.credentials | list, get, create, update, delete, setDefault, checkConnection | | client.dataSources | list, get, create, update, delete, listVersions, createVersion, testConnection, query | | client.chat | listSessions, getSession, createSession, deleteSession, listMessages, sendMessage | | client.traces | list, getByTraceId | | client.costs | getSummary, getAgentSummary | | client.scores | list, get, create, update, delete, listConfigs, getConfig, createConfig, updateConfig, deleteConfig, aggregates | | client.mcpTools | list, get, create, update, delete | | client.approvals | list, get, decide | | client.webhookTriggers | list, get, create, update, delete | | client.mediaModels | list | | client.media | generate | | client.assets | list, get, delete, getSignedUrl | | client.a2a | getAgentCard, sendMessage, getTask, listTasks, cancelTask |

Media Studio

Generate images, speech, and video using various AI providers.

// Generate an image
const result = await client.media.generate({
  provider: "fal",
  media_type: "image",
  model: "fal-ai/flux/schnell",
  prompt: "A futuristic cityscape at sunset",
  config: { width: 1024, height: 1024 },
});
console.log(result.asset_id, result.url);

// Generate speech
const speech = await client.media.generate({
  provider: "elevenlabs",
  media_type: "speech",
  model: "eleven_multilingual_v2",
  prompt: "Hello, welcome to PromptRails!",
});

Media Models

List available media models, optionally filtered by provider or type.

const models = await client.mediaModels.list({
  provider: "fal",
  media_type: "image",
});
console.log(models.data);

Assets

Browse and manage generated media assets.

// List assets
const assets = await client.assets.list({ type: "image", page: 1, limit: 10 });

// Get a single asset
const asset = await client.assets.get("asset-id");

// Get a signed download URL
const { url } = await client.assets.getSignedUrl("asset-id");

// Delete an asset
await client.assets.delete("asset-id");

Configuration

| Option | Default | Description | | ------------ | ---------------------------- | --------------------------------- | | apiKey | required | API key | | baseUrl | https://api.promptrails.ai | API base URL | | timeout | 30000 | Request timeout (ms) | | maxRetries | 3 | Max retries on network/5xx errors |

Contributing

# Install dependencies
npm ci

# Lint
npm run lint

# Format
npm run format

# Build
npm run build

# Test
npm test

License

MIT