@iris-ai/sdk

Official Node.js/TypeScript SDK for the IRIS AI Platform.

Full access to all 27 platform resources — AI agents, workflows, leads, RAG, automations, and more.

Install

npm install @iris-ai/sdk

Quick Start

import { IRIS } from '@iris-ai/sdk';

const iris = new IRIS({
  apiKey: 'your-api-key',
  userId: 193,
});

// Chat with an agent
const response = await iris.agents.chat(11, [
  { role: 'user', content: 'Hello!' }
]);
console.log(response.message);

// Manage leads
const leads = await iris.leads.list();
await iris.leads.update(412, { status: 'Won' });

// Execute a workflow
const run = await iris.workflows.execute(5, { query: 'Analyze competitors' });

// Search with RAG
const results = await iris.rag.search(11, 'pricing strategy');

Authentication

Get your API key from the IRIS dashboard: Actions > Developer Portal.

// Option 1: Pass directly
const iris = new IRIS({ apiKey: 'your-key', userId: 193 });

// Option 2: Environment variables (.env file)
// IRIS_API_KEY=your-key
// IRIS_USER_ID=193
const iris = new IRIS({});

Environment Variables

| Variable | Description | |----------|-------------| | IRIS_API_KEY | API key (required) | | IRIS_USER_ID | Default user ID | | IRIS_ENV | production (default) or local | | IRIS_PROD_API_KEY | Production-specific API key | | IRIS_LOCAL_API_KEY | Local development API key |

Resources

All 27 resources with full CRUD operations:

Complex Resources (Custom Methods)

| Resource | Description | Key Methods | |----------|-------------|-------------| | iris.agents | AI agents | chat(), multiStep(), createFromTemplate() | | iris.chat | Chat sessions | start(), execute(), resume(), summarize() | | iris.leads | CRM leads | notes(), tags(), outreach(), enrichment() | | iris.workflows | Automation workflows | execute(), getRunStatus(), webhooks | | iris.bloqs | Content blocks | lists(), items(), upload() | | iris.rag | Vector search | index(), search(), status() | | iris.integrations | External services | execute(), types() | | iris.automations | Scheduled tasks | execute(), executeAndWait() |

Standard Resources (CRUD)

iris.profiles, iris.cloudFiles, iris.usage, iris.vapi, iris.models, iris.services, iris.tools, iris.articles, iris.schedules, iris.servisAi, iris.programs, iris.courses, iris.audio, iris.social, iris.voice, iris.videos, iris.phone, iris.pages, iris.users

Every resource inherits list(), get(), create(), update(), delete() from the base class.

Examples

Agent Chat

const iris = new IRIS({ apiKey: 'key', userId: 193 });

// Simple chat
const res = await iris.agents.chat(11, [
  { role: 'user', content: 'What are today\'s tasks?' }
]);

// Multi-step workflow
const run = await iris.agents.multiStep(11, 'Generate a marketing report');

Lead Management

// Create a lead
const lead = await iris.leads.create({
  first_name: 'Jane',
  last_name: 'Doe',
  email: '[email protected]',
  status: 'New',
});

// Add a note
await iris.leads.createNote(lead.id, { content: 'Initial call went well' });

// Get aggregation stats
const stats = await iris.leads.getAggregationStats();

Workflow Execution

// Execute and wait for completion
const run = await iris.chat.execute({
  agentId: 11,
  query: 'Analyze Q4 sales data',
});
console.log(run.output);

// Or start async and poll manually
const { workflow_execution_id } = await iris.chat.start({
  agentId: 11,
  query: 'Generate report',
});

const status = await iris.chat.getStatus(workflow_execution_id);

RAG (Vector Search)

// Index content
await iris.rag.index('Your document content here', {
  agentId: 11,
  title: 'Product Guide',
});

// Search
const results = await iris.rag.search(11, 'pricing details');

Admin Operations

// Act as a different user
const adminIris = iris.asUser(456);
const theirAgents = await adminIris.agents.list();

CLI

# Set credentials
export IRIS_API_KEY=your-key
export IRIS_USER_ID=193

# Test connection
npx @iris-ai/sdk test-connection

# Agents
npx @iris-ai/sdk agents list
npx @iris-ai/sdk agents get 11
npx @iris-ai/sdk agents chat 11 "Hello!"

# Leads
npx @iris-ai/sdk leads list
npx @iris-ai/sdk leads search "acme"

# Workflows
npx @iris-ai/sdk workflows list
npx @iris-ai/sdk workflows execute 5 --query "Analyze data"

# Models
npx @iris-ai/sdk models

Error Handling

import { IRIS, AuthenticationError, RateLimitError, ValidationError } from '@iris-ai/sdk';

try {
  await iris.agents.chat(11, messages);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401/403 — invalid or expired token
  } else if (error instanceof RateLimitError) {
    // 429 — retry after error.retryAfter seconds
  } else if (error instanceof ValidationError) {
    // 422 — check error.errors for field-level details
  }
}

Extending with Custom Resources

Adding a new resource is ~10 lines:

import { BaseResource } from '@iris-ai/sdk';

class MyCustomResource extends BaseResource {
  constructor(http, config) {
    super(http, config, '/api/v1/my-resource');
  }

  // Inherits: list(), get(), create(), update(), delete()
  // Add custom methods as needed
}

Requirements

• Node.js 18+ (uses native fetch)
• Zero runtime dependencies

License

MIT