Skip to main content
This guide walks you through installing the SDK, authenticating, and making your first API call.

​
Step 1: Install the SDK

npm install @nimblebrain/sdk

​
Step 2: Get Your API Key

  1. Log in to NimbleBrain Studio
  2. Go to Settings > API Keys
  3. Click Create API Key
  4. Copy the key (starts with nb_live_)
Store your API key in an environment variable like NIMBLEBRAIN_API_KEY to keep it out of your code.

​
Step 3: Initialize the SDK

import { NimbleBrain } from '@nimblebrain/sdk';

const nb = new NimbleBrain({
  apiKey: process.env.NIMBLEBRAIN_API_KEY || 'nb_live_xxxxx',
});

​
Configuration Options

const nb = new NimbleBrain({
  apiKey: 'nb_live_xxxxx',           // Required
  baseUrl: 'https://studio-api.nimblebrain.ai', // Optional (this is the default)
});

​
Step 4: Make Your First API Call

​
List Your Playbooks

const playbooks = await nb.playbooks.list();

console.log('Your playbooks:');
for (const playbook of playbooks) {
  console.log(`- ${playbook.name} (${playbook.id})`);
}

​
Step 5: Chat with Nira

The most common use case is having a conversation with Nira: 
// Create a new conversation
const conversation = await nb.nira.conversations.create('My First Chat');
console.log(`Created conversation: ${conversation.id}`);

// Send a message and stream the response
console.log('\nNira response:');
for await (const event of nb.nira.messages.stream(conversation.id, 'Hello! What can you help me with?')) {
  if (event.type === 'content') {
    process.stdout.write(event.data.text as string);
  }
}
console.log('\n');

​
Step 6: Execute a Playbook

Run a playbook and wait for the result: 
// Get the first playbook
const playbooks = await nb.playbooks.list();
const playbook = playbooks[0];

// Execute the playbook
console.log(`Executing playbook: ${playbook.name}`);
const { id: executionId } = await nb.playbooks.execute(playbook.id);

// Wait for completion
const execution = await nb.executions.waitForCompletion(executionId, {
  timeoutMs: 120000,  // 2 minutes
  pollIntervalMs: 2000, // Check every 2 seconds
});

console.log(`Status: ${execution.status}`);
console.log(`Result: ${execution.result}`);

​
Complete Example

Here’s a complete example that ties everything together: 
import { NimbleBrain } from '@nimblebrain/sdk';

async function main() {
  // Initialize
  const nb = new NimbleBrain({
    apiKey: process.env.NIMBLEBRAIN_API_KEY!,
  });

  try {
    // List available playbooks
    const playbooks = await nb.playbooks.list();
    console.log(`Found ${playbooks.length} playbooks`);

    // Chat with Nira
    console.log('\nStarting conversation with Nira...');
    const conversation = await nb.nira.conversations.create('SDK Demo');

    // Stream the response
    process.stdout.write('\nNira: ');
    for await (const event of nb.nira.messages.stream(
      conversation.id,
      'Hello! Give me a brief introduction of what you can help me with.'
    )) {
      if (event.type === 'content') {
        process.stdout.write(event.data.text as string);
      }
    }
    console.log('\n');

  } catch (error) {
    console.error('Error:', error);
  }
}

main();

​
Error Handling

Always wrap API calls in try-catch blocks: 
try {
  const playbooks = await nb.playbooks.list();
} catch (error) {
  if (error instanceof Error) {
    console.error('API error:', error.message);
  }
}
Common errors:
  • 401 Unauthorized: Invalid or expired API key
  • 403 Forbidden: API key doesn’t have access to this workspace
  • 404 Not Found: Conversation or playbook doesn’t exist
  • 429 Too Many Requests: Rate limit exceeded

​
Next Steps

Nira API

Deep dive into chatting with Nira

Playbooks API

Execute and monitor playbooks

Streaming

Build real-time chat interfaces

API Reference

Full REST API documentation