Roe AI TypeScript SDK

TypeScript/Node SDK for the Roe AI API.

v1.0.80 — RoeHTTPClient/axios were replaced by the generated openapi-fetch client exposed as client.raw; use components["schemas"] (or inferred types from the wrappers) where you need response shapes from the OpenAPI definitions. Highlights and migration notes across releases live in CHANGELOG.md.

Installation

npm install roe-typescript

Quick Start

import { RoeClient } from "roe-typescript";

const client = new RoeClient({
  apiKey: "your-api-key",
  organizationId: "your-org-uuid",
});

// Run an agent
const job = await client.agents.run({
  agentId: "agent-uuid",
  inputs: { text: "Analyze this text" },
});
const result = await job.wait();

for (const output of result.outputs) {
  console.log(`${output.key}: ${output.value}`);
}

Or use environment variables:

export ROE_API_KEY="your-api-key"
export ROE_ORGANIZATION_ID="your-org-uuid"

Job Result Inspection

After waiting for a job, you can inspect its outcome using the JobStatus enum:

import { JobStatus } from "roe-typescript";

const result = await job.wait();

if (result.status === JobStatus.SUCCESS || result.status === JobStatus.CACHED) {
  for (const output of result.outputs) {
    console.log(`${output.key}: ${output.value}`);
  }
} else if (result.status === JobStatus.CANCELLED) {
  console.log("Job was cancelled");
} else if (result.status === JobStatus.FAILURE) {
  console.log("Error:", result.error_message);
}

// Available fields
result.status        // JobStatus enum value (PENDING, STARTED, RETRY, SUCCESS, FAILURE, CANCELLED, CACHED) or null
result.error_message // Error string or null
result.outputs       // AgentDatum[] from components["schemas"]["AgentDatum"]

Errors

Non-2xx responses throw typed exceptions from roe-typescript, all subclasses of RoeAPIException. Use them to handle expected failures without parsing error strings:

import {
  RoeAPIException,
  BadRequestError,          // 400 — validation / bad input
  AuthenticationError,      // 401 — missing or invalid API key
  InsufficientCreditsError, // 402 — plan limit / billing
  ForbiddenError,           // 403 — feature or resource forbidden
  NotFoundError,            // 404 — resource not found
  RateLimitError,           // 429 — throttled
  ServerError,              // 5xx — server-side
} from "roe-typescript";

try {
  await client.agents.retrieve("00000000-0000-0000-0000-000000000000");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log(err.statusCode, err.message);
  } else {
    throw err;
  }
}

job.wait() does not throw on agent-side failures — instead the returned result carries result.status === JobStatus.FAILURE and result.error_message. Transport / HTTP errors hit the typed hierarchy above.

Raw API Access

The generated raw client is exposed as client.raw:

import { RoeClient } from "roe-typescript";

const client = new RoeClient({
  apiKey: "your-api-key",
  organizationId: "your-org-uuid",
});

const response = await client.raw.GET("/v1/users/current_user/");
console.log(response.response.status);

Full Example

Create an agent that extracts structured data from websites:

import { RoeClient } from "roe-typescript";

const client = new RoeClient();

// Create a Web Insights agent
const agent = await client.agents.create({
  name: "Company Analyzer",
  engineClassId: "URLWebsiteExtractionEngine",
  inputDefinitions: [
    { key: "url", data_type: "text/plain", description: "Website URL" },
  ],
  engineConfig: {
    url: "${url}",
    model: "gpt-4.1-2025-04-14",
    instruction: "Extract company information from this website.",
    vision_mode: false,
    crawl_config: {
      save_html: true,
      save_markdown: true,
      save_screenshot: true,
    },
    output_schema: {
      type: "object",
      properties: {
        company_name: { type: "string" },
        description: { type: "string" },
        products: { type: "array", items: { type: "string" } },
      },
    },
  },
});

// Run the agent
const job = await client.agents.run({
  agentId: agent.id,
  inputs: { url: "https://www.roe-ai.com/" },
});
const result = await job.wait();

// Print results
for (const output of result.outputs) {
  console.log(JSON.stringify(JSON.parse(output.value), null, 2));
}

// Cleanup
await client.agents.delete(agent.id);

API Reference

Agents

client.agents.list()                        // List agents
client.agents.retrieve("agent-uuid")        // Get agent
client.agents.create({ name, ... })         // Create agent
client.agents.update("agent-uuid", { ... }) // Update agent
client.agents.delete("agent-uuid")          // Delete agent
client.agents.duplicate("agent-uuid")       // Duplicate agent

