Raison SDK

Raison is a prompt management platform. Prompts live in the dashboard at raison.ist with full version history and are delivered to applications via real-time WebSocket sync — no redeployments needed when prompts change.

Key concepts: Organization → Project → Agent → Prompt. Each project has Development/Staging/Production environments, each with its own rsn_ API key.

Installation

npm install raison

Connect and Use

import { Raison } from "raison";

const raison = new Raison({ apiKey: process.env.RAISON_API_KEY }); // rsn_...

// Render a prompt with variables (Handlebars template)
const message = await raison.render("PROMPT_ID", { userName: "Alice" });

// Query all prompts in this environment
const all = await raison.find();

// Find by agent + name (most efficient — uses composite index)
const systemPrompt = await raison.findOne({ agentId: "AGENT_ID", name: "system-prompt" });

// Shutdown
raison.disconnect();

All methods (render, find, findOne) await the initial WebSocket sync automatically — no race conditions, no manual readiness checks.

Core Methods

Finding IDs

• Prompt ID — Dashboard: open project → click agent → click prompt → copy ID at top
• Agent ID — Dashboard: open project → click agent → copy ID at top
• IDs are stable across environments (same ID works in Dev/Staging/Prod)

Error Handling Pattern

const prompt = await raison.render("PROMPT_ID", variables);
if (!prompt) {
  return FALLBACK_SYSTEM_PROMPT; // render() returns "" for missing prompts
}

References

• sdk-reference.md — Full API reference: constructor options, method signatures, types, and error behavior table. Read when you need precise signatures, TypeScript types, or to check all error cases.

• templating.md — Handlebars guide: variables, nested objects, {{#if}}, {{#each}}, custom helpers with code examples. Read when writing or debugging prompt templates.

• examples.md — Integration patterns: Anthropic/Claude, OpenAI, Express.js, Next.js serverless singleton, multiple environments, graceful shutdown. Read when integrating Raison into a specific framework or setting up a production pattern.