Quick Start

Get Raison running in your application in under 5 minutes.

Prerequisites

Node.js 18 or later
npm, pnpm, or yarn
A Raison account at raison.ist

1. Get Your API Key

Sign in at raison.ist.
If this is your first login, you will be prompted to create an organization — give it a name and continue.
Create a project (or open an existing one).
Go to API Keys.
Click New, select the environment (start with Development), and give it a label.
Copy the key — it starts with rsn_ and is shown only once.

Your API key is tied to one project and one environment. To connect to Production, create a separate key for the Production environment.

2. Create and Deploy a Prompt

Go to Agents in the left sidebar.
Open an agent (or use the Default Agent that comes with your project).
Click on a prompt (e.g. System Prompt), or click + New Prompt to create one.
Write your prompt content. You can use variables with Handlebars syntax, e.g. {{company_name}}.
Click Edit as new draft in the History panel on the right (or edit the existing draft).
Click Deploy to Development in the History panel.
Copy the prompt ID from the top of the prompt detail view (click IDs).

Your prompt must be deployed to the same environment as your API key. If your key is for Development, make sure the prompt is deployed to Development.

3. Install

npm install raison

4. Connect and Use

import { Raison } from 'raison'

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

// Render a prompt with variables
// Copy the prompt ID from the dashboard: Prompts > click a prompt > copy ID
const message = await raison.render('YOUR_PROMPT_ID', {
  userName: 'Alice',
  context: 'billing inquiry',
})

// Query all prompts deployed to this environment
const allPrompts = await raison.find()

// Find a single prompt by name
const systemPrompt = await raison.findOne({ name: 'system-prompt' })

// Disconnect when your process exits
raison.disconnect()

The SDK connects via WebSocket, receives all deployed prompts for the environment in the initial sync, and keeps them updated in real-time. Every method (render, find, findOne) waits for the initial sync before returning — there are no race conditions to handle.

What Happens After Connection

After new Raison({ apiKey }):

A WebSocket connection is opened to api.raison.ist/sdk.
The server sends a sync event with all prompts currently deployed to your environment.
Prompts are stored in an in-memory database on your side.
The SDK is now ready — all methods resolve immediately from memory.
When you deploy a prompt update in the dashboard, the SDK receives a prompt:deployed event and updates its local copy. Your next call to render or find returns the new content.

Where to Find Prompt IDs

In the Raison dashboard:

Open your project.
Go to Agents and open an agent.
Click on a prompt.
The prompt ID is displayed at the top of the prompt detail view — click to copy.

Prompt IDs are stable across versions and environments. The same ID works in Development, Staging, and Production.

Next Steps

SDK Guide — How the SDK works internally, error handling, and patterns
Concepts — Understand the prompt lifecycle in depth
Templating — Full Handlebars guide for writing prompts
Examples — Anthropic/Claude, Next.js, multi-environment patterns

Introduction

Organizations