agents.duplicate(...) returns an AgentVersion (the new agent's first version), not a BaseAgent. The new agent's id is reachable on the returned object as .base_agent.id.

Running Agents

client.agents.run({ agentId, inputs })      // Async execution
client.agents.runSync(agentId, inputs)      // Sync execution
client.agents.runMany({ agentId, batchInputs }) // Batch execution
client.agents.runVersion({ agentId, versionId, inputs })

Versions

client.agents.versions.list(agentId)
client.agents.versions.retrieve(agentId, versionId)
client.agents.versions.retrieveCurrent(agentId)
client.agents.versions.create({ agentId, ... })
client.agents.versions.update(agentId, versionId, { ... })
client.agents.versions.delete(agentId, versionId)

Jobs

client.agents.jobs.retrieveStatus(jobId)
client.agents.jobs.retrieveResult(jobId)
client.agents.jobs.downloadReference(jobId, resourceId)
client.agents.jobs.deleteData(jobId)

Policies

client.policies.list()                              // List policies
client.policies.retrieve("policy-uuid")             // Get policy
client.policies.create({ name, content, ... })      // Create policy
client.policies.update("policy-uuid", { ... })      // Update policy
client.policies.delete("policy-uuid")               // Delete policy

Policy Versions

client.policies.versions.list(policyId)
client.policies.versions.retrieve(policyId, versionId)
client.policies.versions.create({ policyId, content, ... })

Rori Agents (Agentic Workflows)

Rori agents are autonomous investigation agents that follow policies (SOPs), use tools, and produce structured verdicts. Unlike extraction engines which transform data, Rori agents reason over evidence, apply policy rules, and return dispositions. All Rori agents are policy-aware — you define the rules, they run the investigation.

Policies

Policies define the rules, instructions, and disposition classifications that Rori agents follow. Creating a policy atomically creates the policy and its first version in one call:

const policy = await client.policies.create({
  name: "AML Investigation Policy",
  content: {
    guidelines: {
      categories: [
        {
          title: "Structuring",
          rules: [
            {
              title: "Cash structuring below reporting thresholds",
              description: "Multiple deposits just under $10,000 within short timeframes",
              flag: "RED_FLAG",
            },
          ],
        },
        {
          title: "Layering",
          rules: [
            {
              title: "Rapid movement between accounts",
              description: "Funds transferred through multiple accounts to obscure origin",
              flag: "RED_FLAG",
              sub_rules: [
                { title: "Cross-border wire transfers with no business purpose" },
                { title: "Shell company intermediaries" },
              ],
            },
          ],
        },
      ],
    },
    instructions: "Investigate the alert against each category. Use available data sources to gather evidence.",
    dispositions: {
      classifications: [
        { name: "Suspicious", description: "Activity warrants SAR filing" },
        { name: "Not Suspicious", description: "Activity has legitimate explanation" },
        { name: "Needs Escalation", description: "Requires senior analyst review" },
      ],
    },
    summary_template: {
      template: "Investigation of {{subject}} found {{verdict}} based on {{findings_count}} findings.",
    },
  },
});

Iterate on policies by creating new versions:

// Create a new version (automatically becomes the current version)
const newVersion = await client.policies.versions.create({
  policyId: policy.id,
  content: { /* Updated policy content */ },
  versionName: "v2 - added layering rules",
});

// List all versions
const versions = await client.policies.versions.list(policy.id);

// Retrieve a specific version
const version = await client.policies.versions.retrieve(policy.id, newVersion.id);

// Update policy metadata
await client.policies.update(policy.id, { name: "Updated Policy Name" });

// List all policies
const policies = await client.policies.list();

// Delete a policy
await client.policies.delete(policy.id);

Policy Content Reference

| Field | Type | Description | |-------|------|-------------| | guidelines | object | Categories → Rules → Sub-rules hierarchy | | guidelines.categories[].title | string | Category name | | guidelines.categories[].rules[].title | string | Rule name | | guidelines.categories[].rules[].description | string | Rule details | | guidelines.categories[].rules[].flag | string | "RED_FLAG" or "GREEN_FLAG" | | guidelines.categories[].rules[].sub_rules[].title | string | Sub-rule name | | instructions | string | Free-text investigation instructions | | dispositions.classifications[].name | string | Outcome label (e.g., "Suspicious") | | dispositions.classifications[].description | string | When to apply this outcome | | summary_template.template | string | Handlebars template for report generation | | optional.sar_narrative_template.template | string | SAR narrative template (AML-specific) |

Product Compliance

Analyze product listings against your compliance policy:

const agent = await client.agents.create({
  name: "Product Compliance",
  engineClassId: "ProductPolicyEngine",
  inputDefinitions: [
    { key: "product_listings", data_type: "text/plain", description: "Product listing to analyze" },
  ],
  engineConfig: {
    policy_version_id: policy.current_version_id!,
    product_listings: "${product_listings}",
  },
});

const outputs = await client.agents.runSync(agent.id, {
  product_listings: "Nike Air Max 90, brand new, $45 — ships from Shenzhen",
});

AML Investigation

Investigate anti-money laundering alerts:

const agent = await client.agents.create({
  name: "AML Investigation",
  engineClassId: "AMLInvestigationEngine",
  inputDefinitions: [
    { key: "alert_data", data_type: "text/plain", description: "Alert data and context" },
  ],
  engineConfig: {
    policy_version_id: policy.current_version_id!,
    alert_data: "${alert_data}",
  },
});

const job = await client.agents.run({
  agentId: agent.id,
  inputs: { alert_data: "Customer John Doe, 5 cash deposits of $9,500 in 3 days" },
});
const result = await job.wait();

Fraud Investigation

Investigate fraud alerts and suspicious activity:

const agent = await client.agents.create({
  name: "Fraud Investigation",
  engineClassId: "FraudInvestigationEngine",
  inputDefinitions: [
    { key: "alert_data", data_type: "text/plain", description: "Alert data and context" },
  ],
  engineConfig: {
    policy_version_id: policy.current_version_id!,
    alert_data: "${alert_data}",
  },
});

const job = await client.agents.run({
  agentId: agent.id,
  inputs: { alert_data: "Chargeback spike: 47 disputes in 24h from merchant ACME-1234" },
});
const result = await job.wait();

Merchant Risk

Analyze merchant risk profiles:

const agent = await client.agents.create({
  name: "Merchant Risk Analysis",
  engineClassId: "MerchantRiskEngine",
  inputDefinitions: [
    { key: "merchant_context", data_type: "text/plain", description: "Merchant name and context" },
  ],
  engineConfig: {
    policy_version_id: policy.current_version_id!,
    merchant_context: "${merchant_context}",
  },
});

const job = await client.agents.run({
  agentId: agent.id,
  inputs: { merchant_context: "ACME Corp - Online electronics retailer, MCC 5732" },
});
const result = await job.wait();

Agent Configuration Options

All Rori agents accept these options in engineConfig:

| Option | Type | Default | Description | |--------|------|---------|-------------| | policy_version_id | string | — | Policy version UUID (required) | | context_sources | array | [] | External data sources (SQL connections, APIs) | | enable_planning | boolean | true | Enable autonomous tool-use planning | | enable_memory | boolean | false | Retain context across runs for the same entity | | reasoning_effort | string | "medium" | "low", "medium", or "high" |

Example with advanced configuration:

const agent = await client.agents.create({
  name: "AML Investigation (Advanced)",
  engineClassId: "AMLInvestigationEngine",
  inputDefinitions: [
    { key: "alert_data", data_type: "text/plain", description: "Alert data and context" },
  ],
  engineConfig: {
    policy_version_id: policy.current_version_id!,
    alert_data: "${alert_data}",
    reasoning_effort: "high",
    context_sources: [
      { type: "sql", name: "Transactions DB", connection_id: "conn-uuid" },
    ],
  },
});

Supported Models

| Model | Value | |-------|-------| | GPT-5.4 Pro | gpt-5.4-pro-2026-03-05 | | GPT-5.4 | gpt-5.4-2026-03-05 | | GPT-5.4 Mini | gpt-5.4-mini-2026-03-17 | | GPT-5.4 Nano | gpt-5.4-nano-2026-03-17 | | GPT-5.2 | gpt-5.2-2025-12-11 | | GPT-5 | gpt-5-2025-08-07 | | GPT-4.1 | gpt-4.1-2025-04-14 | | Claude Opus 4.7 | claude-opus-4-7 | | Claude Opus 4.6 | claude-opus-4-6 | | Claude Sonnet 4.6 | claude-sonnet-4-6 | | Claude Haiku 4.5 | claude-haiku-4-5-20251001 | | Gemini 3.1 Pro | gemini-3.1-pro-preview | | Gemini 3 Flash | gemini-3-flash-preview | | Grok 4.20 Reasoning | grok-4.20-0309-reasoning |

Engine Classes

| Engine | ID | |--------|----| | Multimodal Extraction | MultimodalExtractionEngine | | Document Insights | PDFExtractionEngine | | Document Segmentation | PDFPageSelectionEngine | | Web Insights | URLWebsiteExtractionEngine | | Interactive Web | InteractiveWebExtractionEngine | | Web Search | URLFinderEngine | | Perplexity Search | PerplexitySearchEngine | | Maps Search | GoogleMapsEntityExtractionEngine | | LinkedIn Crawler | LinkedInScraperEngine | | Social Media | SocialScraperEngine | | Product Compliance | ProductPolicyEngine | | Merchant Risk | MerchantRiskEngine | | AML Investigation | AMLInvestigationEngine | | Fraud Investigation | FraudInvestigationEngine |

Links

• Roe AI
• API Docs
• Changelog