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
| Method |
Returns |
Notes |
render(id, vars?) |
Promise<string> |
Returns "" if not found; raw content if no vars |
find(params?) |
Promise<Prompt[]> |
Returns [] if no match |
findOne(params) |
Promise<Prompt | null> |
Returns null if no match |
disconnect() |
void |
Call on process shutdown |
Raison.registerHelper(name, fn) |
void |
Global Handlebars helper; register at startup |
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.
1---2name: raison-sdk3description: Raison JavaScript/TypeScript prompt management SDK. Use when working with the `raison` npm package to render templates or query prompt data.4---56# Raison SDK78Raison 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.910**Key concepts:** Organization → Project → Agent → Prompt. Each project has Development/Staging/Production environments, each with its own `rsn_` API key.1112## Installation1314```bash15npm install raison16```1718## Connect and Use1920```typescript21import { Raison } from "raison";2223const raison = new Raison({ apiKey: process.env.RAISON_API_KEY }); // rsn_...2425// Render a prompt with variables (Handlebars template)26const message = await raison.render("PROMPT_ID", { userName: "Alice" });2728// Query all prompts in this environment29const all = await raison.find();3031// Find by agent + name (most efficient — uses composite index)32const systemPrompt = await raison.findOne({ agentId: "AGENT_ID", name: "system-prompt" });3334// Shutdown35raison.disconnect();36```3738All methods (`render`, `find`, `findOne`) await the initial WebSocket sync automatically — no race conditions, no manual readiness checks.3940## Core Methods4142| Method | Returns | Notes |43|---|---|---|44| `render(id, vars?)` | `Promise<string>` | Returns `""` if not found; raw content if no vars |45| `find(params?)` | `Promise<Prompt[]>` | Returns `[]` if no match |46| `findOne(params)` | `Promise<Prompt \| null>` | Returns `null` if no match |47| `disconnect()` | `void` | Call on process shutdown |48| `Raison.registerHelper(name, fn)` | `void` | Global Handlebars helper; register at startup |4950## Finding IDs5152- **Prompt ID** — Dashboard: open project → click agent → click prompt → copy ID at top53- **Agent ID** — Dashboard: open project → click agent → copy ID at top54- IDs are stable across environments (same ID works in Dev/Staging/Prod)5556## Error Handling Pattern5758```typescript59const prompt = await raison.render("PROMPT_ID", variables);60if (!prompt) {61 return FALLBACK_SYSTEM_PROMPT; // render() returns "" for missing prompts62}63```6465## References6667- **[sdk-reference.md](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.6869- **[templating.md](references/templating.md)** — Handlebars guide: variables, nested objects, `{{#if}}`, `{{#each}}`, custom helpers with code examples. Read when writing or debugging prompt templates.7071- **[examples.md](references/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.
aksuharun