# Introduction
Source: https://docs.roe-ai.com/agents/agentic-workflows/introduction
Autonomous AI agents that reason, research, and make decisions
## What are Agentic Workflows?
Agentic Workflows are autonomous AI agents that go beyond simple extraction or processing. Unlike traditional engines that follow deterministic rules, agentic workflows can reason about complex problems, dynamically query external data sources, conduct web research, and make sophisticated decisions based on your policies and guidelines.
### Key Characteristics
**Autonomous Reasoning:** Agentic workflows analyze situations and determine the best course of action without rigid step-by-step instructions. They adapt their investigation approach based on what they discover.
**Dynamic Research & Querying:** These agents can perform web research, query SQL databases (Snowflake, ClickHouse) for transaction data, call APIs (Zendesk, etc.) to retrieve context, and synthesize information from multiple sources.
**Policy-Driven Decision Making:** Agentic workflows evaluate evidence against your Standard Operating Procedures (SOPs) and policies to produce structured verdicts and recommendations, just like a human analyst would.
**Multi-Step Investigations:** Rather than a single extraction pass, these agents conduct thorough investigations with multiple steps: data gathering, evidence analysis, risk assessment, and final determination.
## When to Use Agentic Workflows
Choose an agentic workflow when you need:
* **Complex investigations** that require gathering evidence from multiple sources
* **Policy-based decision making** with clear verdicts and recommendations
* **Dynamic data access** where the agent needs to query databases or APIs based on what it finds
* **Multi-step reasoning** that mimics how a human analyst would approach the problem
* **Explainable results** with evidence trails and justification for decisions
## Configuration Requirements
Most agentic workflows require:
1. **Policy Version ID**: A policy containing your SOPs, guidelines, and decision criteria
2. **Context Sources** (optional but recommended): Connections to data warehouses, APIs, or databases
3. **Input Data**: The alert, case, or data to investigate
Learn more about [Policies](/policies/introduction) and [Context Sources](/data-resources/context-sources).
# AML Investigation
Source: https://docs.roe-ai.com/agents/engines/aml-investigation
Investigates transaction data for potential money laundering patterns using policy-driven analysis
## AML Investigation Engine Overview
The AML (Anti-Money Laundering) Investigation Engine is an agentic workflow that investigates transaction data for potential money laundering patterns. It analyzes alerts against your defined Standard Operating Procedures (SOPs), performs web research, and queries data warehouses to gather evidence and produce a structured investigation result.
### Key Capabilities
* **Policy-Driven Analysis**: Investigates transactions against your AML SOP guidelines
* **Automated Evidence Collection**: Uses web research and SQL queries to gather evidence
* **Category-by-Category Analysis**: Evaluates red flags and green flags per SOP category
* **Structured Verdicts**: Produces investigation results with clear verdicts from your policy dispositions
## AML Investigation Engine Inputs
The AML Investigation Engine Configuration has **four parameters**:
| Parameter | Required | Description |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| **policy\_version\_id** | Yes | The Policy version ID containing your AML investigation guidelines (SOP) |
| **context\_sources** | No | Data sources (e.g., Snowflake) for the agent to query transaction data during investigation |
| **alert\_data** | Yes | Alert data that triggered this investigation (JSON string with alert details) |
| **transaction\_data** | No | Pre-loaded transaction data (JSON string). If empty, the agent will fetch from context sources |
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## AML Investigation Output
The output is a structured JSON object containing:
### Policy Applied
Information about the policy used for investigation:
* `name`: Name of the policy applied
* `version`: Version ID of the policy applied
### AML Analysis
Complete investigation result including:
| Field | Description |
| -------------------- | ----------------------------------------------------------------------------------- |
| `verdict` | Final verdict from policy dispositions (e.g., "Clear - False Positive", "File STR") |
| `summary` | Executive summary explaining the conclusion and key findings |
| `category_analysis` | Detailed analysis for each category in the policy guidelines |
| `out_of_scope_flags` | Additional findings not covered by the defined guidelines |
| `reason_for_output` | Brief explanation of the thought process behind the verdict |
### Category Analysis Structure
For each SOP category, the output includes:
* `category_title`: Title of the category
* `summary`: 2-3 sentence summary of findings
* `red_flag_analysis`: Array of RED\_FLAG rules with hit status and evidence
* `green_flag_analysis`: Array of GREEN\_FLAG rules with hit status and evidence
### Evidence Structure
Each piece of evidence includes:
* `evidence_type`: "web\_link", "screenshot", or "artifact"
* `evidence_data`: URL or artifact reference
* `evidence_name`: Short descriptive name
* `evidence_description`: Why this evidence is relevant
## Policy (SOP) Structure
Your AML policy should contain:
1. **Instructions**: High-level data exploration and investigation guidance
2. **Guidelines**: Organized as Categories > Rules
* Each Category (e.g., "BLACKLISTED\_BARCODE\_CHECK", "DAILY\_TRANSACTION\_COUNT\_CHECK") contains multiple Rules
* Each Rule has a `flag` type (GREEN\_FLAG or RED\_FLAG), `title`, and `description`
3. **Dispositions**: Classification options for final verdicts
## Supported Context Sources
The AML Investigation Engine supports the following data source connectors:
| Connector | Type | Description |
| -------------- | ---- | -------------------------------------------------------------------------------- |
| **Snowflake** | SQL | Query your Snowflake data warehouse for transaction history, customer data, etc. |
| **Roe Tables** | SQL | Query tables stored in Roe Tables for internal data analysis |
| **Zendesk** | API | Fetch support tickets and customer communication history |
Configure context sources to allow the agent to automatically fetch transaction data during investigation. The agent will use natural language to generate appropriate SQL queries or API calls.
## Creating an AML Policy
The AML Investigation Engine requires a policy containing your Standard Operating Procedures (SOPs). You can create policies using the [Policies](/policies/introduction) feature.
A pre-built **AML Investigation Workflow** policy template is available in the platform. This template provides a comprehensive framework for alert review, typology assessment, evidence synthesis, and regulatory reporting decisions.
### Policy Template Structure
The AML policy template includes:
* **Alert Intake and Classification**: Initial steps for processing alerts
* **Customer Due Diligence Review**: KYC verification and customer profile analysis
* **Transaction Pattern Analysis**: Suspicious activity indicators
* **Web Research Guidance**: Entity verification and adverse media screening
* **Disposition Classifications**: Clear verdict options (e.g., "Clear - False Positive", "File STR", "Escalate for Review")
## Example Alert Data
```json theme={null}
{
"alert_id": "ALT-2024-001234",
"merchant_id": "MER-789456",
"merchant_name": "ABC Trading Co.",
"alert_type": "HIGH_VOLUME_TRANSACTIONS",
"alert_date": "2024-01-15",
"triggered_by": "Daily transaction count exceeded threshold",
"transaction_summary": {
"total_transactions": 450,
"total_amount": 125000.00,
"average_amount": 277.78
}
}
```
## Example Output
```json theme={null}
{
"policy_applied": {
"name": "AML Investigation SOP v2",
"version": "pol_ver_abc123"
},
"aml_analysis": {
"verdict": "Clear - Continue Monitoring",
"summary": "Investigation found high transaction volume consistent with seasonal business patterns. No indicators of structuring or suspicious counterparties identified.",
"category_analysis": [
{
"category_title": "TRANSACTION_PATTERN_CHECK",
"summary": "Transaction patterns show legitimate business activity with seasonal variation.",
"red_flag_analysis": [
{
"rule_title": "Round Amount Detection",
"hit": false,
"evidences": []
}
],
"green_flag_analysis": [
{
"rule_title": "Consistent Business Hours",
"hit": true,
"evidences": [
{
"evidence_type": "artifact",
"evidence_data": "AMLInvestigationEngine-123/sql_query_1234567.json",
"evidence_name": "Transaction timing analysis",
"evidence_description": "95% of transactions occur during business hours 9am-6pm"
}
]
}
]
}
],
"out_of_scope_flags": [],
"reason_for_output": "I analyzed the merchant's transaction patterns and found them consistent with their stated business type. The high volume is explained by seasonal factors and no structuring patterns were detected."
}
}
```
## Common Verdict Classifications
Define disposition classifications in your policy that match your compliance requirements. Common examples include:
| Verdict | Description |
| ------------------------------------- | --------------------------------------------------------- |
| **Clear - False Positive** | Alert reviewed, no suspicious activity identified |
| **Clear - Continue Monitoring** | No immediate concern, but enhanced monitoring recommended |
| **Hold - Pending Documentation** | Additional documentation needed before final decision |
| **Escalate for Review** | Requires senior analyst or compliance officer review |
| **File STR** | Suspicious Transaction Report should be filed |
| **Temporary Suspension + Escalation** | Account suspended pending further investigation |
## Use Cases
The AML Investigation Engine is designed for:
* **Transaction Monitoring Alerts**: Investigate alerts from TMS systems for unusual transaction patterns
* **Sanctions Screening**: Verify potential matches against sanctions lists
* **PEP Identification**: Investigate politically exposed person alerts
* **Adverse Media Monitoring**: Assess negative news coverage about customers or counterparties
* **Periodic Customer Reviews**: Conduct scheduled reviews of high-risk customers
* **Referrals from Other Teams**: Investigate escalations from frontline staff
## Best Practices
Create comprehensive policies with specific red and green flag rules for each category you want to investigate
Configure SQL context sources to allow the agent to query historical transaction data automatically
Provide well-structured alert data with all relevant identifiers for accurate investigation
Define clear disposition classifications in your policy for consistent verdict assignment
## Related Resources
Learn how to create and manage AML investigation policies
Set up Snowflake and other data source connections
# Data Analysis
Source: https://docs.roe-ai.com/agents/engines/data-analysis
Performs AI-powered multimodal data analysis with web research and context source integration.
## Data Analysis Engine Overview
The Data Analysis Engine is an agentic workflow that intelligently orchestrates document/image extraction with optional web research and context source querying. The agent reasons about the best approach to extract information based on the provided instruction and content.
## Engine Inputs
The Data Analysis Engine Configuration has the following parameters:
* **text**: *optional.* Text content to extract information from. Leave blank to extract from images only.
* **images**: *optional.* Image URLs or file IDs (comma/newline/whitespace separated). Leave blank to extract from text only.
* **instruction**: *optional.* Instructions describing what to extract or analyze from the provided content.
* **output\_schema**: *required.* JSON schema defining the structure of data to extract. Follows the standard [JSON schema specification](https://json-schema.org/).
* **context\_sources**: *optional.* Define context sources (Snowflake, ClickHouse, Zendesk, etc.) for the agent to query during analysis.
At least one of **text** or **images** must be provided.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output will be a JSON value matching the structure specified in the **output\_schema**.
## Example Usage
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **text**: \$text
* **images**: \$images
* **instruction**: Analyze the data and extract key insights
* **output\_schema**: Copy and paste the JSON schema below:
```json theme={null}
{
"type": "object",
"properties": {
"summary": {
"type": "string",
"description": "Summary of the analysis"
},
"key_findings": {
"type": "array",
"items": { "type": "string" },
"description": "List of key findings"
},
"recommendations": {
"type": "array",
"items": { "type": "string" },
"description": "Recommended actions"
}
},
"required": ["summary"]
}
```
Hit the **Create** button.
Create a new job and provide the data to analyze.
## Capabilities
The Data Analysis Engine has access to multiple tools:
* **Extraction**: Process text and images directly
* **URL Finder**: Search for relevant URLs
* **Web Extraction**: Scrape and extract from web pages
* **Perplexity Search**: Conduct web research
* **Context Source Queries**: Query connected Snowflake, ClickHouse, or Zendesk sources
## Use Cases
* **Business intelligence**: Generate insights from business data with web enrichment
* **Document analysis**: Extract structured data from documents and images
* **Research synthesis**: Combine provided data with web research
* **Multi-source analysis**: Integrate data from context sources with provided content
* **Report generation**: Create automated data reports and summaries
# Document Segmentation
Source: https://docs.roe-ai.com/agents/engines/document-segmentation
Parses page filter criteria and outputs a list of page ranges from PDF documents.
## Document Segmentation Engine Overview
The Document Segmentation Engine analyzes PDF documents and extracts specific page ranges based on semantic descriptions, explicit page ranges, or table of contents entries. It supports multi-stage filtering with optimized processing for large documents.
## Engine Inputs
The Document Segmentation Engine Configuration has the following parameters:
* **page\_description**: *required.* A semantic description of the pages to select. Supports multiple formats:
* **Semantic search**: Natural language description of target pages (e.g., "Any page containing financial data")
* **@PAGERANGE prefix**: Explicit page ranges (e.g., `@PAGERANGE: 3, 5-15`)
* **@TOC prefix**: Table of contents entries (e.g., `@TOC: Chapter 1, Section 2`)
* Can combine multiple formats in one query
* **pdf\_file**: *required.* PDF file to select pages from. Can be file uploads, URLs, or file IDs.
* **model**: *optional.* The AI model to use (defaults to tier 1 image model).
**Example page\_description**:
```
@TOC: Chapter 1, Section 2, some-relevant-text;
@PAGERANGE: 3, 5-15;
Any page containing financial statements
```
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output is a list of page ranges matching the specified criteria.
# Fraud Investigation
Source: https://docs.roe-ai.com/agents/engines/fraud-investigation
Investigates fraud alerts by analyzing transaction data, alert signals, and external intelligence to determine if an alert is genuine fraud or a false positive
## Fraud Investigation Engine Overview
The Fraud Investigation Engine is an agentic workflow that investigates fraud alerts by analyzing transaction data, alert signals, and external intelligence. It evaluates evidence against your Standard Operating Procedures (SOPs), performs web research to verify external entities, and queries data warehouses to produce a comprehensive investigation with a clear verdict and recommended action.
### Key Capabilities
* **Policy-Driven Analysis**: Investigates alerts against your fraud investigation SOP guidelines
* **Fraud Classification**: Categorizes fraud by scenario (what happened), actor (who did it), vector (how), and payment rail
* **Automated Evidence Collection**: Uses web research and SQL queries to gather and cite evidence
* **Risk Signal Detection**: Identifies high-risk signals and verification checks that passed from your SOP
* **Structured Verdicts**: Produces investigation results with clear verdicts from your policy dispositions
### Prerequisites
Before using the Fraud Investigation Engine, ensure you have:
1. **A Fraud Investigation Policy**: Create a policy containing your fraud investigation SOP with guidelines, red flag criteria, and disposition options. See [Policies](/policies/introduction) for setup instructions.
2. **Context Sources (Recommended)**: Configure data connectors (Snowflake, ClickHouse, or Zendesk) to allow the agent to query transaction history and customer data. See [Data Connectors](/data-resources/connectors/introduction).
## Fraud Investigation Engine Inputs
The Fraud Investigation Engine Configuration has **four parameters**:
| Parameter | Required | Description |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| **policy\_version\_id** | Yes | The Policy version ID containing your fraud investigation guidelines (SOP) |
| **context\_sources** | No | Data sources (e.g., Snowflake, Zendesk) for the agent to query transaction and customer data during investigation |
| **alert\_data** | Yes | Alert data that triggered this investigation (JSON string with alert details) |
| **transaction\_data** | No | Pre-loaded transaction data (JSON string). If empty, the agent will fetch from context sources |
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Fraud Investigation Output
The output is a structured JSON object containing:
#### Policy Applied
Information about the policy used for investigation:
* `name`: Name of the policy applied
* `version`: Version ID of the policy applied
#### Customer Profile
Customer information gathered during the investigation:
| Field | Description |
| ------------ | ------------------------------------------------------------------- |
| `account_id` | Customer's account identifier |
| `email` | Customer's email address |
| `name` | Customer's full name |
| `phone` | Customer's phone number |
| `location` | Customer's location (city, state, country or IP-based geolocation) |
| `devices` | Devices associated with the customer (e.g., "iPhone 14", "Android") |
| `product` | Product or service the customer is using |
| `accounts` | List of account types or linked accounts |
| `kyc_status` | KYC verification status including provider and verification method |
#### Fraud Analysis
Complete investigation result including:
| Field | Description |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `verdict` | Final verdict from policy dispositions (e.g., "False Positive", "Needs Review") |
| `summary` | Markdown executive summary with inline evidence references using `$REF_X$` markers |
| `summary_evidences` | Array of evidence objects corresponding to `$REF_X$` markers in the summary |
| `rail` | Payment method used (wire, ach, check, card\_present, card\_not\_present, zelle\_rtp) |
| `scenario` | Fraud typology if fraud is suspected (e.g., account\_takeover, scam\_investment) |
| `actor` | Who committed the fraud (third\_party, first\_party, second\_party, internal\_employee) |
| `vectors` | Attack vectors used (e.g., phishing\_link, credential\_stuffing, sim\_swap) |
| `high_risk_signals` | Array of detected risk signals with evidence |
| `checks_passed` | Array of verification checks that passed with evidence |
| `action_recommendation` | Recommended action with reasoning |
#### Risk Signal Structure
Each risk signal includes:
* `signal_name`: Clear, concise name of the risk signal
* `reasoning`: One sentence explanation of the key finding
* `evidences`: Array of evidence supporting this finding
#### Checks Passed Structure
Each check passed includes:
* `check_name`: Clear, concise name of the check passed
* `reasoning`: One sentence explanation of the key finding
* `evidences`: Array of evidence supporting this finding
#### Evidence Structure
Each piece of evidence includes:
* `evidence_type`: "web\_link", "screenshot", or "artifact"
* `evidence_data`: URL or artifact reference
* `evidence_name`: Short descriptive name
* `evidence_description`: Why this evidence is relevant
#### Action Recommendation Structure
| Field | Description |
| ------------------ | -------------------------------------------------------- |
| `suggested_action` | One of: `clear_alert`, `escalate`, or `lock_account` |
| `reasoning` | Explanation for why this action is suggested over others |
## Fraud Classification Taxonomy
The Fraud Investigation Engine uses a structured taxonomy to classify fraud:
#### Fraud Scenarios (The "What")
| Scenario | Description |
| ----------------------- | ----------------------------------------------- |
| **account\_takeover** | Unauthorized access to an existing account |
| **new\_account\_fraud** | Synthetic or stolen identity used at onboarding |
| **card\_testing** | High velocity small authorizations |
| **scam\_impersonation** | Bank/government impostor scams |
| **scam\_investment** | Crypto/pig butchering investment scams |
| **scam\_romance** | Romance-based fraud schemes |
| **first\_party\_abuse** | "Friendly fraud" / refund abuse |
| **mule\_activity** | Receiving stolen funds |
| **structuring** | Smurfing to avoid reporting limits |
#### Fraud Actors (The "Who")
| Actor | Description | Liability |
| ---------------------- | ------------------- | ------------------ |
| **third\_party** | External criminal | Bank Liability |
| **first\_party** | Customer themselves | Customer Liability |
| **second\_party** | Mule/Collusion | Shared Liability |
| **internal\_employee** | Insider threat | Bank Liability |
#### Attack Vectors (The "How")
| Vector | Type | Description |
| ------------------------ | --------- | ------------------------------- |
| **credential\_stuffing** | Technical | Reusing passwords from breaches |
| **malware\_bot** | Technical | Automated malicious software |
| **sim\_swap** | Technical | Phone number hijacking |
| **man\_in\_the\_middle** | Technical | Intercepting communications |
| **phishing\_link** | Social | Clicked malicious link |
| **vishing\_call** | Social | Fraudulent phone call |
| **document\_forgery** | Social | Fake ID or documents |
| **check\_washing** | Social | Chemically altering checks |
#### Payment Rails (The "Vehicle")
| Rail | Description |
| ---------------------- | ------------------------------ |
| **wire** | Wire transfer |
| **ach** | ACH transfer |
| **check** | Check payment |
| **card\_present** | In-person card transaction |
| **card\_not\_present** | Online/remote card transaction |
| **zelle\_rtp** | Zelle or real-time payments |
## Policy (SOP) Structure
Your fraud policy should contain:
1. **Instructions**: High-level investigation guidance for fraud detection
2. **Guidelines**: Organized as Categories > Rules
* Each Category contains multiple Rules
* Each Rule has a `flag` type (GREEN\_FLAG or RED\_FLAG), `title`, and `description`
3. **Dispositions**: Classification options for final verdicts
## Supported Context Sources
The Fraud Investigation Engine supports the following data source connectors:
| Connector | Type | Description |
| -------------- | ---- | --------------------------------------------------------------------------------------------- |
| **Snowflake** | SQL | Query your Snowflake data warehouse for transaction history, customer data, device logs, etc. |
| **ClickHouse** | SQL | Query ClickHouse for high-performance analytics on transaction data |
| **Roe Tables** | SQL | Query tables stored in Roe Tables for internal data analysis |
| **Zendesk** | API | Fetch support tickets and customer communication history |
Configure context sources to allow the agent to automatically fetch transaction and customer data during investigation. The agent uses an iterative SQL querying strategy—first discovering the schema, then verifying entity columns, before running aggregated queries.
## Creating a Fraud Policy
Fraud investigation requires a policy containing your Standard Operating Procedures (SOP). You can create policies using the [Policies](/policies/introduction) feature.
A pre-built **Fraud Investigation Workflow** policy template is available in the platform. This template provides a comprehensive framework for alert review, typology assessment, evidence synthesis, and decision labels.
## Example Alert Data
```json theme={null}
{
"alert_id": "FRD-2024-005678",
"account_id": "ACC-123456",
"customer_name": "John Smith",
"customer_email": "john.smith@example.com",
"alert_type": "ACCOUNT_TAKEOVER_SUSPECTED",
"alert_date": "2024-01-20",
"triggered_by": "Multiple failed login attempts followed by password reset from new device",
"risk_score": 85,
"device_info": {
"device_id": "DEV-789",
"device_type": "Android",
"ip_address": "203.0.113.45",
"geolocation": "Lagos, Nigeria"
},
"transaction_summary": {
"attempted_transfer": 5000.00,
"recipient": "Unknown Wallet",
"payment_method": "wire"
}
}
```
## Example Output
```json theme={null}
{
"policy_applied": {
"name": "Fraud Investigation SOP v3",
"version": "pol_ver_xyz789"
},
"customer_profile": {
"account_id": "ACC-123456",
"email": "john.smith@example.com",
"name": "John Smith",
"phone": "+1-555-0123",
"location": "New York, NY",
"devices": ["iPhone 14 Pro", "MacBook Pro"],
"product": "Premium Checking",
"accounts": ["checking", "savings"],
"kyc_status": {
"verified": true,
"last_verified": "2023-06-15",
"provider": "Persona",
"verification_method": "Selfie, ID Upload"
}
},
"fraud_analysis": {
"verdict": "highly_suspected",
"summary": "Investigation of account takeover alert for customer ACC-123456. The alert flagged suspicious login activity from an unrecognized device.\n\n**Red Flags:**\n- **New device from Nigeria** detected, inconsistent with customer's US-based transaction history $REF_1$\n- **5 failed login attempts** before successful authentication via password reset $REF_2$\n- **Attempted $5,000 wire transfer** to unknown wallet immediately after access $REF_3$\n\n**Green Flags:**\n- Customer has **verified KYC status** with Persona $REF_4$\n\nStrong evidence of third-party account takeover via credential compromise. Immediate account protection recommended.",
"summary_evidences": [
{
"id": "REF_1",
"evidence_type": "artifact",
"evidence_data": "FraudInvestigationEngine-456/sql_query_device_history.json",
"evidence_name": "Device geolocation analysis",
"evidence_description": "Customer's previous 50 logins were all from New York; this login originated from Nigeria"
},
{
"id": "REF_2",
"evidence_type": "artifact",
"evidence_data": "FraudInvestigationEngine-456/sql_query_login_attempts.json",
"evidence_name": "Login attempt logs",
"evidence_description": "5 failed password attempts within 3 minutes before password reset request"
},
{
"id": "REF_3",
"evidence_type": "input",
"evidence_data": "alert_data",
"evidence_name": "Wire transfer attempt",
"evidence_description": "Attempted wire of $5,000 to unregistered recipient within 10 minutes of account access"
},
{
"id": "REF_4",
"evidence_type": "artifact",
"evidence_data": "FraudInvestigationEngine-456/sql_query_kyc_status.json",
"evidence_name": "KYC verification record",
"evidence_description": "Customer completed identity verification in June 2023"
}
],
"rail": "wire",
"scenario": "account_takeover",
"actor": "third_party",
"vectors": ["credential_stuffing"],
"high_risk_signals": [
{
"signal_name": "Geolocation Anomaly",
"reasoning": "Login from Nigeria when customer history shows exclusively US-based activity.",
"evidences": [
{
"evidence_type": "artifact",
"evidence_data": "FraudInvestigationEngine-456/sql_query_device_history.json",
"evidence_name": "Device location history",
"evidence_description": "All 50 previous logins from New York area"
}
]
},
{
"signal_name": "Password Reset After Failed Attempts",
"reasoning": "Classic account takeover pattern—multiple failed attempts followed by password reset.",
"evidences": [
{
"evidence_type": "artifact",
"evidence_data": "FraudInvestigationEngine-456/sql_query_login_attempts.json",
"evidence_name": "Authentication logs",
"evidence_description": "5 failed attempts then password reset in 3-minute window"
}
]
}
],
"checks_passed": [
{
"check_name": "KYC Verification Valid",
"reasoning": "Customer completed identity verification through Persona with selfie and ID upload.",
"evidences": [
{
"evidence_type": "artifact",
"evidence_data": "FraudInvestigationEngine-456/sql_query_kyc_status.json",
"evidence_name": "KYC record",
"evidence_description": "Verified June 2023 via Persona"
}
]
}
],
"action_recommendation": {
"suggested_action": "lock_account",
"reasoning": "Strong evidence of third-party account takeover with attempted fund transfer. Immediate account lock prevents further unauthorized access and protects customer funds."
}
}
}
```
## Action Recommendations
Based on the verdict, the engine recommends one of three actions:
| Action | When to Use |
| ----------------- | ----------------------------------------------------------------------------- |
| **clear\_alert** | Verdict is `false_positive`—no further action needed |
| **escalate** | Verdict is `needs_review`—requires human analyst review or additional context |
| **lock\_account** | Verdict is `highly_suspected`—immediate protective action to prevent losses |
## Use Cases
The Fraud Investigation Engine is designed for:
* **Account Takeover Alerts**: Investigate suspicious login patterns, device changes, or credential compromise
* **Transaction Fraud Alerts**: Analyze unusual transaction patterns, velocity anomalies, or suspicious recipients
* **New Account Fraud**: Investigate synthetic identity or application fraud signals
* **Scam Detection**: Identify investment scams, romance scams, or impersonation attempts
* **Chargeback Investigation**: Investigate disputes and determine first-party vs. third-party fraud
* **Mule Account Detection**: Identify accounts receiving or laundering stolen funds
## Best Practices
Create comprehensive fraud investigation policies with specific criteria for each verdict level
Configure SQL and Zendesk context sources to give the agent access to transaction history, device logs, and customer communications
Include all relevant identifiers (account ID, device info, IP, transaction details) in your alert data for thorough investigation
Define clear disposition classifications in your policy for consistent verdict assignment
## Related Resources
Learn how to create and manage fraud investigation policies
Set up Snowflake, ClickHouse, and Zendesk connections
Explore the related AML Investigation Engine for anti-money laundering cases
# Google Maps Insights
Source: https://docs.roe-ai.com/agents/engines/google-maps
Extracts location information, nearby places, and geographic data from Google Maps.
## Google Maps Insights Engine Overview
The Google Maps Insights Engine extracts comprehensive location information from Google Maps, including address details, coordinates, nearby businesses, and street view data.
## Engine Inputs
The Google Maps Insights Engine Configuration has the following parameters:
* **address**: *required.* The address or location to search for on Google Maps.
* **instruction**: *required.* Instructions describing what information to extract about the location.
* **output\_schema**: *required.* JSON schema defining the structure of the output. Follows the standard [JSON schema specification](https://json-schema.org/).
* **model**: *optional.* The AI model to use (default: `gpt-4.1-2025-04-14`).
* **near\_by\_business\_types**: *optional.* Comma-separated list of business types to search for nearby (e.g., "restaurant,cafe,bank"). Leave empty to search all types.
* **near\_by\_radius**: *optional.* Radius in meters to search for nearby places (default: 15.0, max: 1000.0).
* **near\_by\_number**: *optional.* Maximum number of nearby places to return (default: 5).
* **include\_street\_view**: *optional.* Whether to include street view imagery (default: False).
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output will be a JSON value matching the structure specified in the **output\_schema**, typically including:
* Location name and formatted address
* Geographic coordinates (latitude/longitude)
* Nearby places and businesses
* Place details and ratings
* Street view imagery (if enabled)
## Example Usage
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **address**: \$address
* **instruction**: \$instruction
* **model**: gpt-4.1-2025-04-14
* **near\_by\_radius**: 15.0
* **near\_by\_number**: 5
* **include\_street\_view**: False
* **output\_schema**: Copy and paste the JSON schema below:
```json theme={null}
{
"type": "object",
"properties": {
"location_name": {
"type": "string",
"description": "Name of the location"
},
"address": {
"type": "string",
"description": "Full address"
},
"coordinates": {
"type": "object",
"properties": {
"latitude": { "type": "number" },
"longitude": { "type": "number" }
},
"description": "Geographic coordinates"
},
"nearby_places": {
"type": "array",
"items": { "type": "string" },
"description": "List of nearby places"
},
"summary": {
"type": "string",
"description": "Summary of the location"
}
},
"required": ["location_name", "address"]
}
```
Hit the **Create** button.
Create a new job and provide:
* **address**: "1600 Amphitheatre Parkway, Mountain View, CA"
* **instruction**: "Extract the location name, full address, coordinates, and list any notable nearby places"
## Use Cases
* **Location verification**: Verify business addresses and get coordinates
* **Competitive analysis**: Find nearby competitors and businesses
* **Site assessment**: Evaluate locations for real estate or business purposes
* **Geographic enrichment**: Add location data to customer or business records
# Interactive Web Insights
Source: https://docs.roe-ai.com/agents/engines/interactive-web
Performs interactive web browsing and extracts information from dynamic web pages.
## Interactive Web Insights Engine Overview
The Interactive Web Insights Engine enables AI-powered interactive web browsing. Unlike static web scraping, this engine can navigate dynamic websites, interact with page elements, and extract information from JavaScript-rendered content.
## Engine Inputs
The Interactive Web Insights Engine Configuration has the following parameters:
* **url**: *required.* The URL to navigate to and interact with.
* **action**: *required.* Instructions describing what actions to perform on the page and what information to extract.
* **output\_schema**: *required.* JSON schema defining the structure of data to extract. Follows the standard [JSON schema specification](https://json-schema.org/).
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output will be a JSON value matching the structure specified in the **output\_schema**. The output may also include a `roe_references` field containing screenshot references captured during browsing.
## Example Usage
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **url**: \$url
* **action**: \$action
* **output\_schema**: Copy and paste the JSON schema below:
```json theme={null}
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Main title or heading"
},
"summary": {
"type": "string",
"description": "Brief summary of the content"
},
"key_points": {
"type": "array",
"items": { "type": "string" },
"description": "List of key points extracted"
}
},
"required": ["title", "summary"]
}
```
Hit the **Create** button.
Create a new job and provide:
* **url**: A webpage URL to interact with
* **action**: Instructions like "Extract the main sections and key information from this webpage"
## Use Cases
* **Dynamic content extraction**: Extract data from pages that require JavaScript execution
* **Form interaction**: Navigate through multi-step forms or wizards
* **Authenticated scraping**: Access content behind login pages
* **Single-page applications**: Extract data from React, Vue, or Angular applications
* **Interactive data gathering**: Click through pagination, expand sections, or trigger data loads
# Introduction
Source: https://docs.roe-ai.com/agents/engines/introduction
Extraction and processing engines for structured data transformation
## What are Engines?
Engines are specialized processing tools designed for specific extraction and transformation tasks. Unlike [Agentic Workflows](/agents/agentic-workflows/introduction) that reason and investigate, engines follow deterministic processes to extract, parse, and structure data from documents, images, and web content.
### When to Use Engines
Choose an engine when you need:
* **Fast, predictable extraction** from PDFs, images, or web pages
* **Specific transformations** like document segmentation or URL finding
* **Structured output** from unstructured sources
* **Repeatable processing** with consistent results
For complex investigations requiring reasoning, research, and decision-making, see [Agentic Workflows](/agents/agentic-workflows/introduction).
## Available Engines
Extracts insights and information from PDF documents into structured JSON.
Selects and extracts specific pages from PDF documents.
Extracts location information and nearby places from Google Maps.
Performs interactive web browsing and extracts information from dynamic pages.
Analyzes marketplace storefronts for compliance and quality.
Analyzes merchant risk profiles for underwriting and compliance.
Extracts structured information from text and images using AI vision models.
AI-powered web research to gather and synthesize information.
Scrapes profile information from social media platforms.
Discovers and extracts URLs from web pages and content.
Extracts content and information from web pages.
## Engine Configuration Overview
All engines come with their own configuration settings. The settings defines parameters like which AI model or prompts the Agent will use when running jobs. If your configurations need to be dynamic (changes depending on the job), then you can add as many Agent inputs as you need and use them in the Engine configuration. Check out [Template Strings](/agents/input-definition#template-strings) to see how to do that.
# Marketplace Storefront Analysis
Source: https://docs.roe-ai.com/agents/engines/marketplace-storefront
Analyzes marketplace storefronts for policy compliance and risk assessment.
## Marketplace Storefront Analysis Engine Overview
The Marketplace Storefront Analysis Engine evaluates seller storefronts on marketplace platforms (like Amazon) against configured policies. It scrapes product listings, analyzes content and images, and assesses compliance with policy rules.
## Engine Inputs
The Marketplace Storefront Analysis Engine Configuration has the following parameters:
* **storefront\_url**: *optional.* The marketplace storefront URL to analyze (e.g., Amazon seller page).
* **policy\_version\_id**: *optional.* Policy version ID containing the compliance rules to evaluate against.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output includes a comprehensive storefront analysis:
```json theme={null}
{
"storefront_url": "https://amazon.com/stores/seller",
"risk_assessments": {
"overall_risk_score": 45,
"overall_risk_level": "LOW | MEDIUM | HIGH",
"summary": "Risk assessment summary",
"recommendations": ["Recommendation 1", "Recommendation 2"]
},
"risk_metrics": [
{
"name": "Policy Category",
"score": 60,
"reasoning": "Assessment reasoning",
"verdicts": [
{
"category": "Violation Category",
"findings": ["Finding 1", "Finding 2"],
"references": ["Product URL 1"]
}
]
}
],
"product_categories": ["Electronics", "Home & Garden"]
}
```
## Example Usage
First, create a Policy in the Policies section with your marketplace compliance rules and categories.
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **storefront\_url**: \$storefront\_url
* **policy\_version\_id**: (select your policy version)
Hit the **Create** button.
Create a new job and provide the storefront URL to analyze.
## Analysis Process
The engine performs these steps:
1. **Scrape storefront**: Extract product listings from the marketplace
2. **Extract content**: Gather text and images from products
3. **Policy evaluation**: Assess each policy category against the content
4. **Risk aggregation**: Combine metrics into overall risk assessment
## Use Cases
* **Seller vetting**: Evaluate new sellers before marketplace approval
* **Compliance monitoring**: Ensure sellers meet marketplace policies
* **Quality assessment**: Evaluate product listing quality
* **Brand protection**: Identify potential counterfeit or policy-violating sellers
* **Periodic audits**: Re-evaluate existing seller storefronts
# Merchant Risk Analysis
Source: https://docs.roe-ai.com/agents/engines/merchant-risk
Analyzes merchant risk profiles for underwriting and compliance purposes.
## Merchant Risk Analysis Engine Overview
The Merchant Risk Analysis Engine performs comprehensive risk assessments of merchants for payment processing, underwriting, and compliance purposes. It evaluates business legitimacy, online presence, social media, domain analysis, and potential risk factors.
## Engine Inputs
The Merchant Risk Analysis Engine Configuration has the following parameters:
* **merchant\_url**: *optional.* The merchant's website URL to analyze. Required if merchant\_address is not provided.
* **merchant\_name**: *optional.* The merchant's business name.
* **merchant\_address**: *optional.* The merchant's physical address. If provided without a URL, the engine will search Google Maps to find the official website.
* **risk\_assessment\_config**: *optional.* Configuration for which risk metrics to evaluate.
At least one of **merchant\_url** or **merchant\_address** must be provided.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output includes a comprehensive merchant risk assessment:
```json theme={null}
{
"merchant_info": {
"url": "https://merchant.com",
"social_media_handles": {}
},
"business_details": {
"name": "Merchant Name",
"description": "Business description"
},
"risk_assessments": {
"overall_risk_score": 35,
"overall_risk_level": "LOW | MEDIUM | HIGH",
"summary": "Risk assessment summary",
"recommendations": ["Recommendation 1", "Recommendation 2"]
},
"risk_metrics": [
{
"name": "Metric Name",
"score": 25,
"reasoning": "Assessment reasoning"
}
],
"social_media_analysis": {},
"domain_analysis": {},
"business_litigation_analysis": {},
"product_analysis": {},
"product_categories": ["Category 1", "Category 2"]
}
```
## Example Usage
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **merchant\_url**: \$merchant\_url
* **merchant\_name**: \$merchant\_name
* **merchant\_address**: \$merchant\_address
Hit the **Create** button.
Create a new job and provide merchant information for risk assessment.
## Risk Assessment Areas
The engine evaluates merchants across multiple dimensions:
* **Website Analysis**: Content quality, legitimacy indicators
* **Social Media Presence**: Platform verification, activity patterns
* **Domain Analysis**: Registration history, WHOIS data
* **Business Litigation**: Legal history, court records
* **Product Analysis**: Product legitimacy, pricing patterns
## Use Cases
* **Merchant onboarding**: Assess new merchants before approval
* **Periodic reviews**: Re-evaluate existing merchant risk profiles
* **Compliance monitoring**: Ensure merchants meet regulatory requirements
* **Underwriting decisions**: Support automated underwriting workflows
* **Portfolio risk management**: Assess overall merchant portfolio risk
# Merchant Underwriting
Source: https://docs.roe-ai.com/agents/engines/merchant-underwriting
Evaluates merchant risk and legitimacy for onboarding decisions using SOP-driven analysis
## Merchant Underwriting Engine Overview
The Merchant Underwriting Engine is an agentic workflow that systematically evaluates merchant risk and legitimacy for onboarding decisions. It follows Standard Operating Procedures (SOPs) to analyze every category and flag, performing web research and data gathering to make informed underwriting verdicts.
### Key Capabilities
* **SOP-Driven Analysis**: Systematically evaluates merchants against your underwriting SOP guidelines
* **Automated Evidence Collection**: Performs web research and gathers supporting documentation
* **Category-by-Category Analysis**: Evaluates red flags and green flags per SOP category
* **Structured Verdicts**: Produces underwriting results with clear verdicts from your policy dispositions
## Engine Inputs
The Merchant Underwriting Engine Configuration has the following parameters:
* **policy\_version\_id**: *optional.* The Policy version ID containing your underwriting criteria and guidelines (SOP).
* **merchant\_context**: *required.* Merchant name and any additional context or information about the merchant to underwrite.
* **images**: *optional.* Image URLs or file IDs (comma/newline/whitespace separated) for visual analysis.
* **documents**: *optional.* Document URLs or file IDs (comma/newline/whitespace separated) for document review.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output is a structured JSON object containing:
### Policy Applied
Information about the SOP policy used for underwriting:
* `name`: Name of the policy applied
* `version`: Version ID of the policy applied
### Underwriting Result
Complete underwriting analysis including:
| Field | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `verdict` | Final underwriting decision from policy dispositions (e.g., "APPROVED", "DENIED", "FURTHER\_REVIEW\_NEEDED") |
| `summary` | Executive summary explaining the decision and key findings |
| `summary_evidences` | Evidence objects with web links, screenshots, and artifacts supporting the summary |
| `investigation_findings` | Detailed analysis of each rule/flag from the SOP with reasoning and evidence |
### Investigation Findings Structure
For each rule evaluated, the output includes:
* `rule_title`: Title of the SOP rule
* `rule_description`: Description from the policy
* `hit`: Boolean indicating if this rule was triggered
* `reasoning`: Explanation of the evaluation
* `evidence_references`: References to supporting evidence
### Evidence Structure
Each piece of evidence includes:
* `evidence_type`: "web\_link", "screenshot", or "artifact"
* `evidence_data`: URL or artifact reference
* `evidence_name`: Short descriptive name
* `evidence_description`: Why this evidence is relevant
## Creating an Underwriting Policy
The Merchant Underwriting Engine requires a policy containing your Standard Operating Procedures. You can create policies using the [Policies](/policies/introduction) feature.
### Policy Structure
Your underwriting policy should contain:
1. **Instructions**: High-level guidance on merchant evaluation approach
2. **Guidelines**: Organized as Categories > Rules
* Each Category (e.g., "BUSINESS\_LEGITIMACY", "FINANCIAL\_STABILITY") contains multiple Rules
* Each Rule has a `flag` type (GREEN\_FLAG or RED\_FLAG), `title`, and `description`
3. **Dispositions**: Classification options for final verdicts (e.g., "Approved", "Denied", "Further Review")
## How It Works
The Merchant Underwriting Engine autonomously:
1. **Loads the SOP** - Retrieves and parses your underwriting policy
2. **Plans investigation** - Creates a systematic plan to evaluate each SOP category
3. **Gathers information** - Performs web research, analyzes documents and images
4. **Evaluates flags** - Checks each red flag and green flag against gathered evidence
5. **Makes decision** - Produces a verdict based on SOP dispositions with full evidence trail
## Example Usage
First, create a Policy in the Policies section with your underwriting criteria, red/green flags, and decision dispositions.
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **policy\_version\_id**: (select your policy version)
* **merchant\_context**: \$merchant\_context
* **images**: \$images (optional)
* **documents**: \$documents (optional)
Hit the **Create** button.
Create a new job and provide merchant information to evaluate. The agent will systematically analyze the merchant against your SOP and provide a structured underwriting decision.
## Use Cases
* **Merchant onboarding**: Evaluate new merchants for payment processing or marketplace approval
* **Risk assessment**: Systematically assess merchant risk factors against your criteria
* **Compliance review**: Ensure merchants meet regulatory and business requirements
* **Portfolio monitoring**: Re-evaluate existing merchants based on updated SOPs
# Multimodal Insights
Source: https://docs.roe-ai.com/agents/engines/multimodal-extraction
Extracts insights and structured information from text and images using AI vision models.
## Multimodal Insights Engine Overview
The Multimodal Insights Engine is a unified engine that can extract structured information from both text and images. It replaces the previous separate Text Insights and Image Insights engines, providing a single powerful interface for multimodal content analysis.
## Engine Inputs
The Multimodal Insights Engine Configuration has the following parameters:
* **text**: *optional.* Text content to analyze and extract information from. Leave blank to extract from images only.
* **images**: *optional.* Image URLs or file IDs (comma/newline/whitespace separated). Leave blank to extract from text only.
* **instruction**: *optional.* Instructions describing what to extract from the content. Defaults to empty.
* **model**: *optional.* The AI model to use (default: `gpt-4.1-2025-04-14`).
* **reasoning**: *optional.* Reasoning effort level for the model. Options: `low`, `medium`, `high`.
* **output\_schema**: *required.* JSON schema defining the structure of data to extract. Follows the standard [JSON schema specification](https://json-schema.org/).
At least one of **text** or **images** must be provided.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output will be a JSON value matching the structure specified in the **output\_schema**.
## Text Extraction Example
Extract structured information from text content:
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **text**: \$text
* **images**: (leave empty)
* **instruction**: Analyze the text to extract key information and insights
* **model**: gpt-4.1-2025-04-14
* **output\_schema**: Copy and paste the JSON schema below:
```json theme={null}
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Main title or heading"
},
"summary": {
"type": "string",
"description": "Brief summary of the content"
},
"key_points": {
"type": "array",
"items": { "type": "string" },
"description": "List of key points extracted"
}
},
"required": ["title", "summary"]
}
```
Hit the **Create** button.
Create a new job and provide text content to analyze. The engine will extract structured information based on your output schema.
## Image Extraction Example
Extract structured information from images:
Click on the "Add Agent" button and enter a name for your Agent.
\$ starts a template string
* **text**: (leave empty)
* **images**: \$images
* **instruction**: Analyze the image and describe what you see in detail
* **model**: gpt-4.1-2025-04-14
* **output\_schema**: Copy and paste the JSON schema below:
```json theme={null}
{
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Detailed description of the image content"
},
"objects": {
"type": "array",
"items": { "type": "string" },
"description": "List of objects identified in the image"
},
"text_content": {
"type": "string",
"description": "Any text visible in the image"
}
},
"required": ["description"]
}
```
Hit **Create**, then run a job by providing an image URL to analyze.
## Combined Text and Image Analysis
You can also provide both text and images for combined analysis. The engine will process both modalities together.
# Document Insights
Source: https://docs.roe-ai.com/agents/engines/pdf-extraction
Extracts insights and structured information from PDF documents using AI.
## Document Insights Engine Overview
The Document Insights Engine extracts structured information, insights, and data from PDF documents using AI. It processes documents in batches, supports schema-based extraction, source tracing, and handles multi-page documents efficiently.
## Engine Inputs
The Document Insights Engine Configuration has the following parameters:
* **instructions**: *required.* Instructions for the AI describing what to extract from the PDF. Can also use alias `instruction`.
* **pdf\_files**: *required.* PDF files to extract insights from. Can be file uploads, URLs, or file IDs. Supports multiple files (comma/newline separated). Can also use alias `pdf_file`.
* **batch\_size**: *optional.* Number of PDF pages to process in each batch (default: 10, range: 1-50). Larger batches are faster but may affect quality.
* **model**: *optional.* The AI model to use (default: `gpt-4.1-2025-04-14`).
* **temperature**: *optional.* Controls randomness in output (default: 0.0). Range: 0.0 (deterministic) to 1.0 (most random).
* **use\_source**: *optional.* Trace the sources of extracted data (default: False). Adds cost when enabled.
* **convert\_to\_images**: *optional.* Convert PDF pages to images and send to the model along with text (default: True). Improves extraction for visual documents.
* **output\_schema**: *optional.* JSON schema defining the structure of data to extract. Follows the standard [JSON schema specification](https://json-schema.org/).
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output will be a JSON value matching the structure specified in the **output\_schema** (if defined). Without a schema, returns extracted content in a default format.
## Example Usage
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **instructions**: \$instructions
* **pdf\_files**: \$pdf\_files
* **batch\_size**: 10
* **model**: gpt-4.1-2025-04-14
* **temperature**: 0.0
* **convert\_to\_images**: True
* **output\_schema**: Copy and paste the JSON schema below:
```json theme={null}
{
"type": "array",
"items": {
"type": "object",
"properties": {
"row_name": {
"type": "string",
"description": "The name of a row"
},
"value_1": {
"type": "string",
"description": "The monetary value for the first period"
},
"value_2": {
"type": "string",
"description": "The monetary value for the second period"
},
"type": {
"type": "string",
"description": "Asset type classification"
}
},
"description": "A row in the financial statement"
},
"description": "All entries from the financial statement table"
}
```
You can click **Use Widget** to view the JSON schema in the UI.
![]()
Hit the **Create** button.
Create a new job and provide:
* **instructions**: "Extract all rows from the ASSETS table in the balance sheet"
* **pdf\_files**: Upload or provide a URL to a PDF document
![]()
Click **View** on the job to see its status and results.
![]()
Scroll down to see the extracted data matching your output schema.
![]()
# Product Policy
Source: https://docs.roe-ai.com/agents/engines/product-policy
Analyzes product listings against policy rules for compliance violations.
## Product Policy Engine Overview
The Product Policy Engine is an agentic workflow that autonomously analyzes product listings against policy guidelines. It intelligently decides which tools to use (web research, recall databases, etc.) based on the product type and automatically gathers evidence to make informed compliance decisions.
## Engine Inputs
The Product Policy Engine Configuration has the following parameters:
* **product\_listing**: *required.* The product listing text/content to analyze for policy compliance. Can include text descriptions, URLs, or any product information.
* **product\_images**: *optional.* Image URLs to analyze for policy compliance (comma/newline/whitespace separated).
* **policy\_version\_id**: *required.* The Policy version ID containing the compliance rules to evaluate against.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output includes a comprehensive compliance investigation result:
```json theme={null}
{
"policy_applied": {
"name": "Product Policy Name",
"version": "policy-version-id"
},
"compliance_result": {
"verdict": "APPROVED | DENIED | FURTHER_REVIEW_NEEDED",
"summary": "Executive summary of the compliance analysis with key findings",
"summary_evidences": [
{
"reference": "$REF_1$",
"evidence_type": "web_link | screenshot | artifact",
"evidence_data": "URL or artifact reference",
"evidence_name": "Short name",
"evidence_description": "Why this evidence is relevant"
}
],
"investigation_findings": [
{
"rule_title": "Policy Rule Title",
"rule_description": "Rule description from policy",
"hit": true,
"reasoning": "Explanation of why this rule was triggered",
"evidence_references": ["$REF_1$", "$REF_2$"]
}
]
}
}
```
## Example Usage
First, create a Policy in the Policies section with your compliance rules and guidelines.
Click on the "Add Agent" button in the top right corner of the Agents page.
Enter a name and an optional description of your Agent.
\$ starts a template string
* **product\_listing**: \$product\_listing
* **product\_images**: \$product\_images
* **policy\_version\_id**: (select your policy version)
Hit the **Create** button.
Create a new job and provide the product listing content to analyze.
## How It Works
The Product Policy Engine is an agentic workflow that autonomously:
1. **Analyzes the product listing** - Extracts key information from text and images
2. **Decides which tools to use** - Based on product type, may check recall databases, perform web research, or gather regulatory information
3. **Evaluates against policy rules** - Systematically checks each rule in your policy guidelines
4. **Collects evidence** - Gathers web links, screenshots, and data to support findings
5. **Makes compliance determination** - Provides a verdict with reasoning and evidence references
## Use Cases
* **Marketplace compliance**: Ensure product listings meet marketplace policies before approval
* **Regulatory compliance**: Automatically check products against safety regulations
* **Content moderation**: Evaluate listings for prohibited content or misleading claims
* **Quality assurance**: Assess product descriptions for accuracy and completeness
# Research Agent
Source: https://docs.roe-ai.com/agents/engines/research
Performs AI-powered web research to gather and synthesize information on any topic.
## Research Agent Engine Overview
The Research Agent Engine leverages AI-powered search providers to conduct comprehensive web research. It can search the web, synthesize information from multiple sources, and return structured insights with source citations.
## Engine Inputs
The Research Agent Engine Configuration has the following parameters:
* **prompt**: *required.* The research query or question to investigate.
* **provider**: *optional.* The search provider to use (default: `perplexity`). Options:
* `perplexity`: Perplexity AI search (general web, conversational)
* `exa`: Exa AI-powered semantic search (structured/academic)
* **use\_deep\_search**: *optional.* Enable deep search for more comprehensive results (default: False). Higher cost but more thorough.
* **include\_sources**: *optional.* Include source URLs in the response (default: True).
* **output\_schema**: *optional.* JSON schema for structured response format. For Exa, providing a schema routes to the Research API; for Perplexity, schemas work with standard or deep search.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output includes researched information with optional source citations. When an output schema is defined, the response will match that structure.
## Example Usage
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **prompt**: \$prompt
* **provider**: perplexity
* **use\_deep\_search**: False
* **include\_sources**: True
* **output\_schema**: Copy and paste the JSON schema below:
```json theme={null}
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Main title or heading"
},
"summary": {
"type": "string",
"description": "Brief summary of the research findings"
},
"key_points": {
"type": "array",
"items": { "type": "string" },
"description": "List of key points from the research"
}
},
"required": ["title", "summary"]
}
```
Hit the **Create** button.
Create a new job and provide a research prompt like:
* "What are the latest developments in AI-powered document processing?"
* "Research the competitive landscape for enterprise data warehouses"
## Search Providers
| Provider | Description | Best For |
| ---------- | ---------------------------------- | ---------------------------------------------- |
| Perplexity | Conversational AI search (default) | General research, complex questions |
| Exa | AI-powered semantic search | Structured/academic research, technical topics |
## Use Cases
* **Market research**: Gather competitive intelligence and market trends
* **Due diligence**: Research companies, products, or individuals
* **Content creation**: Gather source material for articles and reports
* **Fact-checking**: Verify claims with web sources
* **Technical research**: Find documentation, tutorials, and best practices
# Social Media Crawler
Source: https://docs.roe-ai.com/agents/engines/social-media-crawler
Scrapes profile information and content from social media platforms.
## Social Media Crawler Engine Overview
The Social Media Crawler Engine extracts profile information and content from various social media platforms.
## Engine Inputs
The Social Media Crawler Engine Configuration has the following parameters:
* **profile\_url**: *required.* URL or handle of the social media profile to scrape.
* **platform**: *optional.* The social media platform to scrape (default: `LinkedIn`). Options:
* `Instagram`
* `X`
* `TikTok`
* `Facebook`
* `Pinterest`
* `Youtube`
* `Yelp`
* `TrustPilot`
* `LinkedIn`
* **max\_posts**: *optional.* Maximum number of posts to retrieve (default: 5, range: 1-100).
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output will be a JSON value containing structured information from the social media profile. The specific data returned varies by platform and may include:
* Profile name and headline/bio
* Profile description
* Posts and content
* Follower/subscriber counts
* Platform-specific profile information
The availability of data depends on the platform's privacy settings and terms of service. Some profiles may have limited information available for scraping.
## Example Configuration
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **profile\_url**: \$profile\_url
* **platform**: LinkedIn
* **max\_posts**: 5
Hit the **Create** button.
Create a new job and provide a social media profile URL to scrape. The engine will return structured profile data.
# Web Insights
Source: https://docs.roe-ai.com/agents/engines/url-extraction
Extracts insights and structured information from URLs
## Web Insights Engine Overview
The Web Insights Engine extracts structured information, insights, and content from websites by crawling URLs. It supports vision mode for visual analysis, custom extraction instructions, and schema-based output formatting. Can handle Reddit URLs and Amazon product pages through specialized extraction.
## Engine Inputs
The Web Insights Engine Configuration has the following parameters:
### Core Parameters
* **url**: *required.* The website URL you want to extract information from.
* **instruction**: *required (in AI extraction mode).* Instructions for AI to analyze and extract data from the webpage.
* **output\_schema**: *required (in AI extraction mode).* JSON schema defining the structure of data to extract. Follows the standard [JSON schema specification](https://json-schema.org/).
* **model**: *optional.* The AI model to use (default: `gpt-5.1-2025-11-13`).
* **vision\_mode**: *optional.* Enable visual analysis of the webpage screenshot in addition to text content (default: False).
### Crawl Configuration
The **crawl\_config** object provides advanced settings for how the website should be crawled:
* **crawling\_only**: *optional.* Skip AI extraction and return raw scraped content (default: False). When enabled, `instruction` and `output_schema` are not required.
* **min\_wait\_time\_sec**: *optional.* Time to wait for page to load in seconds (default: 0, range: 0-60).
* **save\_html**: *optional.* Save the original HTML source code (default: False).
* **save\_markdown**: *optional.* Save a clean, formatted markdown version of the webpage content (default: False).
* **save\_screenshot**: *optional.* Capture a visual screenshot of the webpage (default: False).
* **collect\_web\_analytics**: *optional.* Capture network request/response data in HAR format (default: False).
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output will be a JSON value matching the structure specified in the **output\_schema**. When `crawling_only` is enabled, returns the raw scraped content instead.
## Web Insights Example
Let's run through an example using this engine together.
Click on the "Add Agent" button in the
top right corner of the Agents page.
![]()
\$ starts a template string
* **url**: \$
* **instruction**: \$
* **model**: gpt-5.1-2025-11-13
* **vision\_mode**: False
* **output\_schema**: Copy and paste the JSON schema below (hit **Use Text**).
```json theme={null}
{
"type": "object",
"properties": {
"moon": {
"type": "string",
"description": "Which moon is the article talking about"
},
"planet": {
"type": "string",
"description": "Which planet does the moon in question belong to"
},
"summary": {
"type": "string",
"description": "Summary of the article"
}
}
}
```
You can click **Use Widget** to then view the JSON schema in the UI.
![]()
Hit the **Create Agent** button. Now, let's run it on a URL through the UI.
![]()
Leave **instruction** empty.
**url**: [https://en.wikipedia.org/wiki/Europa\_Clipper](https://en.wikipedia.org/wiki/Europa_Clipper)
Here are the filled-in Agent inputs:
![]()
Hit the **Create** button at the bottom to start the Web Insights
job.
Click on the job to view its status and results.
![]()
You'll see the results on the right side.
![]()
Notice that, as expected, the **JSON output only contains the information we defined in the output\_schema**.
# URL Finder
Source: https://docs.roe-ai.com/agents/engines/url-finder
Searches for relevant URLs using text search, reverse image lookup, or both.
## URL Finder Engine Overview
The URL Finder Engine searches for the most relevant URLs using text-based Google Search, reverse image lookup via Google Lens, or both. It returns URLs with titles, snippets, and AI-scored relevance ratings.
## Engine Inputs
The URL Finder Engine Configuration has the following parameters:
* **search\_term**: *optional.* Search engine query to find relevant URLs. Required if search\_image is not provided.
* **search\_image**: *optional.* Image URL (http/https) or file identifier (file\_\*) for reverse image lookup using Google Lens. When provided, performs visual search.
* **description**: *required.* Description of the target URLs to be included in the search results. Used to score relevance.
* **search\_limit**: *optional.* Maximum number of search results to analyze (default: 5, range: 1-100).
* **top\_results**: *optional.* Number of best matching URLs to return (default: 1, range: 1-100). Must be less than or equal to search\_limit.
* **model**: *optional.* The AI model to use for relevance scoring (default: `gpt-5.1-2025-11-13`).
At least one of **search\_term** or **search\_image** must be provided.
See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.
## Engine Output
The output is a structured list of discovered URLs with metadata:
```json theme={null}
{
"urls": [
{
"url": "https://example.com/page",
"title": "Page Title",
"snippet": "Brief description from search results",
"score": 0.95
}
]
}
```
## Example Usage
Click on the "Add Agent" button in the top right corner of the Agents page.
![]()
Enter a name and an optional description of your Agent.
\$ starts a template string
* **search\_term**: \$search\_term
* **description**: Find the official product page for this item
* **search\_limit**: 10
* **top\_results**: 3
Hit the **Create** button.
Create a new job and provide a search term or image to find relevant URLs.
## Use Cases
* **Product matching**: Find product pages matching a description or image
* **Reverse image search**: Find the source of an image using Google Lens
* **Web crawling**: Discover relevant pages for further processing
* **Content discovery**: Find pages matching specific criteria
* **Data pipeline input**: Generate URL lists for batch processing with other engines
# Input Definitions
Source: https://docs.roe-ai.com/agents/input-definition
Define the inputs that your Agent will accept
## Overview
![]()
Each **Agent** can have a set of inputs that it accepts. These inputs can be
used as parameters for the **Engine Configuration** or provide data to the **Engine** powering the
**Agent**.
You can define the inputs that your Agent will accept by defining a required
**key** to identify the input and the **data type** of that input.
## Template Strings
Once the inputs are defined, you can use the keys in the
**Engine Configuration** to fill in the configurations. This allows you to
dynamically set the configurations based on the inputs provided to the Agent
at runtime.
To use the keys in the Engine Configuration, you can reference them using
template strings. For example, if you have an input key `prompt`, you can
use `${prompt}` or `$prompt` in the Engine Configuration to reference
the value of the `prompt` input.
![]()
You can use multiple keys in one configuration. For example, if you have two
input keys `prompt1` and `prompt2`, you can use them in the configuration
like this `${prompt1} ${prompt2}`.
![]()
In this case if `prompt1` is `summarize the document` and `prompt2` is
`provide a list of speakers`, at runtime, the configuration will be filled
with
```
Please follow the instruction: summarize the document and provide a list
of speakers
```
## Types of Inputs
Each input and engine configuration can have a specific set of data types. The
agent input used in the engine configuration should match the types required.
Only text-based inputs and configurations support multiple keys in one
configuration. For all other types, only one key can be used in one
configuration and any other text in the configuration will be ignored.
# Introduction
Source: https://docs.roe-ai.com/agents/introduction
Start building powerful data processing Agents in under 5 minutes
A Roe Agent is designed to perform various data-related tasks. Each Agent is
powered by either an Engine or an Agentic Workflow. Engines handle specific extraction and processing tasks, while Agentic Workflows are autonomous agents that reason, research, and make complex decisions.
Build a Roe Agent to process your unstructured data.
Extraction and processing engines for structured data transformation.
Autonomous agents that reason, research, and make decisions.
## What is a Roe Agent?
You can think of an Agent as a data processing worker. Each Agent can
be configured to perform a specific task on your data based on the
[Engine](/agents/engines/introduction) or [Agentic Workflow](/agents/agentic-workflows/introduction) you choose.
### Engines
[Engines](/agents/engines/introduction) are specialized tools for specific extraction and transformation tasks. They follow deterministic processes to extract, parse, and structure data. For example, the [Multimodal Extraction Engine](/agents/engines/multimodal-extraction) extracts structured information from text and images.
### Agentic Workflows
[Agentic Workflows](/agents/agentic-workflows/introduction) are autonomous agents that can reason about complex problems, conduct research, query databases, and make sophisticated decisions. For example, the [Fraud Investigation Engine](/agents/engines/fraud-investigation) investigates fraud alerts by analyzing transaction data and external intelligence to produce structured verdicts.
## What is an Agent Job?
An Agent Job is one execution of an Agent. When you run an Agent, it creates an
Agent Job. You can check the status of the job through the UI, API, or by using
the [job\_status](/database/functions/job-status) function in
[SQL workspace](/database/introduction).
# JSON Output Schema
Source: https://docs.roe-ai.com/agents/output-schema-json
Define the structure of the JSON output
Many Engines support definition of the JSON output schema. This allows you to
control the structure of the JSON output exactly as you wish. The schema follows
the standard [JSON schema specification](https://json-schema.org/).
We support creation of the schema using our UI Widget. Or you can paste the raw
JSON schema in Text mode.
![]()
# Prompt Engineering Guide
Source: https://docs.roe-ai.com/agents/prompt-engineering
How to create prompts effectively for your Agents
## Include details in your query to get more relevant answers
In order to get a highly relevant response, make sure that requests provide any
important details or context. Otherwise you are leaving it up to the model to
guess what you mean. This is especially important when working with domain
specific requests.
| Worse | Better |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Summarize the meeting notes. | Summarize the meeting notes in a single paragraph. Then write a markdown list of the speakers and each of their key points. Finally, list the next steps or action items suggested by the speakers, if any. |
| Get the total. | Extract the total sales amount from the financial report table in the document. The table lists monthly sales for each product category. Summarize the total sales amount for the entire year across all categories. |
## Provide Examples
Also known as "few-shot" prompting, providing examples is the most common way to
prompt a model. This is especially useful when you want to get a specific type
of response. For example, if you want to get a summary of a document, you can
provide a few examples of the type of summaries you want to get.
## Give models time to "think"
If asked to multiply 17 by 28, you might not know it instantly, but can still
work it out with time. Similarly, models make more reasoning errors when trying
to answer right away, rather than taking time to work out an answer. Asking for
a "chain of thought" before an answer can help the model reason its way toward
correct answers more reliably.
For example, if you ask an agent to classify a document, you can ask it to also
provide the reasons for its classification. This can help the agent to provide a
more accurate classification.
Practically, to apply this in our agents with `output_schema` configuration, you
can ask the agent to output a reasoning entity first, and then a classification
entity.
For example:
```
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Is it good or bad? Give your comprehensive reasoning."
},
"classification": {
"type": "boolean",
"description": "true if good, false if bad"
}
}
}
```
works better than:
```
{
"type": "object",
"properties": {
"classification": {
"type": "boolean",
"description": "true if good, false if bad"
},
"reason": {
"type": "string",
"description": "Is it good or bad? Give your comprehensive reasoning."
}
}
}
```
## Split complex tasks into simpler subtasks
If you have a complex task, it is often better to split it into simpler
subtasks. This makes it easier for the agent to understand what you are asking,
and it also forces the agent to "think" about the task in a structured way.
For example, if you want to extract information from a document which requires
multiple steps, you can split the task by asking the agent to extract the
intermediate results, and then use those results to extract the final result.
## Other Resources
* [OpenAI's Prompting Resources Index](https://cookbook.openai.com/articles/related_resources)
# Quickstart
Source: https://docs.roe-ai.com/agents/quickstart
Build your first Roe Agent in under 5 minutes
## Build an Image Extraction Agent
Each Roe Agent uses an Engine that defines which tasks this agent will tackle.
Our built-in [Engines](/agents/engines/introduction) are optimized for their
respective functions. In this example, we will use our
[Image Extraction Engine](/agents/engines/multimodal-extraction) to extract data from
images.
Click on the "Add Agent" button in the
top right corner of the Agents page.
![]()
Select the Image Extraction Engine.
![]()
Configure the **Agent Inputs** and **Engine Configurations**.
![]()
* **Agent Input Definition**: Defines the inputs that your Agent must
accept when running a job. You can define the input key and its type as well as add or remove inputs. All defined inputs must be passed in a value when running the Agent. Learn more
about [Input Definitions](/agents/input-definition).
![]()
* **Engine Configuration**: Configurations specific
to your selected Engine. This sets things like which AI model or prompt instructions the Agent will use when running jobs. You can also dyanmically define the Engine configurations at runtime by using template strings of the Agent input keys. Learn more about configuring
[Engines](/agents/engines/introduction).
![]()
Hit the **Create** button. Woohoo, you just built your first Agent! Now, let's run it.
## Run Your Image Extraction Agent
There are three ways to run your Agent:
* UI
* [Agent API](/api-reference/agents/run)
* [Roe SQL](/database/functions/run-agent.mdx)
We will run the agent through the UI:
![]()
![]()
Paste in the following text for the **instruction** input field:
````
Describe the image in one sentence.
Output in the following structure:
```
{
"description": ""
}
```
````
Then pick an image to upload to the **image** input field. You can use the one below.
![]()
Here is the filled-in Agent inputs:
![]()
Hit the **Create** button at the bottom. Hell yeah, your first Agent job has been kicked off!
## View Results
You can view the status of your Agent job in its details page.
![]()
Click **view** to check the job result.
![]()
## Improve Your Agents' Results
* [Prompt Engineering](/agents/prompt-engineering)
* [Define Output Schema](/agents/output-schema-json)
# Create Agent
Source: https://docs.roe-ai.com/api-reference/agents/create-agent
POST /v1/agents/
Create a new base agent.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/agents/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "My New Agent",
"description": "Agent description"
}'
```
# Create Agent Version
Source: https://docs.roe-ai.com/api-reference/agents/create-agent-version
POST /v1/agents/{agent_id}/versions/
Create a new version of an existing agent.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/versions/" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"prompt": "New version prompt",
"description": "Version description"
}'
```
# Delete an Agent
Source: https://docs.roe-ai.com/api-reference/agents/delete-agent
DELETE /v1/agents/{agent_id}/
Delete a specific base agent.
```bash cURL theme={null}
curl --request DELETE \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Duplicate an Agent
Source: https://docs.roe-ai.com/api-reference/agents/duplicate-agent
POST /v1/agents/{agent_id}/duplicate/
Create a new agent with the same attributes as the current version of the specified agent.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/duplicate/" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Duplicated Agent Name"
}'
```
# Agent Job Result
Source: https://docs.roe-ai.com/api-reference/agents/job-result
GET /v1/agents/jobs/{agent_job_id}/result/
Get agent job result data. If the output references artifact keys (e.g. `evidence_data` values), fetch their full content via GET /v1/agents/jobs/{agent_job_id}/artifacts/result/?artifact_key=.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/jobs/YOUR_JOB_ID/result/" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Agent Job Status
Source: https://docs.roe-ai.com/api-reference/agents/job-status
GET /v1/agents/jobs/{job_id}/status/
Get agent job status.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/jobs/YOUR_JOB_ID/status/" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# List Agent's Jobs
Source: https://docs.roe-ai.com/api-reference/agents/list-agent-jobs
GET /v1/agents/{agent_id}/jobs/
Retrieve a list of jobs for a specific agent or create a new job
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/jobs/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# List Agent Versions
Source: https://docs.roe-ai.com/api-reference/agents/list-agent-versions
GET /v1/agents/{agent_id}/versions/
Retrieve a list of versions for a specific agent.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/versions/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# List Agents
Source: https://docs.roe-ai.com/api-reference/agents/list-agents
GET /v1/agents/
Retrieve a list of agents or create a new agent.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Retrieve an Agent
Source: https://docs.roe-ai.com/api-reference/agents/retrieve-agent
GET /v1/agents/{agent_id}/
Retrieve details of a specific base agent.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Retrieve Current Agent Version
Source: https://docs.roe-ai.com/api-reference/agents/retrieve-agent-current-version
GET /v1/agents/{agent_id}/versions/current/
Retrieve details of the current version of a specific agent.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/versions/current/" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Retrieve an Agent Version
Source: https://docs.roe-ai.com/api-reference/agents/retrieve-agent-version
GET /v1/agents/{agent_id}/versions/{agent_version_id}/
Retrieve details of a specific agent version.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/versions/YOUR_VERSION_ID/" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Run Agent
Source: https://docs.roe-ai.com/api-reference/agents/run
POST /v1/agents/run/{agent_id}/
Execute an agent with provided inputs and return results immediately.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/agents/run/YOUR_AGENT_ID/" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"inputs": {
"key": "value"
}
}'
```
# Run Agent Async
Source: https://docs.roe-ai.com/api-reference/agents/run-async
POST /v1/agents/run/{agent_id}/async/
Run agent asynchronously. Returns agent job id which can be used to check status and get results.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/agents/run/YOUR_AGENT_ID/async/" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"inputs": {
"key": "value"
}
}'
```
# Update an Agent's Settings
Source: https://docs.roe-ai.com/api-reference/agents/update-agent-settings
PUT /v1/agents/{agent_id}/
Update a base agent's settings.
```bash cURL theme={null}
curl --request PUT \
--url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Updated Agent Name",
"description": "Updated description"
}'
```
# Run Query
Source: https://docs.roe-ai.com/api-reference/database/query
POST /v1/database/query/
Execute a query synchronously and return results.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/database/query/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"query": "SELECT * FROM my_table LIMIT 10"
}'
```
# Run Query Async
Source: https://docs.roe-ai.com/api-reference/database/query-async
POST /v1/database/query/async/
Execute a query asynchronously and return query object.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/database/query/async/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"query": "SELECT * FROM my_table LIMIT 10"
}'
```
# Query Result
Source: https://docs.roe-ai.com/api-reference/database/query-result
GET /v1/database/query/{worksheet_query_id}/result/
Get the results of a query.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/database/query/YOUR_QUERY_ID/result/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Query Status
Source: https://docs.roe-ai.com/api-reference/database/query-status
GET /v1/database/query/{worksheet_query_id}/status/
Get the status of a query.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/database/query/YOUR_QUERY_ID/status/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Examples
Source: https://docs.roe-ai.com/api-reference/examples
API Examples
## Run a batch of jobs and get the job statuses
All API endpoints are authenticated using Bearer tokens which you can find under `Settings` on the platform.
```python batch_job_runner.py [expandable] theme={null}
import argparse
import json
import os
import requests
import time
from pathlib import Path
def run_agent_async(api_key, agent_id, file_path):
"""Run an agent asynchronously with a file input."""
url = f"https://api.roe-ai.com/v1/agents/run/{agent_id}/async/"
headers = {"Authorization": f"Bearer {api_key}"}
# Upload file directly
with open(file_path, "rb") as f:
files = {"pdf_file": (os.path.basename(file_path), f, "application/pdf")}
response = requests.post(url, headers=headers, files=files)
if response.status_code == 200:
job_id = response.json()
print(f"Started job {job_id} for file: {os.path.basename(file_path)}")
return job_id
else:
print(
f"Failed to start job for {file_path}: {response.status_code} - {response.text}"
)
return None
def get_job_status(api_key, job_id):
"""Get the status of a job."""
url = f"https://api.roe-ai.com/v1/agents/jobs/{job_id}/status/"
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response.json()
else:
print(f"Failed to get status for job {job_id}: {response.status_code}")
return None
def is_job_complete(status_code):
"""Check if job is in terminal state."""
terminal_states = {3, 4, 5, 6} # 3: SUCCESS, 4: FAILURE, 5: CANCELLED, 6: CACHED
return status_code in terminal_states
def poll_jobs_until_complete(api_key, job_ids, poll_interval=5):
"""Poll job statuses until all jobs are complete."""
job_statuses = {}
completed_jobs = set()
print(f"Polling {len(job_ids)} jobs every {poll_interval} seconds...")
while len(completed_jobs) < len(job_ids):
for job_id in job_ids:
if job_id in completed_jobs:
continue
status_info = get_job_status(api_key, job_id)
if status_info:
status_code = status_info.get("status")
job_statuses[job_id] = status_info
if is_job_complete(status_code):
completed_jobs.add(job_id)
print(f"Job {job_id} completed with status {status_code}")
else:
print(f"Job {job_id} still running (status: {status_code})")
if len(completed_jobs) < len(job_ids):
time.sleep(poll_interval)
print("All jobs completed!")
return job_statuses
def get_files_from_folder(folder_path):
"""Get all files from the specified folder."""
folder = Path(folder_path)
if not folder.exists():
print(f"Folder does not exist: {folder_path}")
return []
files = [f for f in folder.iterdir() if f.is_file()]
print(f"Found {len(files)} files in {folder_path}")
return files
def main():
parser = argparse.ArgumentParser(
description="Run Roe agent jobs on files in a folder"
)
parser.add_argument("--api-key", required=True, help="Roe API key")
parser.add_argument("--agent-id", required=True, help="Agent ID to run")
parser.add_argument("--folder", required=True, help="Folder containing input files")
args = parser.parse_args()
# Get files from folder
files = get_files_from_folder(args.folder)
if not files:
print("No files found to process")
return
print(f"Starting jobs for {len(files)} files...")
# Start all jobs
job_ids = []
for file_path in files:
job_id = run_agent_async(args.api_key, args.agent_id, file_path)
if job_id:
job_ids.append(job_id)
if not job_ids:
print("No jobs were started successfully")
return
# Poll until all jobs complete
final_results = poll_jobs_until_complete(args.api_key, job_ids)
# Print results
print("\nFinal Results:")
print("-" * 50)
for job_id, status_info in final_results.items():
print(f"Job ID: {job_id}")
print(f" Status: {status_info.get('status')}")
print(f" Timestamp: {status_info.get('timestamp')}")
# Print job status map
print("\nJob Status Map:")
job_status_map = {
job_id: info.get("status") for job_id, info in final_results.items()
}
print(json.dumps(job_status_map, indent=2))
if __name__ == "__main__":
main()
```
# Overview
Source: https://docs.roe-ai.com/api-reference/go-sdk-introduction
Official Go SDK for Roe
# Go SDK
The official Go SDK for interacting with the Roe API. Build high-performance data extraction and processing workflows with Go's concurrency and type safety.
## Installation
```bash theme={null}
go get github.com/roe-ai/roe-golang
```
## Requirements
* Go >=1.23
## Resources
* [Go Package](https://pkg.go.dev/github.com/roe-ai/roe-golang)
* [GitHub Repository](https://github.com/roe-ai/roe-golang)
* [Report Issues](https://github.com/roe-ai/roe-golang/issues)
# Examples
Source: https://docs.roe-ai.com/api-reference/go-sdk-reference
Copy-ready examples for calling Roe with the Go SDK.
## SDK operations
Copy-ready calls for each operation available through this SDK. Required and
optional inputs are shown inline in the code.
### Agents
#### `agents_list`
List agents or create a new agent.
```go theme={null}
result, err := client.Agents.List(
1,
1,
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_create`
Create a new base agent.
```go theme={null}
result, err := client.Agents.Create(
"name",
"engineClassID",
[]map[string]any{{"key": "text", "data_type": "text/plain"}},
map[string]any{"model": "gpt-5.5-2026-04-23"},
"versionName",
"description",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_results_create`
Get results for multiple agent jobs
```go theme={null}
result, err := client.Agents.Jobs.RetrieveResultMany([]string{"job_id"})
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_statuses_create`
Get status for multiple agent jobs
```go theme={null}
result, err := client.Agents.Jobs.RetrieveStatusMany([]string{"job_id"})
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_artifacts_result_retrieve`
Get tool result artifact (result only)
```go theme={null}
result, err := client.Agents.Jobs.RetrieveArtifact(
"jobID",
"artifactKey",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_references_retrieve`
Serve a reference file associated with an agent job.
```go theme={null}
content, err := client.Agents.Jobs.DownloadReference(
"job_id",
"resource_id",
false,
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_result_retrieve`
Get agent job result data.
```go theme={null}
result, err := client.Agents.Jobs.RetrieveResult(
"jobID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_cancel_create`
Cancel an agent job
```go theme={null}
err := client.Agents.Jobs.Cancel(
"jobID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_delete_data_create`
Delete agent job data
```go theme={null}
result, err := client.Agents.Jobs.DeleteData(
"jobID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_webhook_resend_create`
Resend agent job webhook
```go theme={null}
result, err := client.Agents.Jobs.ResendWebhook(
"jobID",
"webhookID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_status_retrieve`
Get agent job status.
```go theme={null}
result, err := client.Agents.Jobs.RetrieveStatus(
"jobID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_run`
Run agent synchronously
```go theme={null}
result, err := client.Agents.RunSync(
"agent_id",
map[string]any{"text": "text"},
map[string]any{},
// optional: roe.RunOptions{SkipCache: true} bypasses the job-result cache
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_run_async_create`
Run agent asynchronously.
```go theme={null}
job, err := client.Agents.Run(
"agent_id",
300,
map[string]any{"text": "text"},
map[string]any{},
// optional: roe.RunOptions{SkipCache: true} bypasses the job-result cache
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_run_async_many`
Run agent asynchronously with multiple inputs
```go theme={null}
batch, err := client.Agents.RunMany(
"agent_id",
[]map[string]any{{"text": "text"}},
300,
map[string]any{},
// optional: roe.RunOptions{SkipCache: true} bypasses the job-result cache
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_run_version`
Run agent version synchronously
```go theme={null}
result, err := client.Agents.RunVersionSync(
"agent_id",
"version_id",
map[string]any{"text": "text"},
map[string]any{},
// optional: roe.RunOptions{SkipCache: true} bypasses the job-result cache
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_run_versions_async_create`
Run agent version asynchronously.
```go theme={null}
job, err := client.Agents.RunVersion(
"agent_id",
"version_id",
300,
map[string]any{"text": "text"},
map[string]any{},
// optional: roe.RunOptions{SkipCache: true} bypasses the job-result cache
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_destroy`
Delete a base agent.
```go theme={null}
err := client.Agents.Delete(
"agentID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_retrieve`
Retrieve an agent.
```go theme={null}
result, err := client.Agents.Retrieve(
"agentID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_partial_update`
Partially update an agent.
```go theme={null}
result, err := client.Agents.Update(
"agentID",
"name",
&[]bool{true}[0],
&[]bool{true}[0],
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_update`
Update a base agent.
```go theme={null}
result, err := client.Agents.Replace(
"agentID",
"name",
&[]bool{true}[0],
&[]bool{true}[0],
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_duplicate_create`
Duplicate an agent.
```go theme={null}
result, err := client.Agents.Duplicate("agent_id")
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_list`
List agent jobs or create a new agent job.
```go theme={null}
result, err := client.Agents.Jobs.ListJobs(
"agentID",
1,
1,
"statusCode",
"versionName",
"metadata",
"createdFrom",
"createdTo",
"search",
"ordering",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_jobs_cancel_all_create`
Cancel all running agent jobs (:cancelAll)
```go theme={null}
result, err := client.Agents.Jobs.CancelAll(
"agentID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_versions_list`
List agent versions.
```go theme={null}
params := &roe.ListVersionsParams{Page: 1, PageSize: 10}
result, err := client.Agents.Versions.ListPaginated(
"agent_id",
params,
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_versions_create`
Create a new agent version.
```go theme={null}
result, err := client.Agents.Versions.Create(
"agentID",
[]map[string]any{{"key": "text", "data_type": "text/plain"}},
map[string]any{"model": "gpt-5.5-2026-04-23"},
"versionName",
"description",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_versions_current_retrieve`
Retrieve the current version of an agent.
```go theme={null}
getSupportsEval := true
result, err := client.Agents.Versions.RetrieveCurrentWithEval(
"agent_id",
&getSupportsEval,
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_versions_destroy`
Delete an agent version.
```go theme={null}
err := client.Agents.Versions.Delete(
"agentID",
"versionID",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_versions_retrieve`
Retrieve an agent version.
```go theme={null}
result, err := client.Agents.Versions.Retrieve(
"agentID",
"versionID",
&[]bool{true}[0],
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_versions_partial_update`
Partially update an agent version.
```go theme={null}
err := client.Agents.Versions.Update(
"agentID",
"versionID",
"versionName",
"description",
)
if err != nil {
log.Fatal(err)
}
```
#### `agents_versions_update`
Update an agent version.
```go theme={null}
err := client.Agents.Versions.Replace(
"agentID",
"versionID",
"versionName",
"description",
)
if err != nil {
log.Fatal(err)
}
```
### Connections
#### `connections_list`
List/create connections.
```go theme={null}
result, err := client.Connections.List(
"connectorType",
"search",
1,
1,
)
if err != nil {
log.Fatal(err)
}
```
#### `connections_create`
List/create connections.
```go theme={null}
result, err := client.Connections.Create(
"connectorType",
"name",
map[string]any{},
"description",
map[string]any{},
map[string]string{},
)
if err != nil {
log.Fatal(err)
}
```
#### `connections_test_credentials_create`
Test credentials without storing them.
```go theme={null}
result, err := client.Connections.TestCredentials(
"connectorType",
map[string]any{},
map[string]any{},
map[string]string{},
)
if err != nil {
log.Fatal(err)
}
```
#### `connections_destroy`
Manage connection.
```go theme={null}
err := client.Connections.Delete(
"connectionID",
)
if err != nil {
log.Fatal(err)
}
```
#### `connections_retrieve`
Manage connection.
```go theme={null}
result, err := client.Connections.Retrieve(
"connectionID",
)
if err != nil {
log.Fatal(err)
}
```
#### `connections_partial_update`
Manage connection.
```go theme={null}
result, err := client.Connections.Update(
"connectionID",
"name",
"description",
map[string]any{},
map[string]any{},
map[string]string{},
)
if err != nil {
log.Fatal(err)
}
```
#### `connections_update`
Manage connection.
```go theme={null}
result, err := client.Connections.Replace(
"connectionID",
"name",
"description",
map[string]any{},
map[string]any{},
map[string]string{},
)
if err != nil {
log.Fatal(err)
}
```
#### `connections_test_create`
Test connection.
```go theme={null}
result, err := client.Connections.Test(
"connectionID",
)
if err != nil {
log.Fatal(err)
}
```
### Connectors
#### `connectors_retrieve`
List all connector types.
```go theme={null}
result, err := client.Connectors.List(
)
if err != nil {
log.Fatal(err)
}
```
#### `connectors_retrieve_by_type`
Get connector details.
```go theme={null}
result, err := client.Connectors.Retrieve(
"connectorType",
)
if err != nil {
log.Fatal(err)
}
```
### Discovery
#### `discovery_supported_models_list`
List supported model IDs
```go theme={null}
result, err := client.Discovery.ListSupportedModels(
"capability",
)
if err != nil {
log.Fatal(err)
}
```
#### `discovery_agent_engine_types_list`
List supported agent engine types
```go theme={null}
result, err := client.Discovery.ListAgentEngineTypes(
)
if err != nil {
log.Fatal(err)
}
```
### Knowledge Base
#### `knowledge_base_list`
List all KBs for the org, or start a new draft.
```go theme={null}
result, err := client.KnowledgeBase.List(1, 10)
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_create`
List all KBs for the org, or start a new draft.
```go theme={null}
result, err := client.KnowledgeBase.Create(
"company",
"brief",
"", // name (optional)
"", // product name (optional)
"", // website URL (optional)
)
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_catalog_retrieve`
Names-only typology+tactic catalog.
```go theme={null}
result, err := client.KnowledgeBase.Catalog()
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_import_lens_create`
Import a finalized Atlas lens into roe-main by its atlas\_lens\_id.
```go theme={null}
result, err := client.KnowledgeBase.ImportLens("atlas_lens_id")
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_lens_retrieve`
Fetch a lens directly from Atlas by its atlas\_lens\_id and return the
names-only projection.
```go theme={null}
result, err := client.KnowledgeBase.LensByAtlasId("atlas_lens_id")
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_destroy`
Get or delete a single KB.
```go theme={null}
err := client.KnowledgeBase.Delete("knowledge_base_id")
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_retrieve`
Get or delete a single KB.
```go theme={null}
result, err := client.KnowledgeBase.Retrieve("knowledge_base_id")
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_draft_retrieve`
Poll the atlas draft.
```go theme={null}
result, err := client.KnowledgeBase.PollDraft("knowledge_base_id")
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_finalize_create`
Commit the agreed selection into a lens and mark the KB active.
```go theme={null}
result, err := client.KnowledgeBase.Finalize(
"knowledge_base_id",
"", // name (optional)
true, // MCP enabled
true, // public
)
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_regenerate_create`
Kick off another async generation round with feedback.
```go theme={null}
result, err := client.KnowledgeBase.Regenerate("knowledge_base_id", "")
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_resolve_create`
Approve or decline a pending regeneration proposal.
```go theme={null}
result, err := client.KnowledgeBase.Resolve(
"knowledge_base_id",
nil, // refs (optional)
"", // suggested name (optional)
false, // accept summary
false, // discard
)
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_selection_partial_update`
Persist hand-edits to the working selection (typology + tactic opt-in/out).
```go theme={null}
result, err := client.KnowledgeBase.PatchSelection(
"knowledge_base_id",
[]map[string]any{},
"", // suggested name (optional)
)
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_sync_create`
Standalone best-effort lens sync (display mode).
```go theme={null}
result, err := client.KnowledgeBase.Sync("knowledge_base_id")
if err != nil {
log.Fatal(err)
}
```
#### `knowledge_base_unlink_destroy`
Unlink a knowledge base: remove the local KnowledgeBase row only, leaving
the Atlas lens (and any in-progress draft) untouched.
```go theme={null}
err := client.KnowledgeBase.Unlink("knowledge_base_id")
if err != nil {
log.Fatal(err)
}
```
### Policies
#### `policies_list`
List all policies and create a new policy.
```go theme={null}
result, err := client.Policies.List(
1,
1,
)
if err != nil {
log.Fatal(err)
}
```
#### `policies_create`
List all policies and create a new policy.
```go theme={null}
result, err := client.Policies.Create(
"name",
map[string]any{},
"description",
"versionName",
)
if err != nil {
log.Fatal(err)
}
```
#### `policies_destroy`
Retrieve, update, or delete a single policy by ID.
```go theme={null}
err := client.Policies.Delete(
"policyID",
)
if err != nil {
log.Fatal(err)
}
```
#### `policies_retrieve`
Retrieve, update, or delete a single policy by ID.
```go theme={null}
result, err := client.Policies.Retrieve(
"policyID",
)
if err != nil {
log.Fatal(err)
}
```
#### `policies_partial_update`
Retrieve, update, or delete a single policy by ID.
```go theme={null}
result, err := client.Policies.Update(
"policyID",
&[]string{"value"}[0],
&[]string{"value"}[0],
)
if err != nil {
log.Fatal(err)
}
```
#### `policies_update`
Retrieve, update, or delete a single policy by ID.
```go theme={null}
result, err := client.Policies.Replace(
"policyID",
"name",
"description",
)
if err != nil {
log.Fatal(err)
}
```
#### `policies_versions_list`
Create a new policy version or list all versions of a specific policy.
```go theme={null}
result, err := client.Policies.Versions.List("policy_id")
if err != nil {
log.Fatal(err)
}
```
#### `policies_versions_create`
Create a new policy version or list all versions of a specific policy.
```go theme={null}
result, err := client.Policies.Versions.Create(
"policy_id",
map[string]any{},
"version_name",
"base_version_id",
)
if err != nil {
log.Fatal(err)
}
```
#### `policies_versions_retrieve`
Get a specific policy version by policy\_id and version\_id.
```go theme={null}
result, err := client.Policies.Versions.Retrieve(
"policy_id",
"version_id",
)
if err != nil {
log.Fatal(err)
}
```
### Tables
#### `tables_list`
List Roe tables
```go theme={null}
result, err := client.Tables.List(
)
if err != nil {
log.Fatal(err)
}
```
#### `tables_query_create`
Run a read-only Roe table query
```go theme={null}
result, err := client.Tables.Query(
"sql",
1,
)
if err != nil {
log.Fatal(err)
}
```
#### `tables_query_result_retrieve`
Get a Roe table query result
```go theme={null}
result, err := client.Tables.QueryResult(
"tableQueryID",
)
if err != nil {
log.Fatal(err)
}
```
#### `tables_destroy`
Delete a Roe table
```go theme={null}
err := client.Tables.Delete(
"tableName",
)
if err != nil {
log.Fatal(err)
}
```
#### `tables_describe_retrieve`
Describe a Roe table
```go theme={null}
result, err := client.Tables.Describe(
"tableName",
)
if err != nil {
log.Fatal(err)
}
```
#### `tables_preview_retrieve`
Preview a Roe table
```go theme={null}
result, err := client.Tables.Preview(
"tableName",
1,
)
if err != nil {
log.Fatal(err)
}
```
#### `upload_table`
Upload a CSV as a Roe table
```go theme={null}
file := roe.FileUpload{Path: "file.csv"}
result, err := client.Tables.Upload(
"table_name",
file,
true,
)
if err != nil {
log.Fatal(err)
}
```
### Users
#### `users_current_user_retrieve`
Get the current user
```go theme={null}
result, err := client.Users.Me()
if err != nil {
log.Fatal(err)
}
```
# Use Cases
Source: https://docs.roe-ai.com/api-reference/go-sdk-use-cases
End-to-end workflows for calling Roe with the Go SDK.
These workflows assume `ROE_API_KEY` and `ROE_ORGANIZATION_ID` are set.
The first example provisions a policy and an agent from scratch; the later two
reuse an existing agent id so they stay focused on the run-and-fetch calls.
## Create a policy and run a policy-aware agent
```go theme={null}
package main
import (
"fmt"
"log"
"os"
"time"
roe "github.com/roe-ai/roe-golang"
)
func main() {
client, err := roe.NewClient(os.Getenv("ROE_API_KEY"), os.Getenv("ROE_ORGANIZATION_ID"), "", 0, 0)
if err != nil {
log.Fatal(err)
}
defer client.Close()
policy, err := client.Policies.Create("AML Investigation Policy", map[string]any{
"guidelines": map[string]any{
"categories": []map[string]any{
{
"title": "Transaction Patterns",
"rules": []map[string]any{
{
"title": "Structuring below reporting thresholds",
"flag": "RED_FLAG",
"description": "Deposits just under CTR thresholds in a short window.",
},
},
},
},
},
"dispositions": map[string]any{
"classifications": []map[string]any{
{"name": "SAR", "description": "File a Suspicious Activity Report."},
{"name": "DISMISS", "description": "Close as non-suspicious."},
},
},
}, "", "")
if err != nil {
log.Fatal(err)
}
agent, err := client.Agents.Create(
"AML Investigation Agent",
"AMLInvestigationEngine",
[]map[string]any{{"key": "alert_data", "data_type": "text/plain", "description": "Alert to investigate."}},
map[string]any{"policy_version_id": *policy.CurrentVersionID, "alert_data": "${alert_data}"},
"", "",
)
if err != nil {
log.Fatal(err)
}
job, err := client.Agents.Run(agent.ID, 300, map[string]any{
"alert_data": "Customer made 9 cash deposits of $9,500 over three days.",
}, nil)
if err != nil {
log.Fatal(err)
}
result, err := job.Wait(5*time.Second, 5*time.Minute)
if err != nil {
log.Fatal(err)
}
for _, output := range result.Outputs {
fmt.Printf("%s: %s\n", output.Key, output.Value)
}
}
```
## Run an agent and download a saved reference
```go theme={null}
package main
import (
"encoding/json"
"log"
"os"
"time"
roe "github.com/roe-ai/roe-golang"
)
type reference struct {
ResourceID string `json:"resource_id"`
}
func main() {
client, err := roe.NewClient(os.Getenv("ROE_API_KEY"), os.Getenv("ROE_ORGANIZATION_ID"), "", 0, 0)
if err != nil {
log.Fatal(err)
}
defer client.Close()
agentID := os.Getenv("ROE_URL_AGENT_ID")
if agentID == "" {
log.Fatal("Set ROE_URL_AGENT_ID")
}
job, err := client.Agents.Run(agentID, 300, map[string]any{"url": "https://www.roe-ai.com/"}, map[string]any{"use_case": "website-scan"})
if err != nil {
log.Fatal(err)
}
result, err := job.Wait(5*time.Second, 5*time.Minute)
if err != nil {
log.Fatal(err)
}
for _, output := range result.Outputs {
for _, ref := range referencesFrom(output.Value) {
content, err := client.Agents.Jobs.DownloadReference(job.ID(), ref.ResourceID, false)
if err != nil {
log.Fatal(err)
}
if err := os.WriteFile(ref.ResourceID+".bin", content, 0644); err != nil {
log.Fatal(err)
}
}
}
}
func referencesFrom(value string) []reference {
var payload struct {
References []reference `json:"references"`
}
if err := json.Unmarshal([]byte(value), &payload); err != nil {
return nil
}
return payload.References
}
```
## Run a batch of inputs
```go theme={null}
package main
import (
"fmt"
"log"
"os"
"time"
roe "github.com/roe-ai/roe-golang"
)
func main() {
client, err := roe.NewClient(os.Getenv("ROE_API_KEY"), os.Getenv("ROE_ORGANIZATION_ID"), "", 0, 0)
if err != nil {
log.Fatal(err)
}
defer client.Close()
agentID := os.Getenv("ROE_TEXT_AGENT_ID")
if agentID == "" {
log.Fatal("Set ROE_TEXT_AGENT_ID")
}
batch, err := client.Agents.RunMany(agentID, []map[string]any{
{"text": "Summarize the customer complaint."},
{"text": "Extract the requested follow-up action."},
}, 300, nil)
if err != nil {
log.Fatal(err)
}
results, err := batch.Wait(5*time.Second, 5*time.Minute)
if err != nil {
log.Fatal(err)
}
for _, result := range results {
for _, output := range result.Outputs {
fmt.Printf("%s: %s\n", output.Key, output.Value)
}
}
}
```
# Introduction
Source: https://docs.roe-ai.com/api-reference/introduction
Manage your unstructured data with Roe API
## Authentication
All API endpoints are authenticated using Bearer tokens which you can find under `Settings` on the platform.
![title]()
# Create Policy
Source: https://docs.roe-ai.com/api-reference/policies/create-policy
POST /policies/
List all policies and create a new policy
Create a new policy with an initial version. The initial version is automatically set as the current version.
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---- | -------- | ------------------------------------------------ |
| `organization_id` | uuid | Yes | UUID of the organization to create the policy in |
## Request Body
| Field | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------------------------- |
| `name` | string | Yes | Name of the policy (max 255 characters) |
| `description` | string | No | Description of the policy |
| `content` | object | Yes | Policy content structure (see below) |
| `version_name` | string | No | Name for the initial version (default: "version 1") |
### Content Object
The `content` field accepts a JSON object with the following optional sections:
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------ |
| `guidelines` | object | Hierarchical structure with categories, rules, and sub-rules |
| `instructions` | string | Free-form text instructions for the agent |
| `dispositions` | object | Classification options for agent outputs |
| `summary_template` | object | Handlebars-style template for generating summaries |
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/policies/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents against compliance requirements",
"content": {
"guidelines": {
"categories": [
{
"title": "Document Verification",
"rules": [
{
"title": "Check all signatures",
"flag": "RED_FLAG"
}
]
}
]
},
"instructions": "Review all documents carefully."
},
"version_name": "version 1"
}'
```
```json 201 theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents against compliance requirements",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174001",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
```
```json 400 Missing required fields theme={null}
{
"name": ["This field is required."],
"content": ["This field is required."]
}
```
```json 400 Invalid content structure theme={null}
{
"content": ["Invalid new format content: guidelines.categories[0].title must be a non-empty string"]
}
```
# Create Policy Version
Source: https://docs.roe-ai.com/api-reference/policies/create-policy-version
POST /policies/{policy_id}/versions/
Create a new policy version or list all versions of a specific policy
Create a new version of an existing policy. The new version is automatically set as the current version for the policy.
Creating a new version does not modify existing versions. All previous versions remain accessible and can be restored using the [Set Current Version](/api-reference/policies/set-current-version) endpoint.
## Path Parameters
| Parameter | Type | Required | Description |
| ----------- | ---- | -------- | -------------------------------------- |
| `policy_id` | uuid | Yes | UUID of the policy to add a version to |
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---- | -------- | ------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization for access control |
## Request Body
| Field | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `version_name` | string | No | Name for this version (auto-generated if not provided, e.g., "version 2") |
| `content` | object | Yes | Policy content structure (see below) |
### Content Object
The `content` field accepts a JSON object with the following optional sections:
| Field | Type | Description |
| --------------------------------------------- | ------ | --------------------------------------------------------------- |
| `guidelines` | object | Hierarchical structure with `categories` array containing rules |
| `guidelines.categories[].title` | string | Category title (required) |
| `guidelines.categories[].description` | string | Category description (optional) |
| `guidelines.categories[].rules` | array | List of rules in this category |
| `guidelines.categories[].rules[].title` | string | Rule title (required) |
| `guidelines.categories[].rules[].description` | string | Rule description (optional) |
| `guidelines.categories[].rules[].flag` | string | `GREEN_FLAG` or `RED_FLAG` (optional) |
| `guidelines.categories[].rules[].sub_rules` | array | Nested sub-rules (optional) |
| `instructions` | string | Free-form text instructions for the agent |
| `dispositions` | object | Classification options with `classifications` array |
| `dispositions.classifications[].name` | string | Classification name (required) |
| `dispositions.classifications[].description` | string | Classification description (optional) |
| `dispositions.classifications[].prompt` | string | Prompt for when to use this classification (optional) |
| `summary_template` | object | Template for generating summaries |
| `summary_template.template` | string | Handlebars-style template string |
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/policies/POLICY_ID/versions/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"version_name": "version 2",
"content": {
"guidelines": {
"categories": [
{
"title": "Updated Verification Rules",
"rules": [
{
"title": "Enhanced signature validation",
"description": "All signatures must be verified against the authorized signatory list",
"flag": "RED_FLAG"
}
]
}
]
},
"instructions": "Apply enhanced review procedures.",
"dispositions": {
"classifications": [
{"name": "Approved", "description": "Document passes all checks"},
{"name": "Rejected", "description": "Document fails one or more checks"}
]
}
}
}'
```
```json 201 theme={null}
{
"id": "456e7890-e89b-12d3-a456-426614174002",
"version_name": "version 2",
"content": {
"guidelines": {
"categories": [
{
"title": "Updated Verification Rules",
"rules": [
{
"title": "Enhanced signature validation",
"description": "All signatures must be verified against the authorized signatory list",
"flag": "RED_FLAG"
}
]
}
]
},
"instructions": "Apply enhanced review procedures.",
"dispositions": {
"classifications": [
{"name": "Approved", "description": "Document passes all checks"},
{"name": "Rejected", "description": "Document fails one or more checks"}
]
}
}
}
```
```json 400 Missing required fields theme={null}
{
"content": ["This field is required."]
}
```
```json 400 Invalid content structure theme={null}
{
"content": ["Invalid new format content: guidelines.categories[0].rules[0].title must be a non-empty string"]
}
```
# Delete Policy
Source: https://docs.roe-ai.com/api-reference/policies/delete-policy
DELETE /policies/{id}/
Retrieve, update, or delete a single policy by ID
Delete a policy and all of its versions. This operation is irreversible.
Policies cannot be deleted while they are in use by any agent. You must first unlink all agents from the policy before deleting it.
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ---------------------------- |
| `id` | uuid | Yes | UUID of the policy to delete |
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---- | -------- | ------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization for access control |
```bash cURL theme={null}
curl --request DELETE \
--url "https://api.roe-ai.com/v1/policies/POLICY_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
```json 204 theme={null}
// No content - policy successfully deleted
```
```json 409 theme={null}
{
"error": "Cannot delete policy - it is in use by agents",
"dependent_agents": [
{
"base_agent_id": "abc12345-e89b-12d3-a456-426614174000",
"agent_name": "Document Reviewer",
"version_id": "def67890-e89b-12d3-a456-426614174001",
"version_name": "v2"
}
]
}
```
# List Policies
Source: https://docs.roe-ai.com/api-reference/policies/list-policies
GET /policies/
List all policies and create a new policy
Retrieve a paginated list of all policies in your organization.
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization to list policies from |
| `page` | integer | No | Page number for pagination (default: 1) |
| `page_size` | integer | No | Number of results per page (default: 10) |
| `search` | string | No | Search term to filter policies by name, description, or ID prefix (also matches version IDs) |
| `ordering` | string | No | Field to order results by. Options: `name`, `-name`, `created_at`, `-created_at`, `updated_at`, `-updated_at` (default: `-updated_at`) |
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/policies/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={null}
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents against compliance requirements",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174001",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z"
},
{
"id": "789e0123-e89b-12d3-a456-426614174002",
"name": "Document Classification Policy",
"description": "Policy for classifying incoming documents",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "012e3456-e89b-12d3-a456-426614174003",
"created_at": "2024-01-10T08:00:00Z",
"updated_at": "2024-01-18T12:30:00Z"
}
]
}
```
# List Policy Versions
Source: https://docs.roe-ai.com/api-reference/policies/list-policy-versions
GET /policies/{policy_id}/versions/
Create a new policy version or list all versions of a specific policy
Retrieve a paginated list of all versions for a specific policy, ordered by most recently updated first.
## Path Parameters
| Parameter | Type | Required | Description |
| ----------- | ---- | -------- | --------------------------------------- |
| `policy_id` | uuid | Yes | UUID of the policy to list versions for |
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization for access control |
| `page` | integer | No | Page number for pagination (default: 1) |
| `page_size` | integer | No | Number of results per page (default: 10) |
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/policies/POLICY_ID/versions/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={null}
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": "456e7890-e89b-12d3-a456-426614174003",
"version_name": "version 3",
"content": {
"guidelines": {
"categories": [
{
"title": "Enhanced Verification",
"rules": [
{
"title": "Verify all signatures",
"flag": "RED_FLAG"
}
]
}
]
},
"instructions": "Apply enhanced review procedures."
},
"updated_at": "2024-01-20T15:45:00Z",
"policy": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174003",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z"
}
},
{
"id": "456e7890-e89b-12d3-a456-426614174002",
"version_name": "version 2",
"content": {
"guidelines": {
"categories": []
},
"instructions": "Review documents."
},
"updated_at": "2024-01-18T12:00:00Z",
"policy": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174003",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z"
}
}
]
}
```
# Retrieve Policy
Source: https://docs.roe-ai.com/api-reference/policies/retrieve-policy
GET /policies/{id}/
Retrieve, update, or delete a single policy by ID
Retrieve details of a specific policy by its ID.
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ------------------------------ |
| `id` | uuid | Yes | UUID of the policy to retrieve |
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---- | -------- | ------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization for access control |
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/policies/POLICY_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents against compliance requirements",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174001",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z"
}
```
# Retrieve Policy Version
Source: https://docs.roe-ai.com/api-reference/policies/retrieve-policy-version
GET /policies/versions/{id}/
Get a policy version by ID. Supports two lookup methods:
1. Direct PolicyVersion ID lookup
2. Policy ID lookup using the policy's current_version_id
Retrieve a specific policy version with its full content.
This endpoint supports two lookup methods:
1. **Direct lookup**: Provide a policy version ID to retrieve that specific version
2. **Policy lookup**: Provide a policy ID to retrieve its current version
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------------------------------------------------------------- |
| `id` | uuid | Yes | UUID of the policy version OR the policy (to get current version) |
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---- | -------- | ------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization for access control |
## Response Fields
| Field | Type | Description |
| -------------- | -------- | ------------------------------------------------------------------------------ |
| `id` | uuid | Unique identifier for this version |
| `version_name` | string | Human-readable version name |
| `content` | object | The policy content (guidelines, instructions, dispositions, summary\_template) |
| `updated_at` | datetime | When this version was last updated |
| `policy` | object | The parent policy object |
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/policies/versions/VERSION_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={null}
{
"id": "456e7890-e89b-12d3-a456-426614174001",
"version_name": "version 2",
"content": {
"guidelines": {
"categories": [
{
"title": "Document Verification",
"description": "Rules for verifying document authenticity",
"rules": [
{
"title": "Check signatures",
"description": "Verify all required signatures are present",
"flag": "RED_FLAG",
"sub_rules": [
{
"title": "Authorized signatories",
"description": "Signatures must match authorized personnel list"
}
]
},
{
"title": "Verify dates",
"description": "All dates must be within valid ranges",
"flag": "GREEN_FLAG"
}
]
}
]
},
"instructions": "Review all documents for compliance with company policy. Flag any discrepancies.",
"dispositions": {
"classifications": [
{
"name": "Approved",
"description": "Document meets all requirements",
"prompt": "Select this when all compliance checks pass"
},
{
"name": "Rejected",
"description": "Document fails one or more requirements",
"prompt": "Select this when any critical rule is violated"
},
{
"name": "Needs Review",
"description": "Document requires manual review",
"prompt": "Select this for edge cases or unclear situations"
}
]
},
"summary_template": {
"template": "## Review Summary\n\n**Decision**: {{disposition}}\n\n**Findings**:\n{{#each findings}}\n- {{this}}\n{{/each}}"
}
},
"updated_at": "2024-01-20T15:45:00Z",
"policy": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents against compliance requirements",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174001",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z"
}
}
```
```json 404 Policy exists but no current version theme={null}
{
"detail": "Policy has no current version set"
}
```
# Set Current Version
Source: https://docs.roe-ai.com/api-reference/policies/set-current-version
PATCH /policies/{policy_id}/set-current-version/{version_id}/
Set the current version of a policy
Change which version is the current (active) version for a policy. This is useful for rolling back to a previous version or promoting a specific version.
Agents that reference this policy will automatically use the new current version on their next job run.
## Path Parameters
| Parameter | Type | Required | Description |
| ------------ | ---- | -------- | ------------------------------------- |
| `policy_id` | uuid | Yes | UUID of the policy to update |
| `version_id` | uuid | Yes | UUID of the version to set as current |
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---- | -------- | ------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization for access control |
```bash cURL theme={null}
curl --request PATCH \
--url "https://api.roe-ai.com/v1/policies/POLICY_ID/set-current-version/VERSION_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Compliance Review Policy",
"description": "Policy for reviewing documents against compliance requirements",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174002",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-21T09:15:00Z"
}
```
# Update Policy
Source: https://docs.roe-ai.com/api-reference/policies/update-policy
PUT /policies/{id}/
Retrieve, update, or delete a single policy by ID
Update metadata (name and description) of an existing policy. This does not modify the policy versions or content - use the [Create Policy Version](/api-reference/policies/create-policy-version) endpoint to add new content.
This endpoint supports both `PUT` (full update) and `PATCH` (partial update) methods.
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ---------------------------- |
| `id` | uuid | Yes | UUID of the policy to update |
## Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---- | -------- | ------------------------------------------- |
| `organization_id` | uuid | Yes | UUID of the organization for access control |
## Request Body
| Field | Type | Required (PUT) | Required (PATCH) | Description |
| ------------- | ------ | -------------- | ---------------- | -------------------------------------------- |
| `name` | string | Yes | No | New name for the policy (max 255 characters) |
| `description` | string | No | No | New description for the policy |
```bash cURL (PUT - full update) theme={null}
curl --request PUT \
--url "https://api.roe-ai.com/v1/policies/POLICY_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Updated Policy Name",
"description": "Updated policy description"
}'
```
```bash cURL (PATCH - partial update) theme={null}
curl --request PATCH \
--url "https://api.roe-ai.com/v1/policies/POLICY_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"description": "Only updating the description"
}'
```
```json 200 theme={null}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Updated Policy Name",
"description": "Updated policy description",
"organization_id": "org-12345678-1234-1234-1234-123456789012",
"current_version_id": "456e7890-e89b-12d3-a456-426614174001",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-21T09:00:00Z"
}
```
```json 400 Missing name field (PUT only) theme={null}
{
"name": ["This field is required."]
}
```
# Overview
Source: https://docs.roe-ai.com/api-reference/python-sdk-introduction
Official Python SDK for Roe
## Python SDK
The official Python SDK for interacting with the Roe API. Build powerful data extraction and processing workflows with a simple, intuitive interface.
## Installation
```bash theme={null}
pip install roe-ai
```
Or with uv:
```bash theme={null}
uv add roe-ai
```
View the package on [PyPI](https://pypi.org/project/roe-ai/)
## Requirements
* Python >=3.10
## Resources
* [PyPI Package](https://pypi.org/project/roe-ai/)
* [GitHub Repository](https://github.com/roe-ai/roe-python)
* [Report Issues](https://github.com/roe-ai/roe-python/issues)
# Examples
Source: https://docs.roe-ai.com/api-reference/python-sdk-reference
Copy-ready examples for calling Roe with the Python SDK.
## SDK operations
Copy-ready calls for each operation available through this SDK. Required and
optional inputs are shown inline in the code.
### Agents
#### `agents_list`
List agents or create a new agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.list(
page=1, # optional
page_size=1, # optional
)
```
#### `agents_create`
Create a new base agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.create(
name="name", # required
engine_class_id="engine_class_id", # required
input_definitions=[{"key": "text", "data_type": "text/plain"}], # optional
engine_config={"model": "gpt-5.5-2026-04-23"}, # optional
version_name="version_name", # optional
description="description", # optional
)
```
#### `agents_jobs_results_create`
Get results for multiple agent jobs
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.retrieve_result_many(
job_ids=["job_id"],
)
```
#### `agents_jobs_statuses_create`
Get status for multiple agent jobs
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.retrieve_status_many(
job_ids=["job_id"],
)
```
#### `agents_jobs_artifacts_result_retrieve`
Get tool result artifact (result only)
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.retrieve_artifact(
job_id="job_id", # required
artifact_key="artifact_key", # required
)
```
#### `agents_jobs_references_retrieve`
Serve a reference file associated with an agent job.
```python theme={null}
from roe import RoeClient
client = RoeClient()
content = client.agents.jobs.download_reference(
job_id="job_id",
resource_id="resource_id",
as_attachment=False,
)
```
#### `agents_jobs_result_retrieve`
Get agent job result data.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.retrieve_result(
job_id="job_id", # required
)
```
#### `agents_jobs_cancel_create`
Cancel an agent job
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.cancel(
job_id="job_id", # required
)
```
#### `agents_jobs_delete_data_create`
Delete agent job data
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.delete_data(
job_id="job_id", # required
)
```
#### `agents_jobs_webhook_resend_create`
Resend agent job webhook
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.resend_webhook(
job_id="job_id", # required
webhook_id="webhook_id", # optional
)
```
#### `agents_jobs_status_retrieve`
Get agent job status.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.retrieve_status(
job_id="job_id", # required
)
```
#### `agents_run`
Run agent synchronously
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.run_sync(
agent_id="agent_id",
text="text",
metadata={},
skip_cache=False, # optional: True bypasses the job-result cache
)
```
#### `agents_run_async_create`
Run agent asynchronously.
```python theme={null}
from roe import RoeClient
client = RoeClient()
job = client.agents.run(
agent_id="agent_id",
timeout_seconds=300,
text="text",
metadata={},
skip_cache=False, # optional: True bypasses the job-result cache
)
```
#### `agents_run_async_many`
Run agent asynchronously with multiple inputs
```python theme={null}
from roe import RoeClient
client = RoeClient()
batch = client.agents.run_many(
agent_id="agent_id",
batch_inputs=[{"text": "text"}],
timeout_seconds=300,
metadata={},
skip_cache=False, # optional: True bypasses the job-result cache
)
```
#### `agents_run_version`
Run agent version synchronously
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.run_version_sync(
agent_id="agent_id",
version_id="version_id",
text="text",
metadata={},
skip_cache=False, # optional: True bypasses the job-result cache
)
```
#### `agents_run_versions_async_create`
Run agent version asynchronously.
```python theme={null}
from roe import RoeClient
client = RoeClient()
job = client.agents.run_version(
agent_id="agent_id",
version_id="version_id",
timeout_seconds=300,
text="text",
metadata={},
skip_cache=False, # optional: True bypasses the job-result cache
)
```
#### `agents_destroy`
Delete a base agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.delete(
agent_id="agent_id", # required
)
```
#### `agents_retrieve`
Retrieve an agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.retrieve(
agent_id="agent_id", # required
)
```
#### `agents_partial_update`
Partially update an agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.update(
agent_id="agent_id", # required
name="name", # optional
disable_cache=True, # optional
cache_failed_jobs=True, # optional
)
```
#### `agents_update`
Update a base agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.replace(
agent_id="agent_id", # required
name="name", # optional
disable_cache=True, # optional
cache_failed_jobs=True, # optional
)
```
#### `agents_duplicate_create`
Duplicate an agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.duplicate(
agent_id="agent_id", # required
)
```
#### `agents_jobs_list`
List agent jobs or create a new agent job.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.list(
agent_id="agent_id", # required
page=1, # optional
page_size=1, # optional
status_code="status_code", # optional
version_name="version_name", # optional
metadata="metadata", # optional
created_from="created_from", # optional
created_to="created_to", # optional
search="search", # optional
ordering="ordering", # optional
)
```
#### `agents_jobs_cancel_all_create`
Cancel all running agent jobs (:cancelAll)
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.jobs.cancel_all(
agent_id="agent_id", # required
)
```
#### `agents_versions_list`
List agent versions.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.versions.list(
agent_id="agent_id", # required
)
```
#### `agents_versions_create`
Create a new agent version.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.versions.create(
agent_id="agent_id", # required
input_definitions=[{"key": "text", "data_type": "text/plain"}], # optional
engine_config={"model": "gpt-5.5-2026-04-23"}, # optional
version_name="version_name", # optional
description="description", # optional
)
```
#### `agents_versions_current_retrieve`
Retrieve the current version of an agent.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.versions.retrieve_current(
agent_id="agent_id", # required
)
```
#### `agents_versions_destroy`
Delete an agent version.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.versions.delete(
agent_id="agent_id", # required
version_id="version_id", # required
)
```
#### `agents_versions_retrieve`
Retrieve an agent version.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.versions.retrieve(
agent_id="agent_id", # required
version_id="version_id", # required
get_supports_eval=True, # optional
)
```
#### `agents_versions_partial_update`
Partially update an agent version.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.versions.update(
agent_id="agent_id", # required
version_id="version_id", # required
version_name="version_name", # optional
description="description", # optional
)
```
#### `agents_versions_update`
Update an agent version.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.agents.versions.replace(
agent_id="agent_id", # required
version_id="version_id", # required
version_name="version_name", # optional
description="description", # optional
)
```
### Connections
#### `connections_list`
List/create connections.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.list(
connector_type="connector_type", # optional
search="search", # optional
page=1, # optional
page_size=1, # optional
)
```
#### `connections_create`
List/create connections.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.create(
connector_type="connector_type", # required
name="name", # required
config={}, # required
description="description", # optional
auth_config={}, # optional
dynamic_inputs={}, # optional
)
```
#### `connections_test_credentials_create`
Test credentials without storing them.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.test_credentials(
connector_type="connector_type", # required
config={}, # required
auth_config={}, # optional
dynamic_inputs={}, # optional
)
```
#### `connections_destroy`
Manage connection.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.delete(
connection_id="connection_id", # required
)
```
#### `connections_retrieve`
Manage connection.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.retrieve(
connection_id="connection_id", # required
)
```
#### `connections_partial_update`
Manage connection.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.update(
connection_id="connection_id", # required
name="name", # optional
description="description", # optional
config={}, # optional
auth_config={}, # optional
dynamic_inputs={}, # optional
)
```
#### `connections_update`
Manage connection.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.replace(
connection_id="connection_id", # required
name="name", # optional
description="description", # optional
config={}, # optional
auth_config={}, # optional
dynamic_inputs={}, # optional
)
```
#### `connections_test_create`
Test connection.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connections.test(
connection_id="connection_id", # required
)
```
### Connectors
#### `connectors_retrieve`
List all connector types.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connectors.list()
```
#### `connectors_retrieve_by_type`
Get connector details.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.connectors.retrieve(
connector_type="connector_type", # required
)
```
### Discovery
#### `discovery_supported_models_list`
List supported model IDs
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.discovery.list_supported_models(
capability="capability", # optional
)
```
#### `discovery_agent_engine_types_list`
List supported agent engine types
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.discovery.list_agent_engine_types()
```
### Knowledge Base
#### `knowledge_base_list`
List all KBs for the org, or start a new draft.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.list(
page=1, # optional
page_size=10, # optional
)
```
#### `knowledge_base_create`
List all KBs for the org, or start a new draft.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.create(
company="company",
brief="brief",
)
```
#### `knowledge_base_catalog_retrieve`
Names-only typology+tactic catalog.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.catalog()
```
#### `knowledge_base_import_lens_create`
Import a finalized Atlas lens into roe-main by its atlas\_lens\_id.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.import_lens("atlas_lens_id")
```
#### `knowledge_base_lens_retrieve`
Fetch a lens directly from Atlas by its atlas\_lens\_id and return the
names-only projection.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.lens_by_atlas_id("atlas_lens_id")
```
#### `knowledge_base_destroy`
Get or delete a single KB.
```python theme={null}
from roe import RoeClient
client = RoeClient()
client.knowledge_base.delete("knowledge_base_id")
```
#### `knowledge_base_retrieve`
Get or delete a single KB.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.retrieve("knowledge_base_id")
```
#### `knowledge_base_draft_retrieve`
Poll the atlas draft.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.poll_draft("knowledge_base_id")
```
#### `knowledge_base_finalize_create`
Commit the agreed selection into a lens and mark the KB active.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.finalize("knowledge_base_id")
```
#### `knowledge_base_regenerate_create`
Kick off another async generation round with feedback.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.regenerate("knowledge_base_id")
```
#### `knowledge_base_resolve_create`
Approve or decline a pending regeneration proposal.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.resolve("knowledge_base_id")
```
#### `knowledge_base_selection_partial_update`
Persist hand-edits to the working selection (typology + tactic opt-in/out).
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.patch_selection(
"knowledge_base_id",
refs=[],
)
```
#### `knowledge_base_sync_create`
Standalone best-effort lens sync (display mode).
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.knowledge_base.sync("knowledge_base_id")
```
#### `knowledge_base_unlink_destroy`
Unlink a knowledge base: remove the local KnowledgeBase row only, leaving
the Atlas lens (and any in-progress draft) untouched.
```python theme={null}
from roe import RoeClient
client = RoeClient()
client.knowledge_base.unlink("knowledge_base_id")
```
### Policies
#### `policies_list`
List all policies and create a new policy.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.list(
page=1, # optional
page_size=1, # optional
)
```
#### `policies_create`
List all policies and create a new policy.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.create(
name="name", # required
content={}, # required
description="description", # optional
version_name="version_name", # optional
)
```
#### `policies_destroy`
Retrieve, update, or delete a single policy by ID.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.delete(
policy_id="policy_id", # required
)
```
#### `policies_retrieve`
Retrieve, update, or delete a single policy by ID.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.retrieve(
policy_id="policy_id", # required
)
```
#### `policies_partial_update`
Retrieve, update, or delete a single policy by ID.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.update(
policy_id="policy_id", # required
name="name", # optional
description="description", # optional
)
```
#### `policies_update`
Retrieve, update, or delete a single policy by ID.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.replace(
policy_id="policy_id", # required
name="name", # required
description="description", # optional
)
```
#### `policies_versions_list`
Create a new policy version or list all versions of a specific policy.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.versions.list(
policy_id="policy_id",
page=1,
page_size=10,
)
```
#### `policies_versions_create`
Create a new policy version or list all versions of a specific policy.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.versions.create(
policy_id="policy_id",
content={},
version_name="version_name",
base_version_id="base_version_id",
)
```
#### `policies_versions_retrieve`
Get a specific policy version by policy\_id and version\_id.
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.policies.versions.retrieve(
policy_id="policy_id",
version_id="version_id",
)
```
### Tables
#### `tables_list`
List Roe tables
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.tables.list()
```
#### `tables_query_create`
Run a read-only Roe table query
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.tables.query(
sql="sql", # required
limit=1, # optional
)
```
#### `tables_query_result_retrieve`
Get a Roe table query result
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.tables.query_result(
table_query_id="table_query_id", # required
)
```
#### `tables_destroy`
Delete a Roe table
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.tables.delete(
table_name="table_name", # required
)
```
#### `tables_describe_retrieve`
Describe a Roe table
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.tables.describe(
table_name="table_name", # required
)
```
#### `tables_preview_retrieve`
Preview a Roe table
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.tables.preview(
table_name="table_name", # required
limit=1, # optional
)
```
#### `upload_table`
Upload a CSV as a Roe table
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.tables.upload(
table_name="table_name",
file="file.csv",
with_headers=True,
)
```
### Users
#### `users_current_user_retrieve`
Get the current user
```python theme={null}
from roe import RoeClient
client = RoeClient()
result = client.users.me()
```
# Use Cases
Source: https://docs.roe-ai.com/api-reference/python-sdk-use-cases
End-to-end workflows for calling Roe with the Python SDK.
These workflows assume `ROE_API_KEY` and `ROE_ORGANIZATION_ID` are set.
The first example provisions a policy and an agent from scratch; the later two
reuse an existing agent id so they stay focused on the run-and-fetch calls.
## Create a policy and run a policy-aware agent
```python theme={null}
from roe import RoeClient
client = RoeClient()
policy = client.policies.create(
name="AML Investigation Policy",
content={
"guidelines": {
"categories": [
{
"title": "Transaction Patterns",
"rules": [
{
"title": "Structuring below reporting thresholds",
"flag": "RED_FLAG",
"description": "Deposits just under CTR thresholds in a short window.",
}
],
}
]
},
"dispositions": {
"classifications": [
{"name": "SAR", "description": "File a Suspicious Activity Report."},
{"name": "DISMISS", "description": "Close as non-suspicious."},
]
},
},
)
agent = client.agents.create(
name="AML Investigation Agent",
engine_class_id="AMLInvestigationEngine",
input_definitions=[
{
"key": "alert_data",
"data_type": "text/plain",
"description": "Alert to investigate.",
}
],
engine_config={
"policy_version_id": str(policy.current_version_id),
"alert_data": "${alert_data}",
},
)
job = client.agents.run(
agent_id=str(agent.id),
timeout_seconds=300,
alert_data="Customer made 9 cash deposits of $9,500 over three days.",
)
result = job.wait(interval=5.0, timeout=300)
for output in result.outputs:
print(f"{output.key}: {output.value}")
```
## Run an agent and download a saved reference
```python theme={null}
import json
import os
from pathlib import Path
from roe import RoeClient
client = RoeClient()
agent_id = os.environ["ROE_URL_AGENT_ID"]
job = client.agents.run(
agent_id=agent_id,
timeout_seconds=300,
url="https://www.roe-ai.com/",
metadata={"use_case": "website-scan"},
)
result = job.wait(interval=5.0, timeout=300)
for output in result.outputs:
try:
payload = json.loads(output.value)
except json.JSONDecodeError:
continue
for ref in payload.get("references", []):
resource_id = ref.get("resource_id")
if resource_id:
content = client.agents.jobs.download_reference(job.id, resource_id)
Path(f"{resource_id}.bin").write_bytes(content)
```
## Run a batch of inputs
```python theme={null}
import os
from roe import RoeClient
client = RoeClient()
agent_id = os.environ["ROE_TEXT_AGENT_ID"]
batch = client.agents.run_many(
agent_id=agent_id,
batch_inputs=[
{"text": "Summarize the customer complaint."},
{"text": "Extract the requested follow-up action."},
],
timeout_seconds=300,
)
results = batch.wait(interval=5.0, timeout=300)
for job_result in results:
if job_result is None:
continue
for output in job_result.result or []:
print(f"{output.key}: {output.value}")
```
# Create a Dataset
Source: https://docs.roe-ai.com/api-reference/roe-dataset/create
POST /v1/datasets/
Create a new dataset.
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/datasets/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "My Dataset",
"description": "Dataset description"
}'
```
# Delete a Dataset
Source: https://docs.roe-ai.com/api-reference/roe-dataset/delete-dataset
DELETE /v1/datasets/{dataset_id}/
Permanently delete a dataset. All associated files are soft-deleted and can be restored later.
```bash cURL theme={null}
curl --request DELETE \
--url "https://api.roe-ai.com/v1/datasets/YOUR_DATASET_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Delete a File
Source: https://docs.roe-ai.com/api-reference/roe-dataset/delete-file
DELETE /v1/datasets/{dataset_id}/files/{id}/
Mixin for organization access validation.
Automatically resolves and validates organization access on every request,
making the organization available as self.organization.
For API key auth: organization is derived from the key (no org_id param needed).
For user auth: organization_id must be provided in the request
(kwargs / headers / body / query params).
Usage:
class MyView(BaseOrganizationAccessMixin, APIView):
def get(self, request):
# self.organization is automatically available
return Response({"org": self.organization.name})
```bash cURL theme={null}
curl --request DELETE \
--url "https://api.roe-ai.com/v1/datasets/YOUR_DATASET_ID/files/YOUR_FILE_ID/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# Download File
Source: https://docs.roe-ai.com/api-reference/roe-dataset/file-download
GET /v1/datasets/files/{file_str}/download/
Download a file by its file string identifier.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/datasets/files/YOUR_FILE_ID/download/" \
--header "Authorization: Bearer YOUR_API_KEY" \
--output downloaded_file.pdf
```
# Upload File
Source: https://docs.roe-ai.com/api-reference/roe-dataset/file-upload
POST /v1/datasets/files/upload/
Mixin for organization access validation.
Automatically resolves and validates organization access on every request,
making the organization available as self.organization.
For API key auth: organization is derived from the key (no org_id param needed).
For user auth: organization_id must be provided in the request
(kwargs / headers / body / query params).
Usage:
class MyView(BaseOrganizationAccessMixin, APIView):
def get(self, request):
# self.organization is automatically available
return Response({"org": self.organization.name})
```bash cURL theme={null}
curl --request POST \
--url "https://api.roe-ai.com/v1/datasets/files/upload/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: multipart/form-data" \
--form "file=@/path/to/your/file.pdf" \
--form "dataset_id=YOUR_DATASET_ID"
```
# List Datasets
Source: https://docs.roe-ai.com/api-reference/roe-dataset/list
GET /v1/datasets/
Retrieve a list of datasets or create a new dataset.
```bash cURL theme={null}
curl --request GET \
--url "https://api.roe-ai.com/v1/datasets/?organization_id=YOUR_ORG_ID" \
--header "Authorization: Bearer YOUR_API_KEY"
```
# SDK Overview
Source: https://docs.roe-ai.com/api-reference/sdk-integration
Manage your unstructured data with Python, TypeScript, or Go
# Overview
Official SDKs for the Roe API. Build powerful data extraction and processing workflows with our simple, intuitive interfaces available in Python, TypeScript, and Go.
## Available SDKs
* **[Python SDK](/api-reference/python-sdk-introduction)** - Full-featured Python client with async support
* **[TypeScript SDK](/api-reference/typescript-sdk-introduction)** - TypeScript/JavaScript client for Node.js
* **[Go SDK](/api-reference/go-sdk-introduction)** - High-performance Go client
## Quick Start
Choose your preferred language and get started in minutes:
```bash theme={null}
# Python
pip install roe-ai
# TypeScript/JavaScript
npm install roe-typescript
# Go
go get github.com/roe-ai/roe-golang
```
## Features
* **Agent Management** - Create, configure, and run AI agents
* **File Processing** - Handle PDFs, images, documents, and more
* **Batch Operations** - Process multiple items efficiently
* **Real-time Monitoring** - Track job status and results
* **Type Safety** - Full type definitions for better development experience
# Overview
Source: https://docs.roe-ai.com/api-reference/typescript-sdk-introduction
Official TypeScript SDK for Roe
# TypeScript SDK
The official TypeScript SDK for interacting with the Roe API. Build powerful data extraction and processing workflows with full TypeScript support and type safety.
## Installation
```bash theme={null}
npm install roe-typescript
```
Or with yarn:
```bash theme={null}
yarn add roe-typescript
```
View the package on [npm](https://www.npmjs.com/package/roe-typescript)
## Requirements
* Node.js >=18
## Resources
* [npm Package](https://www.npmjs.com/package/roe-typescript)
* [GitHub Repository](https://github.com/roe-ai/roe-typescript)
* [Report Issues](https://github.com/roe-ai/roe-typescript/issues)
# Examples
Source: https://docs.roe-ai.com/api-reference/typescript-sdk-reference
Copy-ready examples for calling Roe with the TypeScript SDK.
## SDK operations
Copy-ready calls for each operation available through this SDK. Required and
optional inputs are shown inline in the code.
### Agents
#### `agents_list`
List agents or create a new agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.list(
{
page: 1, // optional
pageSize: 1, // optional
}
);
```
#### `agents_create`
Create a new base agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.create(
{
name: "name", // required
engineClassId: "engineClassId", // required
inputDefinitions: [{ key: "text", data_type: "text/plain" }], // optional
engineConfig: { model: "gpt-5.5-2026-04-23" }, // optional
versionName: "versionName", // optional
description: "description", // optional
}
);
```
#### `agents_jobs_results_create`
Get results for multiple agent jobs
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.retrieveResultMany(["job_id"]);
```
#### `agents_jobs_statuses_create`
Get status for multiple agent jobs
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.retrieveStatusMany(["job_id"]);
```
#### `agents_jobs_artifacts_result_retrieve`
Get tool result artifact (result only)
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.retrieveArtifact(
"jobId",
"artifactKey",
);
```
#### `agents_jobs_references_retrieve`
Serve a reference file associated with an agent job.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const content = await client.agents.jobs.downloadReference(
"job_id",
"resource_id",
false,
);
```
#### `agents_jobs_result_retrieve`
Get agent job result data.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.retrieveResult("jobId");
```
#### `agents_jobs_cancel_create`
Cancel an agent job
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.cancel("jobId");
```
#### `agents_jobs_delete_data_create`
Delete agent job data
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.deleteData("jobId");
```
#### `agents_jobs_webhook_resend_create`
Resend agent job webhook
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.resendWebhook(
"jobId",
"webhookId",
);
```
#### `agents_jobs_status_retrieve`
Get agent job status.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.retrieveStatus("jobId");
```
#### `agents_run`
Run agent synchronously
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.runSync(
"agent_id",
{ text: "text" },
{},
{ skipCache: false }, // optional: true bypasses the job-result cache
);
```
#### `agents_run_async_create`
Run agent asynchronously.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const job = await client.agents.run({
agentId: "agent_id",
inputs: { text: "text" },
timeoutSeconds: 300,
metadata: {},
skipCache: false, // optional: true bypasses the job-result cache
});
```
#### `agents_run_async_many`
Run agent asynchronously with multiple inputs
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const batch = await client.agents.runMany({
agentId: "agent_id",
batchInputs: [{ text: "text" }],
timeoutSeconds: 300,
skipCache: false, // optional: true bypasses the job-result cache
});
```
#### `agents_run_version`
Run agent version synchronously
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.runVersionSync(
"agent_id",
"version_id",
{ text: "text" },
{},
{ skipCache: false }, // optional: true bypasses the job-result cache
);
```
#### `agents_run_versions_async_create`
Run agent version asynchronously.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const job = await client.agents.runVersion({
agentId: "agent_id",
versionId: "version_id",
inputs: { text: "text" },
timeoutSeconds: 300,
metadata: {},
skipCache: false, // optional: true bypasses the job-result cache
});
```
#### `agents_destroy`
Delete a base agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.delete("agentId");
```
#### `agents_retrieve`
Retrieve an agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.retrieve("agentId");
```
#### `agents_partial_update`
Partially update an agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.update(
"agentId",
{
name: "name", // optional
disableCache: true, // optional
cacheFailedJobs: true, // optional
}
);
```
#### `agents_update`
Update a base agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.replace(
"agentId",
{
name: "name", // optional
disableCache: true, // optional
cacheFailedJobs: true, // optional
}
);
```
#### `agents_duplicate_create`
Duplicate an agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.duplicate("agentId");
```
#### `agents_jobs_list`
List agent jobs or create a new agent job.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.list(
{
agentId: "agentId", // required
page: 1, // optional
pageSize: 1, // optional
statusCode: "statusCode", // optional
versionName: "versionName", // optional
metadata: "metadata", // optional
createdFrom: "createdFrom", // optional
createdTo: "createdTo", // optional
search: "search", // optional
ordering: "ordering", // optional
}
);
```
#### `agents_jobs_cancel_all_create`
Cancel all running agent jobs (:cancelAll)
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.jobs.cancelAll("agentId");
```
#### `agents_versions_list`
List agent versions.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.versions.list("agentId");
```
#### `agents_versions_create`
Create a new agent version.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.versions.create(
{
agentId: "agentId", // required
inputDefinitions: [{ key: "text", data_type: "text/plain" }], // optional
engineConfig: { model: "gpt-5.5-2026-04-23" }, // optional
versionName: "versionName", // optional
description: "description", // optional
}
);
```
#### `agents_versions_current_retrieve`
Retrieve the current version of an agent.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.versions.retrieveCurrent("agentId");
```
#### `agents_versions_destroy`
Delete an agent version.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.versions.delete(
"agentId",
"versionId",
);
```
#### `agents_versions_retrieve`
Retrieve an agent version.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.versions.retrieve(
"agentId",
"versionId",
true,
);
```
#### `agents_versions_partial_update`
Partially update an agent version.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.versions.update(
"agentId",
"versionId",
{
versionName: "versionName", // optional
description: "description", // optional
}
);
```
#### `agents_versions_update`
Update an agent version.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.agents.versions.replace(
"agentId",
"versionId",
{
versionName: "versionName", // optional
description: "description", // optional
}
);
```
### Connections
#### `connections_list`
List/create connections.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.list(
{
connectorType: "connectorType", // optional
search: "search", // optional
page: 1, // optional
pageSize: 1, // optional
}
);
```
#### `connections_create`
List/create connections.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.create(
{
connectorType: "connectorType", // required
name: "name", // required
config: {}, // required
description: "description", // optional
authConfig: {}, // optional
dynamicInputs: {}, // optional
}
);
```
#### `connections_test_credentials_create`
Test credentials without storing them.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.testCredentials(
{
connectorType: "connectorType", // required
config: {}, // required
authConfig: {}, // optional
dynamicInputs: {}, // optional
}
);
```
#### `connections_destroy`
Manage connection.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.delete("connectionId");
```
#### `connections_retrieve`
Manage connection.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.retrieve("connectionId");
```
#### `connections_partial_update`
Manage connection.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.update(
"connectionId",
{
name: "name", // optional
description: "description", // optional
config: {}, // optional
authConfig: {}, // optional
dynamicInputs: {}, // optional
}
);
```
#### `connections_update`
Manage connection.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.replace(
"connectionId",
{
name: "name", // optional
description: "description", // optional
config: {}, // optional
authConfig: {}, // optional
dynamicInputs: {}, // optional
}
);
```
#### `connections_test_create`
Test connection.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connections.test("connectionId");
```
### Connectors
#### `connectors_retrieve`
List all connector types.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connectors.list();
```
#### `connectors_retrieve_by_type`
Get connector details.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.connectors.retrieve("connectorType");
```
### Discovery
#### `discovery_supported_models_list`
List supported model IDs
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.discovery.listSupportedModels("capability");
```
#### `discovery_agent_engine_types_list`
List supported agent engine types
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.discovery.listAgentEngineTypes();
```
### Knowledge Base
#### `knowledge_base_list`
List all KBs for the org, or start a new draft.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.list({
page: 1, // optional
pageSize: 10, // optional
});
```
#### `knowledge_base_create`
List all KBs for the org, or start a new draft.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.create({
company: "company",
brief: "brief",
});
```
#### `knowledge_base_catalog_retrieve`
Names-only typology+tactic catalog.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.catalog();
```
#### `knowledge_base_import_lens_create`
Import a finalized Atlas lens into roe-main by its atlas\_lens\_id.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.importLens("atlas_lens_id");
```
#### `knowledge_base_lens_retrieve`
Fetch a lens directly from Atlas by its atlas\_lens\_id and return the
names-only projection.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.lensByAtlasId("atlas_lens_id");
```
#### `knowledge_base_destroy`
Get or delete a single KB.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
await client.knowledge_base.delete("knowledge_base_id");
```
#### `knowledge_base_retrieve`
Get or delete a single KB.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.retrieve("knowledge_base_id");
```
#### `knowledge_base_draft_retrieve`
Poll the atlas draft.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.pollDraft("knowledge_base_id");
```
#### `knowledge_base_finalize_create`
Commit the agreed selection into a lens and mark the KB active.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.finalize("knowledge_base_id");
```
#### `knowledge_base_regenerate_create`
Kick off another async generation round with feedback.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.regenerate("knowledge_base_id");
```
#### `knowledge_base_resolve_create`
Approve or decline a pending regeneration proposal.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.resolve("knowledge_base_id");
```
#### `knowledge_base_selection_partial_update`
Persist hand-edits to the working selection (typology + tactic opt-in/out).
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.patchSelection("knowledge_base_id", {
refs: [],
});
```
#### `knowledge_base_sync_create`
Standalone best-effort lens sync (display mode).
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.knowledge_base.sync("knowledge_base_id");
```
#### `knowledge_base_unlink_destroy`
Unlink a knowledge base: remove the local KnowledgeBase row only, leaving
the Atlas lens (and any in-progress draft) untouched.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
await client.knowledge_base.unlink("knowledge_base_id");
```
### Policies
#### `policies_list`
List all policies and create a new policy.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.list(
{
page: 1, // optional
pageSize: 1, // optional
}
);
```
#### `policies_create`
List all policies and create a new policy.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.create(
{
name: "name", // required
content: {}, // required
description: "description", // optional
versionName: "versionName", // optional
}
);
```
#### `policies_destroy`
Retrieve, update, or delete a single policy by ID.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.delete("policyId");
```
#### `policies_retrieve`
Retrieve, update, or delete a single policy by ID.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.retrieve("policyId");
```
#### `policies_partial_update`
Retrieve, update, or delete a single policy by ID.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.update(
"policyId",
{
name: "name", // optional
description: "description", // optional
}
);
```
#### `policies_update`
Retrieve, update, or delete a single policy by ID.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.replace(
"policyId",
{
name: "name", // required
description: "description", // optional
}
);
```
#### `policies_versions_list`
Create a new policy version or list all versions of a specific policy.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.versions.list("policy_id");
```
#### `policies_versions_create`
Create a new policy version or list all versions of a specific policy.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.versions.create({
policyId: "policy_id",
content: {},
versionName: "version_name",
baseVersionId: "base_version_id",
});
```
#### `policies_versions_retrieve`
Get a specific policy version by policy\_id and version\_id.
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.policies.versions.retrieve(
"policy_id",
"version_id",
);
```
### Tables
#### `tables_list`
List Roe tables
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.tables.list();
```
#### `tables_query_create`
Run a read-only Roe table query
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.tables.query(
{
sql: "sql", // required
limit: 1, // optional
}
);
```
#### `tables_query_result_retrieve`
Get a Roe table query result
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.tables.queryResult("tableQueryId");
```
#### `tables_destroy`
Delete a Roe table
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.tables.delete("tableName");
```
#### `tables_describe_retrieve`
Describe a Roe table
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.tables.describe("tableName");
```
#### `tables_preview_retrieve`
Preview a Roe table
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.tables.preview(
"tableName",
{
limit: 1, // optional
}
);
```
#### `upload_table`
Upload a CSV as a Roe table
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.tables.upload(
{
tableName: "table_name",
file: "file.csv",
withHeaders: true,
}
);
```
### Users
#### `users_current_user_retrieve`
Get the current user
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const result = await client.users.me();
```
# Use Cases
Source: https://docs.roe-ai.com/api-reference/typescript-sdk-use-cases
End-to-end workflows for calling Roe with the TypeScript SDK.
These workflows assume `ROE_API_KEY` and `ROE_ORGANIZATION_ID` are set.
The first example provisions a policy and an agent from scratch; the later two
reuse an existing agent id so they stay focused on the run-and-fetch calls.
## Create a policy and run a policy-aware agent
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const policy = await client.policies.create({
name: "AML Investigation Policy",
content: {
guidelines: {
categories: [
{
title: "Transaction Patterns",
rules: [
{
title: "Structuring below reporting thresholds",
flag: "RED_FLAG",
description: "Deposits just under CTR thresholds in a short window.",
},
],
},
],
},
dispositions: {
classifications: [
{ name: "SAR", description: "File a Suspicious Activity Report." },
{ name: "DISMISS", description: "Close as non-suspicious." },
],
},
},
});
const agent = await client.agents.create({
name: "AML Investigation Agent",
engineClassId: "AMLInvestigationEngine",
inputDefinitions: [
{ key: "alert_data", data_type: "text/plain", description: "Alert to investigate." },
],
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 made 9 cash deposits of $9,500 over three days." },
timeoutSeconds: 300,
});
const result = await job.wait({ intervalSeconds: 5, timeoutSeconds: 300 });
for (const output of result.outputs) {
console.log(`${output.key}: ${output.value}`);
}
```
## Run an agent and download a saved reference
```typescript theme={null}
import { writeFile } from "node:fs/promises";
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const agentId = process.env.ROE_URL_AGENT_ID;
if (!agentId) throw new Error("Set ROE_URL_AGENT_ID");
const job = await client.agents.run({
agentId,
inputs: { url: "https://www.roe-ai.com/" },
metadata: { use_case: "website-scan" },
});
const result = await job.wait({ intervalSeconds: 5, timeoutSeconds: 300 });
for (const output of result.outputs) {
for (const ref of referencesFrom(output.value)) {
if (!ref.resource_id) continue;
const content = await client.agents.jobs.downloadReference(job.id, ref.resource_id);
await writeFile(`${ref.resource_id}.bin`, content);
}
}
function referencesFrom(value: string): Array<{ resource_id?: string }> {
try {
const payload = JSON.parse(value) as { references?: unknown };
return Array.isArray(payload.references)
? (payload.references as Array<{ resource_id?: string }>)
: [];
} catch {
return [];
}
}
```
## Run a batch of inputs
```typescript theme={null}
import { RoeClient } from "roe-typescript";
const client = new RoeClient();
const agentId = process.env.ROE_TEXT_AGENT_ID;
if (!agentId) throw new Error("Set ROE_TEXT_AGENT_ID");
const batch = await client.agents.runMany({
agentId,
batchInputs: [
{ text: "Summarize the customer complaint." },
{ text: "Extract the requested follow-up action." },
],
timeoutSeconds: 300,
});
const results = await batch.wait({ intervalSeconds: 5, timeoutSeconds: 300 });
for (const result of results) {
for (const output of result.outputs) {
console.log(`${output.key}: ${output.value}`);
}
}
```
# Create Webhook
Source: https://docs.roe-ai.com/api-reference/webhooks/create-webhook
POST /webhooks/
Mixin for organization access validation.
Automatically resolves and validates organization access on every request,
making the organization available as self.organization.
For API key auth: organization is derived from the key (no org_id param needed).
For user auth: organization_id must be provided in the request
(kwargs / headers / body / query params).
Usage:
class MyView(BaseOrganizationAccessMixin, APIView):
def get(self, request):
# self.organization is automatically available
return Response({"org": self.organization.name})
# Delete Webhook
Source: https://docs.roe-ai.com/api-reference/webhooks/delete-webhook
DELETE /webhooks/{webhook_id}/
Mixin for organization access validation.
Automatically resolves and validates organization access on every request,
making the organization available as self.organization.
For API key auth: organization is derived from the key (no org_id param needed).
For user auth: organization_id must be provided in the request
(kwargs / headers / body / query params).
Usage:
class MyView(BaseOrganizationAccessMixin, APIView):
def get(self, request):
# self.organization is automatically available
return Response({"org": self.organization.name})
# Link Agents to Webhook
Source: https://docs.roe-ai.com/api-reference/webhooks/link-agents
POST /webhooks/{webhook_id}/agents/
List agents linked to a webhook, or link new agents.
GET: List all agents linked to this webhook
POST: Link one or more agents to this webhook
# List Webhook Agents
Source: https://docs.roe-ai.com/api-reference/webhooks/list-webhook-agents
GET /webhooks/{webhook_id}/agents/
List agents linked to a webhook, or link new agents.
GET: List all agents linked to this webhook
POST: Link one or more agents to this webhook
# List Webhooks
Source: https://docs.roe-ai.com/api-reference/webhooks/list-webhooks
GET /webhooks/
Mixin for organization access validation.
Automatically resolves and validates organization access on every request,
making the organization available as self.organization.
For API key auth: organization is derived from the key (no org_id param needed).
For user auth: organization_id must be provided in the request
(kwargs / headers / body / query params).
Usage:
class MyView(BaseOrganizationAccessMixin, APIView):
def get(self, request):
# self.organization is automatically available
return Response({"org": self.organization.name})
# Retrieve Webhook
Source: https://docs.roe-ai.com/api-reference/webhooks/retrieve-webhook
GET /webhooks/{webhook_id}/
Mixin for organization access validation.
Automatically resolves and validates organization access on every request,
making the organization available as self.organization.
For API key auth: organization is derived from the key (no org_id param needed).
For user auth: organization_id must be provided in the request
(kwargs / headers / body / query params).
Usage:
class MyView(BaseOrganizationAccessMixin, APIView):
def get(self, request):
# self.organization is automatically available
return Response({"org": self.organization.name})
# Unlink Agent from Webhook
Source: https://docs.roe-ai.com/api-reference/webhooks/unlink-agent
DELETE /webhooks/{webhook_id}/agents/{agent_webhook_id}/
Remove an agent link from a webhook.
# Update Webhook
Source: https://docs.roe-ai.com/api-reference/webhooks/update-webhook
PATCH /webhooks/{webhook_id}/
Mixin for organization access validation.
Automatically resolves and validates organization access on every request,
making the organization available as self.organization.
For API key auth: organization is derived from the key (no org_id param needed).
For user auth: organization_id must be provided in the request
(kwargs / headers / body / query params).
Usage:
class MyView(BaseOrganizationAccessMixin, APIView):
def get(self, request):
# self.organization is automatically available
return Response({"org": self.organization.name})
# Custom API Connector
Source: https://docs.roe-ai.com/data-resources/connectors/custom-api
Connect any REST API to Roe with configurable authentication and endpoints
Connect any REST API to Roe by configuring authentication and endpoint definitions. The Custom API connector lets you bring your own API — whether it's an internal service, a third-party platform, or a proprietary data source — and expose it to agents as callable tools.
## Use Cases
* **Fraud Investigation**: Query internal risk scoring APIs, payment processors, or identity verification services
* **AML Investigation**: Access customer due diligence APIs, sanctions screening, or transaction monitoring systems
* **Merchant Risk**: Connect to underwriting or merchant monitoring APIs for risk assessment and due diligence
* **Product Compliance**: Integrate with regulatory databases or compliance checking APIs to verify product and policy adherence
* **Data Enrichment**: Pull data from any REST API to enrich agent investigations with additional context
## Prerequisites
Before creating a Custom API connection, ensure you have:
1. The **base URL** of the API you want to connect (e.g., `https://api.acme.com/v1`)
2. **Authentication credentials** for one of the supported auth methods
3. **API documentation** for the endpoints you want to expose to agents
## Supported Authentication Methods
The Custom API connector supports four authentication strategies:
| Auth Type | Description | Use When |
| ----------------------------- | ----------------------------------------------- | ------------------------------------------- |
| **API Key** | Send an API key as a header or query parameter | Most common for third-party APIs |
| **Bearer Token** | Static Bearer token in the Authorization header | Pre-issued tokens or personal access tokens |
| **Basic Auth** | HTTP Basic authentication (username/password) | Legacy or internal APIs |
| **OAuth2 Client Credentials** | OAuth2 client credentials flow | Modern APIs with machine-to-machine auth |
## Configure the Connection
### Configuration (Non-Sensitive)
| Field | Required | Description |
| ------------------- | -------- | ---------------------------------------------------------------------------------------- |
| **Base URL** | Yes | Root URL for the API (e.g., `https://api.acme.com/v1`). No trailing slash. |
| **Endpoints** | Yes | List of API endpoints the agent can call (see [Defining Endpoints](#defining-endpoints)) |
| **Default Headers** | No | Headers sent with every request (e.g., `{"Accept": "application/json"}`) |
| **Timeout** | No | Request timeout in seconds (default: 30, max: 120) |
### Authentication (Sensitive)
Credentials are encrypted and stored in AWS Secrets Manager.
| Field | Required | Description |
| --------------- | -------- | ---------------------------------------------------------- |
| **API Key** | Yes | The API key value |
| **Header Name** | No | Header name to send the key in (default: `X-API-Key`) |
| **Location** | No | Where to send the key: `header` (default) or `query_param` |
| Field | Required | Description |
| --------- | -------- | ---------------------- |
| **Token** | Yes | The Bearer token value |
| Field | Required | Description |
| ------------ | -------- | ----------------------- |
| **Username** | Yes | Authentication username |
| **Password** | Yes | Authentication password |
| Field | Required | Description |
| ----------------- | -------- | ------------------------------------------ |
| **Client ID** | Yes | OAuth2 client ID |
| **Client Secret** | Yes | OAuth2 client secret |
| **Token URL** | Yes | OAuth2 token endpoint URL |
| **Scope** | No | OAuth2 scope (space-separated if multiple) |
Roe automatically handles token refresh. Tokens are cached and refreshed 60 seconds before expiry.
## Defining Endpoints
Each endpoint you define becomes a tool that agents can call during investigations. The endpoint **name** is used as the tool identifier, and the **description** is shown to the LLM to help it decide when and how to call it.
Write clear, specific endpoint descriptions. The LLM uses these descriptions to decide which endpoints to call and when. Good descriptions lead to better agent behavior.
### Endpoint Fields
| Field | Required | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------- |
| **Name** | Yes | Unique identifier (e.g., `get_customer`, `search_transactions`). Used as the tool name. |
| **Description** | Yes | What this endpoint does. Shown to the LLM as the tool description. |
| **Method** | No | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` (default: `GET`) |
| **Path** | Yes | URL path appended to the base URL. Use `{param_name}` for path parameters. |
| **Parameters** | No | List of parameters this endpoint accepts (see below) |
| **Response Hint** | No | Hint about the response format to help the LLM interpret results |
### Parameter Fields
| Field | Required | Description |
| --------------- | -------- | ----------------------------------------------------------------- |
| **Name** | Yes | Parameter name (e.g., `customer_id`) |
| **Location** | Yes | Where the parameter is sent: `path`, `query`, `body`, or `header` |
| **Type** | No | Data type: `string` (default), `integer`, `number`, or `boolean` |
| **Description** | No | Human-readable description shown to the LLM |
| **Required** | No | Whether this parameter is required (default: `true`) |
### Example Configuration
```json theme={null}
{
"base_url": "https://api.acme.com/v1",
"default_headers": {
"Accept": "application/json"
},
"timeout_seconds": 30,
"endpoints": [
{
"name": "get_customer",
"description": "Retrieve customer details by ID, including name, email, risk score, and account status",
"method": "GET",
"path": "/customers/{customer_id}",
"parameters": [
{
"name": "customer_id",
"location": "path",
"param_type": "string",
"description": "The unique customer identifier",
"required": true
}
],
"response_hint": "Returns JSON with customer name, email, risk_score, account_status"
},
{
"name": "search_transactions",
"description": "Search transactions by customer ID with optional date range and amount filters",
"method": "GET",
"path": "/transactions",
"parameters": [
{
"name": "customer_id",
"location": "query",
"param_type": "string",
"description": "Filter by customer ID",
"required": true
},
{
"name": "start_date",
"location": "query",
"param_type": "string",
"description": "Start date (YYYY-MM-DD)",
"required": false
},
{
"name": "end_date",
"location": "query",
"param_type": "string",
"description": "End date (YYYY-MM-DD)",
"required": false
},
{
"name": "min_amount",
"location": "query",
"param_type": "number",
"description": "Minimum transaction amount",
"required": false
}
],
"response_hint": "Returns a list of transaction objects with amount, date, type, and status"
},
{
"name": "submit_risk_assessment",
"description": "Submit a risk assessment for a customer with a score and reasoning",
"method": "POST",
"path": "/risk-assessments",
"parameters": [
{
"name": "customer_id",
"location": "body",
"param_type": "string",
"description": "Customer ID to assess",
"required": true
},
{
"name": "risk_score",
"location": "body",
"param_type": "number",
"description": "Risk score from 0 to 100",
"required": true
},
{
"name": "reasoning",
"location": "body",
"param_type": "string",
"description": "Explanation for the risk score",
"required": true
}
]
}
]
}
```
## Test the Connection
Click **Test Connection** to verify that Roe can reach your API. The test will:
1. Apply the configured authentication
2. Send a HEAD request to the base URL
3. Verify the API is reachable (any non-5xx response is considered successful)
The test only checks connectivity to the base URL. Individual endpoint availability is validated when agents call them.
## Using Custom API as a Context Source
Once connected, you can use your Custom API connection as a **context source** in agentic workflows. Each configured endpoint is exposed to the agent as a callable tool.
### Context Source Configuration
```json theme={null}
{
"connection_type": "custom_api",
"name": "Risk Scoring API",
"connection_id": "your-connection-uuid",
"description": "Internal risk scoring API for customer due diligence"
}
```
| Field | Description |
| --------------- | ----------------------------------------------- |
| `name` | Friendly name for this data source |
| `connection_id` | UUID of your Custom API connection |
| `description` | Helps the agent understand when to use this API |
### Agent Capabilities
When a Custom API is configured as a context source, agents can:
* **Discover endpoints**: See all configured endpoint names and descriptions
* **Call endpoints**: Invoke any endpoint with the appropriate parameters
* **Interpret responses**: Use response hints and data to inform investigation findings
* **Chain calls**: Make multiple API calls to gather comprehensive data
## Writing Effective Endpoint Descriptions
The quality of your endpoint descriptions directly impacts how well agents use your API. Here are some guidelines:
Instead of "Get customer", write "Retrieve customer details by ID, including name, email, risk score, and account status"
Explain what each parameter means and what values are accepted, especially for enums or constrained fields
Tell the agent what fields to expect in the response so it can extract the right data
Use descriptive names like `search_transactions` or `get_customer_risk_score` rather than generic names
## Security Best Practices
Use API credentials with the minimum required permissions — read-only where possible
Create dedicated API keys or service accounts for Roe rather than sharing personal credentials
Only expose endpoints that agents actually need — avoid including admin or write endpoints unnecessarily
Review your API logs to audit what data agents are accessing
## Troubleshooting
Verify the base URL is correct and reachable from the internet. Roe cannot connect to private networks or localhost.
The API returned a server error. This is likely an issue with the API itself — verify it's healthy and accepting requests.
The API did not respond within the configured timeout. Check that the URL is correct and the API is responsive. You can increase the timeout up to 120 seconds.
Verify your authentication credentials are correct. For OAuth2, ensure the client ID, secret, and token URL are valid. For API keys, check the header name and location match what the API expects.
The agent tried to call an endpoint name that doesn't match any configured endpoint. Verify the endpoint names in your configuration.
The agent called an endpoint without providing a required parameter. Check that the parameter descriptions are clear enough for the agent to know what values to provide.
Verify the token URL, client ID, and client secret are correct. Ensure the OAuth2 server supports the client credentials grant type.
# Introduction
Source: https://docs.roe-ai.com/data-resources/connectors/introduction
Connect to external data sources
Connect your data sources to Roe to enable agents to access and analyze your data during investigations and workflows.
## Connector Types
Roe supports three categories of connectors:
| Category | Description | Connectors |
| ------------ | ----------------------------------------------- | ------------------- |
| **Database** | SQL data warehouses for structured data queries | Snowflake |
| **Storage** | File storage systems for document access | AWS S3, SharePoint |
| **API** | Third-party services and custom REST APIs | Custom API, Zendesk |
## Available Connectors
Connect to any REST API with configurable authentication and endpoints
Connect to Snowflake data warehouse for transaction and customer data queries
Connect to AWS S3 for file storage and document import
Connect to Microsoft SharePoint for enterprise document access
Connect to Zendesk for customer support tickets and communication history
## Using Connectors as Context Sources
Connectors can be configured as **context sources** in agentic workflows, allowing agents to automatically fetch relevant data during investigations.
### Supported Workflows
The following engines support context sources:
* **[AML Investigation](/agents/engines/aml-investigation)**: Query transaction data and customer information
* **Fraud Investigation**: Access transaction history and support tickets
### Context Source Types
| Connector | Use as Context Source | Agent Capabilities |
| ---------- | --------------------- | ------------------------------------------------------------------------ |
| Custom API | ✅ Yes | Call any configured REST endpoint, parameter injection, response parsing |
| Snowflake | ✅ Yes | Natural language SQL queries, schema discovery, data filtering |
| Zendesk | ✅ Yes | Ticket search, conversation retrieval, customer lookup |
| S3 | Import only | File import to database for processing |
| SharePoint | Import only | File import to database for processing |
## Creating a Connection
Go to the **Connections** page in your Roe workspace
Click **Add Connection** and select your connector type
Enter the required configuration and authentication details for your connector
Click **Test Connection** to verify connectivity before saving
Click **Create** to save your connection
## Security
All connector credentials are:
* **Encrypted** using AWS Secrets Manager
* **Isolated** per organization
* **Audited** for access and usage
Create dedicated service accounts or API tokens for Roe integrations with minimal required permissions for enhanced security.
# AWS S3 Connector
Source: https://docs.roe-ai.com/data-resources/connectors/s3
Connect AWS S3 to Roe
## Requirements
Roe uses [programmatic access](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html?icmpid=docs_iam_console#AccessControlMethods)
to connect to the S3 bucket. You create a new user in the
[IAM Management Console](https://aws.amazon.com/iam/), assign in to a group,
and then create a policy that grants access to the specified S3 bucket.
**Create the policy**
1. Add a new user through the IAM Management Console. You can add the user
to an existing group or create a new group in which to add them. Once
created, generate a set of [access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html?icmpid=docs_iam_console#Using_CreateAccessKey)
. You provide the access key and
secret access key when creating an S3 resource in Roe.
![]()
2. Configure permissions for S3 buckets using [policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)
. Create a new policy using the IAM Management Console that grants
sufficient permission to read and write data to the S3 bucket.
3. Use the console's GUI to create permissions or provide a JSON
configuration. The following configuration grants access to read and write
data for the specified S3 bucket. Update the BUCKET\_NAME placeholders with
the name of your bucket.
![]()
```json Example policy theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetBucketAcl",
"s3:GetBucketCORS",
"s3:GetBucketLocation",
"s3:GetBucketLogging",
"s3:GetBucketNotification",
"s3:GetBucketPolicy",
"s3:GetBucketWebsite",
"s3:GetObject",
"s3:GetObjectAcl",
"s3:GetObjectVersion",
"s3:GetObjectVersionAcl",
"s3:PutObject",
"s3:PutObjectAcl",
"s3:PutObjectTagging",
"s3:PutObjectVersionAcl",
"s3:PutObjectVersionTagging"
],
"Resource": [
"arn:aws:s3:::REPLACE_THIS_BUCKET_NAME",
"arn:aws:s3:::REPLACE_THIS_BUCKET_NAME/*"
]
}
]
}
```
**Attach the policy**
You can attach the policy to either the user or the group to which it
belongs. Select the user group in which the user you created is assigned,
then [attach the policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups_manage_attach-policy.html#).
If you want to avoid having permanent permissions for the S3 bucket granted
to your IAM user, you can configure the user to [assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#)
that has sufficient permissions.
Once the policy is attached, you can create the S3 resource in Roe.
## Configure the resource
* **Name**: A unique name for the resource.
* **Description**: A description of the resource.
* **AWS Access Key**: The access key for the user you created in the IAM
Management Console.
* **AWS Secret Key**: The secret access key for the user you created in the
IAM Management Console.
* **Bucket Name**: The name of the S3 bucket you want to connect to.
## Test the connection
Click **Test Connection** to verify that Roe can successfully connect to the
data source. If the test fails, check the resource settings and try again.
## Save the resource
Click **Create resource** to complete the setup. You can now use the resource to
import data from the S3 bucket into the database.
# SharePoint Connector
Source: https://docs.roe-ai.com/data-resources/connectors/sharepoint
Connect Microsoft SharePoint to Roe for document access
Connect your Microsoft SharePoint site to Roe to access documents and files for agent processing and analysis.
## Use Cases
* **Document Processing**: Access documents stored in SharePoint for extraction and analysis
* **File Import**: Import files from SharePoint into the database for processing
* **Enterprise Data Access**: Connect to your organization's document management system
## Prerequisites
Before connecting SharePoint to Roe, ensure you have:
1. An Azure AD application with appropriate permissions
2. The SharePoint site ID you want to connect
3. Admin access to register applications in Azure AD
## Register an Azure AD Application
Go to [Azure Portal](https://portal.azure.com) and navigate to **Azure Active Directory**
Go to **App registrations → New registration**
* Enter a name (e.g., "Roe SharePoint Integration")
* Select appropriate account type
* Click **Register**
Go to **API permissions → Add a permission → Microsoft Graph**
Add these **Application permissions**:
* `Sites.Read.All` - Read items in all site collections
* `Files.Read.All` - Read files in all site collections
Click **Grant admin consent**
Go to **Certificates & secrets → New client secret**
* Add a description
* Select expiration period
* Click **Add** and copy the secret value immediately
From the **Overview** page, copy:
* **Application (client) ID**
* **Directory (tenant) ID**
Store your client secret securely. It's only shown once when created. Roe encrypts and stores credentials in AWS Secrets Manager.
## Find Your SharePoint Site ID
The site ID format is: `{hostname}:/sites/{site-name}`
For example: `contoso.sharepoint.com:/sites/ProjectDocs`
You can find your site ID in SharePoint Admin Center or by using the Graph API Explorer.
## Configure the Connection
Provide the following information to connect SharePoint:
### Configuration
| Field | Required | Description |
| ----------- | -------- | ------------------------------------------------------------ |
| **Site ID** | Yes | SharePoint site ID (format: `{hostname}:/sites/{site-name}`) |
### Authentication (Sensitive)
| Field | Required | Description |
| ----------------- | -------- | ------------------------------------------ |
| **Client ID** | Yes | Azure AD application (client) ID |
| **Client Secret** | Yes | Client secret for the Azure AD application |
| **Tenant ID** | Yes | Azure AD directory (tenant) ID |
## Test the Connection
Click **Test Connection** to verify that Roe can successfully connect to your SharePoint site. The test will:
1. Authenticate using your Azure AD credentials
2. Verify access to the Microsoft Graph API
3. Confirm access to the specified SharePoint site
## Available Data
Once connected, agents can access:
### Files
* Documents stored in the SharePoint site
* File metadata (name, size, content type)
* Files from the document library root
### Supported File Types
* Documents: PDF, DOCX, XLSX, PPTX
* Data files: CSV, JSON
* Images: PNG, JPG, GIF
## Security & Permissions
Roe only reads files—no documents are created, modified, or deleted
Uses Azure AD application permissions for secure, auditable access
## Troubleshooting
Verify your client ID, client secret, and tenant ID are correct. Client secrets expire—check if yours needs to be regenerated.
Ensure the Azure AD application has `Sites.Read.All` and `Files.Read.All` permissions, and that admin consent has been granted.
Verify the site ID format is correct: `{hostname}:/sites/{site-name}`. Check that the site exists and is accessible.
Ensure there are files in the SharePoint document library root. Files in nested folders may require additional configuration.
# Snowflake Connector
Source: https://docs.roe-ai.com/data-resources/connectors/snowflake
Connect Snowflake data warehouse to Roe
Connect your Snowflake data warehouse to Roe to query transaction data, customer information, and other structured data during agent investigations.
## Use Cases
* **AML/Fraud Investigation**: Query transaction history and customer data during investigations
* **Data Analysis**: Enable agents to explore and analyze data using natural language queries
* **Context Enrichment**: Provide agents with access to your data warehouse for comprehensive analysis
## Prerequisites
Before connecting Snowflake to Roe, ensure you have:
1. A Snowflake account with appropriate permissions
2. A Programmatic Access Token (PAT) **OR** an RSA Key Pair for authentication
3. Access to a warehouse, database, and schema
## Authentication Methods
Roe supports two authentication methods for Snowflake: Programmatic Access Tokens (PAT) and RSA Key Pair authentication. Both methods bypass MFA and are recommended for programmatic access.
### Option 1: Programmatic Access Token (PAT)
Log in to your Snowflake account using [Snowsight](https://app.snowflake.com)
Click on your user menu (top-right) → **My Profile**
Select the **Authentication** tab
Under **Programmatic access tokens**, click **Generate new token**
Copy the token immediately—it's only shown once!
### Option 2: RSA Key Pair Authentication
You can generate an RSA key pair locally and register the public key with your Snowflake user.
Run the following OpenSSL commands in your terminal to generate an encrypted private key and a public key:
```bash theme={null}
# Generate an encrypted private key (you will be prompted to create a passphrase)
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out snowflake_private_key.p8
# Generate the public key
openssl rsa -in snowflake_private_key.p8 -pubout -out snowflake_public_key.pub
```
*Note: If you prefer an unencrypted private key, append `-nocrypt` to the first command.*
Snowflake requires the public key body without the header, footer, or newlines. Extract it using:
```bash theme={null}
awk 'NR > 1 && !/-----END PUBLIC KEY-----/ { printf "%s", $0 }' snowflake_public_key.pub
```
Copy the output.
Log into Snowflake as an admin (e.g., `USERADMIN` or `ACCOUNTADMIN`) and run the following SQL:
```sql theme={null}
ALTER USER your_snowflake_username
SET RSA_PUBLIC_KEY = '';
```
Verify it was set correctly by running `DESC USER your_snowflake_username;`.
Store your PAT or Private Key securely. Roe encrypts and stores credentials in AWS Secrets Manager.
## Configure the Connection
Provide the following information to connect Snowflake:
### Authentication (Sensitive)
Choose your authentication method from the dropdown and provide the corresponding fields:
| Field | Required | Description |
| -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| **Account** | Yes | Snowflake account identifier (e.g., `xy12345.us-east-1`) |
| **Username** | Yes | Your Snowflake username |
| **Authentication Method** | Yes | Choose either **Programmatic Access Token** or **Key Pair** |
| **Token** | Conditional | The PAT (required if using Token auth) |
| **Private Key** | Conditional | The full PEM-encoded RSA private key including header/footer (required if using Key Pair auth) |
| **Private Key Passphrase** | Conditional | The passphrase for your encrypted private key (required if using Key Pair auth with an encrypted key) |
### Configuration
| Field | Required | Description |
| ------------- | -------- | -------------------------------------------------------------------- |
| **Warehouse** | Yes | Snowflake warehouse (compute resource) to use for queries |
| **Database** | Yes | Default database to use for queries |
| **Schema** | Yes | Schema (namespace) within the database. `PUBLIC` is a common default |
| **Role** | No | Snowflake role for access control |
The schema hierarchy in Snowflake is: **Account → Database → Schema → Table**
For example, `PROD_DB.PUBLIC.CUSTOMERS` means:
* Database: `PROD_DB`
* Schema: `PUBLIC`
* Table: `CUSTOMERS`
## Test the Connection
Click **Test Connection** to verify that Roe can successfully connect to your Snowflake instance. The test will:
1. Authenticate using your PAT or Key Pair
2. Verify access to the specified warehouse, database, and schema
3. Run a simple query to confirm connectivity
## Using Snowflake as a Context Source
Once connected, you can use your Snowflake connection as a **context source** in agentic workflows like AML Investigation or Fraud Investigation.
### Context Source Configuration
When configuring an agent to use Snowflake:
```json theme={null}
{
"connection_type": "snowflake",
"name": "Transaction History",
"connection_id": "your-connection-uuid",
"table": "TRANSACTIONS",
"description": "Customer transaction data for the last 12 months"
}
```
| Field | Description |
| --------------- | ------------------------------------------------------------ |
| `name` | Friendly name for this data source |
| `connection_id` | UUID of your Snowflake connection |
| `table` | Table to query (agent generates SELECT queries with filters) |
| `description` | Helps the agent understand what data is available |
### Agent Capabilities
When Snowflake is configured as a context source, agents can:
* **Discover schema**: Automatically understand table structure
* **Generate SQL**: Create appropriate queries based on natural language
* **Filter data**: Apply relevant filters (e.g., customer ID, date ranges)
* **Handle errors**: Recover from query issues gracefully
## Security Best Practices
PATs and Key Pair auth are more secure than passwords and can be revoked independently
Create a dedicated role with read-only access to only the required tables
Use a dedicated warehouse for Roe to manage resource usage
Review Snowflake query history to audit agent data access
## Troubleshooting
Verify your account identifier, username, and PAT or Private Key/Passphrase are correct. PATs expire and may need to be regenerated. If using a Key Pair, ensure the public key matches.
Ensure the warehouse name is correct and your user has USAGE permission on the warehouse.
Verify the database and schema exist and your user has appropriate permissions to access them.
Queries have a 30-second timeout. If your queries are timing out, consider optimizing table indexes or filtering to smaller datasets.
# Zendesk Connector
Source: https://docs.roe-ai.com/data-resources/connectors/zendesk
Connect Zendesk to Roe for customer support data
Connect your Zendesk account to Roe to access customer support tickets, user information, and organization data during agent investigations.
## Use Cases
* **Fraud Investigation**: Review customer support history and communication patterns
* **AML Investigation**: Analyze customer interactions and support ticket content
* **Customer Context**: Provide agents with customer support history for comprehensive analysis
## Prerequisites
Before connecting Zendesk to Roe, ensure you have:
1. A Zendesk account with admin access
2. API Token access enabled
3. An API token generated for Roe
## Generate an API Token
Log in to your Zendesk account and go to **Admin Center**
Go to **Apps and integrations → APIs → Zendesk API**
Ensure **Token Access** is enabled
Click **Add API token**, provide a description (e.g., "Roe Integration"), and click **Copy** to save the token
Store your API token securely. It's only shown once when created. Roe encrypts and stores credentials in AWS Secrets Manager.
## Configure the Connection
Provide the following information to connect Zendesk:
### Configuration
| Field | Required | Description |
| ------------- | -------- | ---------------------------------------------------------------------- |
| **Subdomain** | Yes | Your Zendesk subdomain (e.g., `mycompany` for `mycompany.zendesk.com`) |
### Authentication (Sensitive)
| Field | Required | Description |
| ------------- | -------- | ------------------------------------- |
| **Email** | Yes | Email address of a Zendesk admin user |
| **API Token** | Yes | API token generated from Admin Center |
## Test the Connection
Click **Test Connection** to verify that Roe can successfully connect to your Zendesk instance. The test will:
1. Authenticate using your credentials
2. Verify access to the Zendesk API
3. Fetch a sample of tickets to confirm connectivity
## Available Data
Once connected, agents can access the following Zendesk data:
### Tickets
* Ticket details (subject, description, status, priority)
* Ticket comments and conversation history
* Custom field values
* Tags and metadata
### Users
* User profiles and contact information
* User roles (end-user, agent, admin)
* Organization membership
### Organizations
* Organization details
* Associated users and tickets
### Search
* Full-text search across tickets, users, and organizations
* Filter by status, priority, tags, and custom fields
## Using Zendesk as a Context Source
When configuring an agent to use Zendesk:
```json theme={null}
{
"connection_type": "zendesk",
"name": "Customer Support History",
"connection_id": "your-connection-uuid",
"description": "Pull all support tickets for the customer"
}
```
| Field | Description |
| --------------- | ----------------------------------------------------------------------------- |
| `name` | Friendly name for this data source |
| `connection_id` | UUID of your Zendesk connection |
| `description` | Describes what data to fetch—be specific about what the agent should look for |
### Example Descriptions
* `"Pull all support tickets for this customer"`
* `"Search for tickets mentioning fraud or suspicious activity"`
* `"Get ticket history for the past 30 days"`
* `"Find tickets with the 'escalated' tag"`
## Agent Capabilities
When Zendesk is configured as a context source, agents can:
* **Search tickets**: Find relevant tickets by customer, topic, or keywords
* **Read conversations**: Access full ticket comment threads
* **Analyze patterns**: Identify trends in support interactions
* **Cross-reference**: Correlate support data with other investigation findings
## Security & Permissions
Roe only reads data from Zendesk—no tickets are created or modified
Zendesk API rate limits are respected automatically with cursor-based pagination
## Troubleshooting
Verify your email and API token are correct. Ensure Token Access is enabled in Admin Center → APIs → Zendesk API.
Check that your subdomain is correct. It should be just the subdomain portion (e.g., `mycompany` not `mycompany.zendesk.com`).
The API token may not have sufficient permissions. Ensure the user associated with the token has appropriate access rights.
If you encounter rate limits, wait a moment and try again. Roe automatically handles pagination to minimize API calls.
# Context Sources
Source: https://docs.roe-ai.com/data-resources/context-sources
Configure data sources for agentic workflows
Context sources allow agentic workflows to automatically query your data during investigations. When configured, agents can fetch transaction data, customer information, and support history without manual intervention.
## Overview
Context sources bridge your [Connectors](/data-resources/connectors/introduction) with agentic engines. While connectors establish the connection to your data, context sources configure how agents interact with that data during workflow execution.
## Supported Context Source Types
| Type | Connector | Agent Capabilities |
| ------- | --------------------- | ---------------------------------------------------------- |
| **SQL** | Snowflake, Roe Tables | Natural language queries, schema discovery, data filtering |
| **API** | Zendesk | Ticket search, conversation retrieval, entity lookup |
## Configuring Context Sources
Context sources are configured when setting up an agentic workflow (like AML Investigation). Each context source requires:
### Common Fields
| Field | Required | Description |
| ----------------- | -------- | -------------------------------------------------------------------- |
| `connection_type` | Yes | Type of connector (`snowflake`, `zendesk`, `Roe Tables`) |
| `name` | Yes | Friendly name for this data source |
| `connection_id` | Yes\* | UUID of the pre-configured connector (\*not required for Roe Tables) |
| `description` | No | Helps the agent understand what data is available |
## SQL Context Sources
SQL-based context sources (Snowflake, Roe Tables) enable agents to query structured data using natural language.
### Snowflake Configuration
```json theme={null}
{
"connection_type": "snowflake",
"name": "Transaction History",
"connection_id": "conn_abc123",
"table": "TRANSACTIONS",
"description": "Customer transaction data including amounts, dates, and response codes"
}
```
| Field | Description |
| ----------- | -------------------------------------------------------------------- |
| `table` | Table name for the agent to query |
| `sql_query` | (Optional) Predefined SQL query—overrides automatic query generation |
### Roe Tables Configuration
Roe Tables are stored in Roe Tables and don't require a separate connection.
```json theme={null}
{
"connection_type": "Roe Tables",
"name": "Alert History",
"table": "alerts",
"description": "Historical alert data with resolutions"
}
```
### Agent SQL Capabilities
When configured with SQL context sources, agents can:
1. **Discover Schema**: Automatically understand table structure and column types
2. **Generate Queries**: Create appropriate SQL based on natural language instructions
3. **Apply Filters**: Add relevant WHERE clauses based on investigation context
4. **Handle Errors**: Recover from query issues and retry with corrections
Provide a detailed `description` to help the agent understand what data is available and when to use this source.
## API Context Sources
API-based context sources (Zendesk) enable agents to interact with third-party services.
### Zendesk Configuration
```json theme={null}
{
"connection_type": "zendesk",
"name": "Customer Support History",
"connection_id": "conn_xyz789",
"description": "Pull all support tickets for the customer"
}
```
The `description` field is crucial for Zendesk—it tells the agent what to search for:
| Description Example | Agent Behavior |
| ---------------------------------------------- | ------------------------------------- |
| `"Pull all support tickets for this customer"` | Searches tickets by customer email/ID |
| `"Search for tickets mentioning fraud"` | Searches for fraud-related keywords |
| `"Get tickets with 'escalated' tag"` | Filters by specific tags |
## Example: AML Investigation Setup
Here's a complete context source configuration for an AML investigation:
```json theme={null}
{
"context_sources": [
{
"connection_type": "snowflake",
"name": "Transaction Data",
"connection_id": "conn_sf_123",
"table": "TRANSACTIONS",
"description": "Transaction history with amount, merchant, and response codes"
},
{
"connection_type": "snowflake",
"name": "Customer Profiles",
"connection_id": "conn_sf_123",
"table": "CUSTOMERS",
"description": "Customer KYC data and account information"
},
{
"connection_type": "zendesk",
"name": "Support Tickets",
"connection_id": "conn_zd_456",
"description": "Customer support history and communications"
}
]
}
```
## How Agents Use Context Sources
During investigation, agents follow this flow:
Based on the SOP or investigation requirements, the agent determines what data is needed
The agent chooses the appropriate context source based on the `name` and `description`
For SQL sources, the agent generates a natural language query that's converted to SQL
The query is executed and results are returned to the agent
The agent incorporates the data into its investigation and analysis
## Best Practices
Name context sources clearly (e.g., "Transaction History" not "Table1")
Help agents understand when and how to use each source
Specify specific tables rather than exposing entire databases
Configure connectors with minimal permissions for security
## Related Documentation
Set up connections to your data sources
Configure context sources for AML workflows
# Introduction
Source: https://docs.roe-ai.com/data-resources/introduction
Connect to any data source or manage your data directly on Roe
Roe has a powerful data management system that allows you to connect to any
data source, or manage your data directly on Roe.
Manage your unstructured data on Roe.
Connect to any data source.
# Introduction
Source: https://docs.roe-ai.com/data-resources/roe-datasets/introduction
Manage your files on Roe
Roe has an in-house data management system that allows you to manage your
files directly on Roe.
## Datasets
Think of a dataset as a collection of files like a directory. You can create a
dataset to store your files and manage them easily.
![]()
## Files
Files are the individual data points in a dataset. You can upload, download, and
delete files in a dataset. [APIs](/api-reference/roe-dataset/file-upload) are
available to interact with files in a dataset.
![]()
# Introduction
Source: https://docs.roe-ai.com/database/examples/introduction
SQL workspace usage examples.
Coming soon
# Introduction
Source: https://docs.roe-ai.com/database/functions/introduction
A set of functions dedicated to working with unstructured data
Run an Agent to process unstructured data.
Run an Agent to process unstructured data synchronously.
Get the status of an Agent Job.
Get the result of an Agent Job.
Get the multi-modality similarity score between the data and a natural
language query.
# job_result | resolve
Source: https://docs.roe-ai.com/database/functions/job-result
Get the result of an Agent Job.
## Inputs
`job_id` (String): The ID of the
[Agent Job](/agents/introduction#what-is-an-agent-job) to get the result of.
This is **usually** the output of the [run\_agent](/database/functions/run-agent)
function.
## Output
Varies depending on the Agent. The output of an Agent depends on the underlying
[Enging](/agents/engines/introduction) powering the Agent.
## Example Usage
```sql theme={null}
SELECT job_status('123e4567-e89b-12d3-a456-426614174000');
```
```sql theme={null}
SELECT job_status(run_agent_result_column) FROM data_table;
```
```sql theme={null}
SELECT resolve('123e4567-e89b-12d3-a456-426614174000');
```
```sql theme={null}
SELECT resolve(run_agent_result_column) FROM data_table;
```
# job_status
Source: https://docs.roe-ai.com/database/functions/job-status
Get the status of an Agent Job.
## Inputs
`job_id` (String): The ID of the
[Agent Job](/agents/introduction#what-is-an-agent-job) to get the status of.
This is **usually** the output of the [run\_agent](/database/functions/run-agent)
function.
## Output
The status of the Agent Job. The status can be one of the following:
0: PENDING
1: STARTED
2: RETRY
3: SUCCESS
4: FAILURE
5: CANCELLED
## Example Usage
```sql theme={null}
SELECT job_status('123e4567-e89b-12d3-a456-426614174000');
```
```sql theme={null}
SELECT job_status(run_agent_result_column) FROM data_table;
```
# keep_pages
Source: https://docs.roe-ai.com/database/functions/keep-pages
Select which pages to keep and process in a PDF file.
## Inputs
`file_id` (File ID String): File ID
`str_range` (String): A string containing pages or page ranges e.g. "1, 2, 3-5"
## Output
File ID with metadata appended.
## Example Usage
```sql theme={null}
SELECT keep_pages(
'file_5319316b-1209-1234-9010-0ab35a9af2f9',
"1, 2, 3-5"
);
```
# run_agent
Source: https://docs.roe-ai.com/database/functions/run-agent
Run an Agent to process unstructured data.
## Inputs
`agent_id` (String): The ID of the [Agent](/agents/introduction) to run.
`args` (Map): A map of [Agent Inputs](/agents/input-definition) to pass to the Agent.
## Output
[Agent Job](/agents/introduction#what-is-an-agent-job) ID. You will likely want
to use [job\_status](/database/functions/job-status) and
[job\_result](/database/functions/job-result) to get the status and result of the
Agent Job.
## Example Usage
Assuming the underlying Agent is expecting two Agent inputs with keys `prompt`
and `target`:
```sql theme={null}
SELECT run_agent(
'123e4567-e89b-12d3-a456-426614174000',
map(
'prompt', 'Extract entities',
'target', file_column
)
) FROM data_table;
```
# run_agent_sync
Source: https://docs.roe-ai.com/database/functions/run-agent-sync
Run an Agent to process unstructured data synchronously.
## Inputs
`agent_id` (String): The ID of the [Agent](/agents/introduction) to run.
`args` (Map): A map of [Agent Inputs](/agents/input-definition) to pass to the Agent.
## Output
Varies depending on the Agent. The output of an Agent depends on the underlying
[Enging](/agents/engines/introduction) powering the Agent.
## Example Usage
Assuming the underlying Agent is expecting two Agent inputs with keys `prompt`
and `target`:
```sql theme={null}
SELECT run_agent(
'123e4567-e89b-12d3-a456-426614174000',
map(
'prompt', 'Extract entities',
'target', file_column
)
) FROM data_table;
```
# Introduction
Source: https://docs.roe-ai.com/database/introduction
Index, search, and analyze unstructured data with SQL, no matter the scale.
## Overview
Roe's SQL workspace is a distributed SQL warehouse that allows you to search, process and
analyze unstructured data at scale. It is built on top of ClickHouse and
provides a SQL interface to interact with any type of unstructured data.
Work with your unstructured data at scale in under 5 minutes
Learn about the functions that come created for you.
Explore examples of how to use Roe SQL interface.
# Quickstart
Source: https://docs.roe-ai.com/database/quickstart
Work with your unstructured data at scale in under 5 minutes
## Upload Your Unstructured Data
![]()
For the purpose of this quickstart, we will use the same invoice PDF file as `invoice.pdf` file in the `invoice-extraction-example` dataset. Go to that dataset and download the file first. Then upload to the `default` dataset.
![]()
![]()
![]()
## View Your Data
Click on the Workspace tab to go to ROE SQL workspace.
A default table called `dataset_default` has been created for you. Any new
files uploaded to the `default` dataset will automatically be added to this table as well. You can check the table by clicking `dataset_default` table in the table list.
![]()
Or you can run the following SQL query to view the data in a new worksheet tab:
```sql theme={null}
SELECT * FROM dataset_default;
```
![]()
## Process Your Data
Now that you have uploaded your data, you can start processing it using the
built-in functions. For example, you can extract information from the invoice
PDF with the following SQL query:
```sql theme={null}
-- You're shown three example worksheets for three different use cases. Take a moment to read through each one!
-- This worksheet extracts information from the invoice PDF as specified by the return format requested. Try running it!
SELECT name, file, extract_from(
'returns following structure: {
from: ,
recipient: ,
line_items: [
{
name: -
quantity:
-
cost:
-
},
],
subtotal:
tax:
total:
}', -- extract_from() uses the Default Extraction agent, so you don't need to specify an agent
file
) FROM dataset_examples WHERE dataset='invoice-extraction-example'; -- You can run on all datasets in the table or a specific one (what we do here)
```
The result of the `extract_from` function is a reference to the async job. Once
the job is completed, you can view the extracted data in the worksheet by clicking on the Job ID.
![]()
## Next Steps
### Learn More About Roe SQL
We are based on clickhouse dialect, learn more about clickhouse SQL dialect in their official
[documentation](https://clickhouse.com/docs).
Also check out our [examples](/database/examples/introduction) to see how you
can use SQL to process your data.
### Learn More About Roe SQL Functions
`extract_from` is just one of the many functions you can use to process your
data. We have a variety of functions available to help you process your data
with Roe Agents. You can learn more about the functions available in the
[Functions](/database/functions/introduction) section.
# OIDC Single Sign-On (SSO) Integration
Source: https://docs.roe-ai.com/enterprise/sso
Guide to configuring OIDC SSO for your organization.
# OIDC SSO Integration
This guide explains how to configure OpenID Connect (OIDC) Single Sign-On (SSO) for your organization on our platform.
***
## Prerequisites
Before you begin, ensure you have the following:
1. **OIDC Provider Account:** Access to an OIDC provider (e.g., Microsoft Azure AD, Google, Auth0).
2. **Client Credentials:** Obtain these details from your OIDC provider:
* Client ID
* Client Secret
* Authorization Endpoint
* Token Endpoint
* User Info Endpoint
3. **User Mapping Keys:** Determine the keys your OIDC provider uses for user details:
* User Identifier Key (e.g., `userPrincipalName`, `email`)
* First Name Key
* Last Name Key
***
## Configuration Steps
### Step 1: Enable OIDC SSO
1. Go to **Organization Single Sign-On (SSO)** settings in the application.
2. Toggle SSO to **Enabled**.
3. Select **OIDC** as the SSO protocol.
### Step 2: Fill in the Required Fields
Fill out the following fields using information from your OIDC provider:
| Field | Description |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **OIDC Client ID** | Enter the client ID provided by your OIDC provider. |
| **OIDC Client Secret** | Enter the client secret associated with your client ID. |
| **OIDC Authorization Endpoint** | URL for user authentication (e.g., `https://login.microsoftonline.com//oauth2/v2.0/authorize`). |
| **OIDC Token Endpoint** | URL for exchanging authorization codes for tokens (e.g., `https://login.microsoftonline.com//oauth2/v2.0/token`). |
| **OIDC User Info Endpoint** | URL for retrieving user profile details (e.g., `https://graph.microsoft.com/v1.0/me`). |
### Step 3: Configure User Mapping
Specify the user information fields returned by your OIDC provider:
| Field | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **OIDC User Identifier Key** | The field from the user info response that uniquely identifies a user (e.g., `userPrincipalName`, `email`). |
| **OIDC User First Name Key** | The field representing the user's first name (e.g., `givenName`). |
| **OIDC User Last Name Key** | The field representing the user's last name (e.g., `surname`). |
> **Note:** If your OIDC provider uses the same key for both first and last names (e.g., `displayName`), use that key in both fields.
### Step 4: Save Changes
Click the **Save Changes** button to store your configuration. The SSO login will be enabled for your organization.
***
## Testing the Integration
1. Log out of your account.
2. Click **Sign In** on the login page.
3. Select the **Sign in with SSO** option.
4. Authenticate through your OIDC provider.
5. Verify that:
* You are redirected back to the application.
* User details (e.g., name, email) are correctly displayed.
***
## Example Configuration for Microsoft Azure AD
Here’s an example configuration for Azure AD:
| Field | Value |
| ------------------------------- | --------------------------------------------------------------------- |
| **OIDC Client ID** | `` |
| **OIDC Client Secret** | `` |
| **OIDC Authorization Endpoint** | `https://login.microsoftonline.com//oauth2/v2.0/authorize` |
| **OIDC Token Endpoint** | `https://login.microsoftonline.com//oauth2/v2.0/token` |
| **OIDC User Info Endpoint** | `https://graph.microsoft.com/v1.0/me` |
| **OIDC User Identifier Key** | `userPrincipalName` |
| **OIDC User First Name Key** | `givenName` |
| **OIDC User Last Name Key** | `surname` |
Replace `` with your Azure AD tenant ID.
***
## Troubleshooting
* **Invalid Client ID/Secret:** Ensure the client ID and secret are correct.
* **Authorization Error:** Verify the authorization endpoint URL and ensure the redirect URI matches the one registered with your OIDC provider.
* **User Info Mapping Issues:** Test the user info endpoint response using a tool like Postman to confirm the keys match your configuration.
***
Need help? Contact our support team for assistance!
# ADFS OIDC SSO Integration Guide
Source: https://docs.roe-ai.com/enterprise/sso-adfs
This guide explains how to integrate **Active Directory Federation Services (ADFS)** with your platform using OpenID Connect (OIDC) for Single Sign-On (SSO). It includes detailed instructions for retrieving the required configuration data from ADFS.
***
## Prerequisites
Before starting, ensure you have:
1. **Access to the ADFS Management Console** with admin permissions.
2. An SSL certificate installed and configured for your ADFS server.
***
## Steps for Customers to Obtain Configuration Data
Follow these steps to set up ADFS and retrieve the necessary information for integration.
### Step 1: Create a New Application Group in ADFS
1. Open the **ADFS Management Console** on your ADFS server.
2. In the left-hand menu, expand **ADFS** > **Application Groups**.
3. Right-click **Application Groups** and select **Add Application Group**.
4. Enter a name for your application group (e.g., `Your Platform SSO`) and choose **Server application accessing a web API**.
5. Click **Next**.
***
### Step 2: Configure the Server Application
1. On the **Server application** page:
* **Client Identifier**: Enter a unique identifier (e.g., `your-platform-client-id`).
* Click **Add Application** and enter the Roe **Redirect URI** `https://app.roe-ai.com/sso/callback`.
2. Click **Next**.
***
### Step 3: Configure the Web API
1. On the **Web API** page:
* Leave the **Identifier** field as the default value (e.g., `https:///adfs/services/trust`).
* Click **Next**.
***
### Step 4: Generate a Client Secret
1. On the **Client Secret** page:
* Click **Generate a shared secret** and copy the generated value. This will be used as the **OIDC Client Secret**.
* Click **Next**.
***
### Step 5: Configure Application Permissions
1. On the **Configure Application Permissions** page:
* Ensure the default permission **openid** is enabled.
* Add any additional permissions required by your platform (e.g., `email`, `profile`).
* Click **Next**.
***
### Step 6: Collect the ADFS Endpoints
1. Open the **ADFS Federation Metadata XML** by navigating to `https:///FederationMetadata/2007-06/FederationMetadata.xml`.
2. Extract the following URLs from the metadata:
* **Authorization Endpoint**: `https:///adfs/oauth2/authorize`
* **Token Endpoint**: `https:///adfs/oauth2/token`
* **User Info Endpoint**: Add `/userinfo` to the base ADFS server URL (e.g., `https:///adfs/oauth2/userinfo`).
Replace `` with the URL of your ADFS server.
***
## Configuration on Your Platform
Once you’ve collected the necessary information from ADFS, configure your platform as follows:
| Field | Value |
| ------------------------------- | --------------------------------------------- |
| **OIDC Client ID** | The **Client Identifier** configured in ADFS. |
| **OIDC Client Secret** | The **Client Secret** generated in Step 4. |
| **OIDC Authorization Endpoint** | `https:///adfs/oauth2/authorize` |
| **OIDC Token Endpoint** | `https:///adfs/oauth2/token` |
| **OIDC User Info Endpoint** | `https:///adfs/oauth2/userinfo` |
| **OIDC User Identifier Key** | `sub` |
| **OIDC User First Name Key** | `given_name` |
| **OIDC User Last Name Key** | `family_name` |
***
## Testing the Integration
1. Log out of your account on the platform.
2. Go to the login page and select **Sign in with SSO**.
3. Authenticate via ADFS.
4. Verify that:
* You are redirected back to the platform.
* Your user details (e.g., name, email) are displayed correctly.
***
## Troubleshooting
* **Invalid Client ID/Secret**:
* Verify the Client ID and Client Secret are entered correctly in your platform.
* **Authorization Errors**:
* Ensure the Redirect URI matches the one configured in ADFS.
* **User Info Mapping Issues**:
* Use a tool like Postman to test the User Info Endpoint (`https:///adfs/oauth2/userinfo`) and validate the keys.
***
For further assistance, contact our support team.
# Microsoft Entra ID (Azure AD) OIDC SSO Integration
Source: https://docs.roe-ai.com/enterprise/sso-entraid
This guide explains how to integrate Microsoft Entra ID (Azure AD) with your platform using OpenID Connect (OIDC) for Single Sign-On (SSO). It also provides detailed steps for customers to obtain the necessary configuration data from their Microsoft Entra ID tenant.
***
## Prerequisites
Before starting, ensure you have:
1. Access to the **Microsoft Entra Admin Center** with permissions to register applications.
2. A valid Microsoft Entra ID tenant.
3. Admin credentials for your organization’s Microsoft Entra ID tenant.
***
## Steps for Customers to Obtain Configuration Data
Follow these steps to retrieve the required information from Microsoft Entra ID.
### Step 1: Register an Application in Microsoft Entra ID
1. Log in to the [Microsoft Entra Admin Center](https://entra.microsoft.com/).
2. Navigate to **App registrations** in the left-hand menu.
3. Click **New registration** and fill out the following details:
* **Name**: Enter a name for your application (e.g., `Roe SSO Integration App`).
* **Supported account types**: Choose one of the following:
* **Accounts in this organizational directory only** (Single tenant).
* **Accounts in any organizational directory** (Multitenant).
* **Redirect URI**: Under **Web**, enter the URL of Roe callback endpoint `https://app.roe-ai.com/sso/callback`.
4. Click **Register** to create the application.
***
### Step 2: Retrieve the Client ID and Tenant ID
1. After registration, you’ll be redirected to the application overview page.
2. Note the **Application (client) ID** and **Directory (tenant) ID** from this page. These will be used as the **OIDC Client ID** and **Tenant ID**, respectively.
***
### Step 3: Generate a Client Secret
1. In the application overview, navigate to **Certificates & secrets** in the left-hand menu.
2. Under **Client secrets**, click **New client secret**.
3. Add a description (e.g., `Platform SSO Secret`) and set an expiration period (e.g., 1 year).
4. Click **Add**. Once created, copy the **Value** of the client secret. This will be used as the **OIDC Client Secret**.
> **Note:** You won’t be able to view this secret again, so copy and store it securely.
***
### Step 4: Configure API Permissions
1. Navigate to **API permissions** in the left-hand menu.
2. Click **Add a permission** and choose **Microsoft Graph**.
3. Select the following permissions:
* **Delegated Permissions**:
* `openid`
* `profile`
* `email`
* `offline_access`
* **Optional**: Add `User.Read` if you need to access additional user details.
4. Click **Add permissions**.
5. Click **Grant admin consent for \[your tenant name]** to grant the necessary permissions.
***
### Step 5: Collect Endpoint URLs
1. Go to the **Endpoints** tab in the Microsoft Entra Admin Center.
2. Note the following endpoint URLs:
* **Authorization Endpoint**: Copy the URL labeled **OAuth 2.0 authorization endpoint (v2)**.
* **Token Endpoint**: Copy the URL labeled **OAuth 2.0 token endpoint (v2)**.
* **User Info Endpoint**: Use `https://graph.microsoft.com/v1.0/me` to fetch user details.
***
## Configuration on Your Platform
Once you’ve collected the necessary information from Microsoft Entra ID, configure it on your platform as follows:
| Field | Value |
| ------------------------------- | ---------------------------------------------------------------------- |
| **OIDC Client ID** | The **Application (client) ID** retrieved from the Azure portal. |
| **OIDC Client Secret** | The **Client secret** value generated in Step 3. |
| **OIDC Authorization Endpoint** | The **OAuth 2.0 authorization endpoint (v2)** URL retrieved in Step 5. |
| **OIDC Token Endpoint** | The **OAuth 2.0 token endpoint (v2)** URL retrieved in Step 5. |
| **OIDC User Info Endpoint** | `https://graph.microsoft.com/v1.0/me` |
| **OIDC User Identifier Key** | `userPrincipalName` |
| **OIDC User First Name Key** | `givenName` |
| **OIDC User Last Name Key** | `surname` |
***
## Testing the Integration
1. Log out of your account on the platform.
2. Go to the login page and select **Sign in with SSO**.
3. Authenticate through Microsoft Entra ID.
4. Verify that:
* You are redirected back to the platform.
* Your user details (e.g., name, email) are displayed correctly.
***
## Troubleshooting
* **Invalid Client ID/Secret**:
* Ensure the Client ID and Client Secret are entered correctly.
* **Authorization Errors**:
* Verify the redirect URI matches the one registered in Microsoft Entra ID.
* **User Info Mapping Issues**:
* Use a tool like Postman to test the User Info Endpoint (`https://graph.microsoft.com/v1.0/me`) and validate the keys.
***
For further assistance, contact our support team.
# Okta OIDC SSO Integration Guide
Source: https://docs.roe-ai.com/enterprise/sso-okta
This guide explains how to integrate **Okta** with your platform using OpenID Connect (OIDC) for Single Sign-On (SSO). It includes detailed instructions for obtaining the required configuration data from Okta.
***
## Prerequisites
Before starting, ensure you have:
1. An **Okta Admin Account** with the ability to create and manage applications.
2. Access to your **Okta Organization Domain** (e.g., `dev-123456.okta.com`).
***
## Steps for Customers to Obtain Configuration Data
Follow these steps to retrieve the necessary information from Okta.
### Step 1: Create an Application in Okta
1. Log in to the [Okta Admin Console](https://admin.okta.com/).
2. Navigate to **Applications** > **Applications** in the left-hand menu.
3. Click **Create App Integration**.
4. Select **OIDC - OpenID Connect** as the Sign-in method and choose **Web Application**.
5. Click **Next**.
***
### Step 2: Configure the Application
1. Fill out the following details:
* **App Integration Name**: Enter a name for your app (e.g., `Roe SSO Integration App`).
* **Sign-in Redirect URIs**: Add Roe platform's SSO callback URL `https://app.roe-ai.com/sso/callback`.
* **Assignments**: Choose who can access this application (e.g., "Everyone").
2. Click **Save**.
***
### Step 3: Retrieve Client Credentials
1. After saving, you’ll be redirected to the application's **General** settings page.
2. Note the following:
* **Client ID**: This will be used as the **OIDC Client ID**.
* **Client Secret**: Click **Edit** under **Client Credentials** to reveal and copy the **Client Secret**. This will be used as the **OIDC Client Secret**.
> **Important**: Store the Client Secret securely, as it will not be visible again.
***
### Step 4: Enable OIDC Scopes
1. Go to **Security** > **API** in the left-hand menu.
2. Under **Authorization Servers**, select the **default** authorization server.
3. Navigate to the **Scopes** tab and ensure the following scopes are enabled:
* `openid`
* `profile`
* `email`
* `offline_access` (if your platform supports refreshing tokens).
***
### Step 5: Collect Endpoint URLs
1. From the **default** authorization server, navigate to the **Metadata URI** link (e.g., `https:///oauth2/default/.well-known/openid-configuration`).
2. Use this metadata to retrieve the following endpoints:
* **Authorization Endpoint**: `/oauth2/default/v1/authorize`
* **Token Endpoint**: `/oauth2/default/v1/token`
* **User Info Endpoint**: `/oauth2/default/v1/userinfo`
Replace `` with your Okta organization domain (e.g., `dev-123456.okta.com`).
***
## Configuration on Your Platform
Once you’ve collected the necessary information, configure your platform as follows:
| Field | Value |
| ------------------------------- | --------------------------------------------------------------- |
| **OIDC Client ID** | The **Client ID** retrieved from the Okta Admin Console. |
| **OIDC Client Secret** | The **Client Secret** retrieved from the Okta Admin Console. |
| **OIDC Authorization Endpoint** | The **Authorization Endpoint** URL retrieved from the metadata. |
| **OIDC Token Endpoint** | The **Token Endpoint** URL retrieved from the metadata. |
| **OIDC User Info Endpoint** | The **User Info Endpoint** URL retrieved from the metadata. |
| **OIDC User Identifier Key** | `sub` |
| **OIDC User First Name Key** | `given_name` |
| **OIDC User Last Name Key** | `family_name` |
***
## Testing the Integration
1. Log out of your account on the platform.
2. Go to the login page and select **Sign in with SSO**.
3. Authenticate via Okta.
4. Verify that:
* You are redirected back to the platform.
* Your user details (e.g., name, email) are displayed correctly.
***
## Troubleshooting
* **Invalid Client ID/Secret**:
* Ensure the Client ID and Client Secret are entered correctly in your platform.
* **Authorization Errors**:
* Verify the redirect URI matches the one configured in Okta.
* **User Info Mapping Issues**:
* Use a tool like Postman to test the User Info Endpoint (`https:///oauth2/default/v1/userinfo`) and validate the keys.
***
For further assistance, contact our support team.
# SAML Single Sign-On (SSO) Integration
Source: https://docs.roe-ai.com/enterprise/sso-saml
Guide to configuring SAML SSO for your organization.
# SAML SSO Integration
This guide explains how to configure Security Assertion Markup Language (SAML) Single Sign-On (SSO) for your organization on our platform.
***
## Prerequisites
Before you begin, ensure you have the following:
1. **SAML Identity Provider (IdP) Account:** Access to a SAML 2.0 compatible identity provider (e.g., Microsoft Entra ID, Okta, ADFS).
2. **IdP Configuration Details:** Obtain these details from your identity provider:
* IdP Entity ID
* IdP SSO URL (Single Sign-On Service URL)
* IdP X.509 Certificate (PEM format)
3. **Attribute Mapping:** Determine which SAML attributes your IdP uses for user details:
* User Identifier (email attribute)
* First Name attribute
* Last Name attribute
***
## Service Provider (SP) Information
When configuring your identity provider, you'll need the following information about Roe:
| Field | Value |
| ---------------------------------------- | ------------------------------------------------------------------ |
| **SP Entity ID** | `https://api.roe-ai.com/sso/saml/metadata//` |
| **Assertion Consumer Service (ACS) URL** | `https://api.roe-ai.com/sso/saml/acs/` |
| **SP Metadata URL** | `https://api.roe-ai.com/sso/saml/metadata//` |
> **Note:** Replace `` with your actual organization ID from the Roe platform.
***
## Configuration Steps
### Step 1: Enable SAML SSO
1. Go to **Organization Single Sign-On (SSO)** settings in the application.
2. Toggle SSO to **Enabled**.
3. Select **SAML** as the SSO protocol.
### Step 2: Fill in the Required Fields
Fill out the following fields using information from your identity provider:
| Field | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **SAML IdP Entity ID** | The unique identifier for your identity provider (e.g., `https://sts.windows.net//`). |
| **SAML IdP SSO URL** | The URL where authentication requests are sent (e.g., `https://login.microsoftonline.com//saml2`). |
| **SAML IdP X.509 Certificate** | The public certificate from your IdP used to verify SAML responses (PEM format). |
### Step 3: Configure Optional Settings
| Field | Description | Default |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------- |
| **SAML SP Entity ID** | Custom Service Provider Entity ID. If not set, defaults to the metadata URL. | Auto-generated |
| **NameID Format** | The format for the NameID in SAML assertions. Options: `emailAddress`, `persistent`, `transient`, `unspecified`. | `emailAddress` |
| **Want Assertions Signed** | Require the IdP to sign SAML assertions. | `True` |
| **Want Response Signed** | Require the IdP to sign the entire SAML response. | `False` |
### Step 4: Configure Attribute Mapping
Specify the SAML attribute names returned by your identity provider:
| Field | Description | Default |
| ---------------------------- | -------------------------------------------------- | ------------ |
| **SAML User Identifier Key** | The attribute containing the user's email address. | `email` |
| **SAML User First Name Key** | The attribute containing the user's first name. | `first_name` |
| **SAML User Last Name Key** | The attribute containing the user's last name. | `last_name` |
> **Note:** Our platform supports common attribute name variations automatically. For example, for email, we check: `email`, `emailAddress`, `Email`, `mail`, and standard SAML/LDAP URIs.
### Step 5: Save Changes
Click the **Save Changes** button to store your configuration. The SAML SSO login will be enabled for your organization.
***
## Supported Attribute Names
Our platform automatically maps common attribute name variations:
### Email Attributes
* `email`, `emailAddress`, `Email`, `EmailAddress`, `mail`
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
* `urn:oid:0.9.2342.19200300.100.1.3`
### First Name Attributes
* `first_name`, `firstName`, `givenName`, `given_name`
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
* `urn:oid:2.5.4.42`
### Last Name Attributes
* `last_name`, `lastName`, `surname`, `sn`, `family_name`
* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`
* `urn:oid:2.5.4.4`
***
## Testing the Integration
1. Log out of your account.
2. Click **Sign In** on the login page.
3. Select the **Sign in with SSO** option.
4. Enter your organization's email domain or identifier.
5. Authenticate through your SAML identity provider.
6. Verify that:
* You are redirected back to the application.
* User details (e.g., name, email) are correctly displayed.
***
## Example Configuration for Microsoft Entra ID
Here's an example configuration for Microsoft Entra ID (Azure AD):
| Field | Value |
| ------------------------------ | -------------------------------------------------------------------- |
| **SAML IdP Entity ID** | `https://sts.windows.net//` |
| **SAML IdP SSO URL** | `https://login.microsoftonline.com//saml2` |
| **SAML IdP X.509 Certificate** | (Download from Azure AD SAML configuration) |
| **SAML User Identifier Key** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
| **SAML User First Name Key** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
| **SAML User Last Name Key** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` |
Replace `` with your Azure AD tenant ID.
***
## Troubleshooting
* **Invalid IdP Certificate:** Ensure the certificate is in PEM format and includes the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` headers.
* **Signature Validation Error:** Verify that "Want Assertions Signed" matches your IdP's signing configuration.
* **User Not Found:** Check that the user identifier attribute contains a valid email address.
* **Attribute Mapping Issues:** Use your IdP's SAML tracer or test tool to inspect the actual attribute names being sent in the SAML response.
* **Clock Skew Errors:** Ensure the server time on both the IdP and SP are synchronized. Our platform allows up to 2 minutes of clock skew.
***
Need help? Contact our support team for assistance!
# Microsoft Entra ID (Azure AD) SAML SSO Integration
Source: https://docs.roe-ai.com/enterprise/sso-saml-entraid
This guide explains how to integrate Microsoft Entra ID (Azure AD) with your platform using SAML 2.0 for Single Sign-On (SSO). It provides detailed steps for configuring an enterprise application in Microsoft Entra ID.
***
## Prerequisites
Before starting, ensure you have:
1. Access to the **Microsoft Entra Admin Center** with permissions to create enterprise applications.
2. A valid Microsoft Entra ID tenant.
3. Admin credentials for your organization's Microsoft Entra ID tenant.
***
## Steps to Configure Microsoft Entra ID SAML
Follow these steps to set up SAML SSO with Microsoft Entra ID.
### Step 1: Create an Enterprise Application
1. Log in to the [Microsoft Entra Admin Center](https://entra.microsoft.com/).
2. Navigate to **Enterprise applications** in the left-hand menu.
3. Click **New application**.
4. Click **Create your own application**.
5. Enter a name for your application (e.g., `Roe SSO Integration`).
6. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
7. Click **Create**.
***
### Step 2: Configure SAML Single Sign-On
1. In your new application, navigate to **Single sign-on** in the left-hand menu.
2. Select **SAML** as the single sign-on method.
3. In the **Basic SAML Configuration** section, click **Edit** and fill in:
* **Identifier (Entity ID)**: `https://api.roe-ai.com/sso/saml/metadata//`
* **Reply URL (Assertion Consumer Service URL)**: `https://api.roe-ai.com/sso/saml/acs/`
4. Click **Save**.
> **Note:** Replace `` with your actual organization ID from the Roe platform.
***
### Step 3: Configure Attributes & Claims
1. In the **Attributes & Claims** section, click **Edit**.
2. Ensure the following claims are configured:
| Claim name | Value |
| -------------------------------------------------------------------- | --------------------------------------- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` or `user.userprincipalname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.givenname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.surname` |
3. Click **Save** to apply changes.
> **Tip:** If your users' email addresses are stored in `userPrincipalName` rather than `mail`, use `user.userprincipalname` for the email claim.
***
### Step 4: Download the Certificate
1. In the **SAML Certificates** section, find **Certificate (Base64)**.
2. Click **Download** to download the certificate file.
3. Open the downloaded file in a text editor to get the PEM-formatted certificate.
***
### Step 5: Retrieve IdP Configuration
1. In the **Set up \[Your App Name]** section, note the following:
* **Login URL**: This will be used as the **SAML IdP SSO URL**.
* **Microsoft Entra Identifier**: This will be used as the **SAML IdP Entity ID**.
***
### Step 6: Assign Users and Groups
1. Navigate to **Users and groups** in the left-hand menu.
2. Click **Add user/group**.
3. Select the users or groups who should have access to the application.
4. Click **Assign**.
***
## Configuration on Your Platform
Once you've collected the necessary information from Microsoft Entra ID, configure your platform as follows:
| Field | Value |
| ------------------------------ | -------------------------------------------------------------------- |
| **SAML IdP Entity ID** | The **Microsoft Entra Identifier** from Azure. |
| **SAML IdP SSO URL** | The **Login URL** from Azure. |
| **SAML IdP X.509 Certificate** | The certificate downloaded in Step 4 (PEM format). |
| **SAML User Identifier Key** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
| **SAML User First Name Key** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
| **SAML User Last Name Key** | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` |
***
## Testing the Integration
1. Log out of your account on the platform.
2. Go to the login page and select **Sign in with SSO**.
3. Authenticate through Microsoft Entra ID.
4. Verify that:
* You are redirected back to the platform.
* Your user details (e.g., name, email) are displayed correctly.
***
## Troubleshooting
* **Invalid Reply URL Error**:
* Ensure the Reply URL matches exactly: `https://api.roe-ai.com/sso/saml/acs/`
* **Certificate Errors**:
* Verify the certificate is in PEM format (starts with `-----BEGIN CERTIFICATE-----`).
* Ensure you downloaded the correct certificate (Base64 format).
* **User Not Found**:
* Verify the user has been assigned to the enterprise application.
* Check that the email claim is configured correctly.
* **Attribute Mapping Issues**:
* Use a SAML debugging tool to inspect the claims being sent.
* Ensure the claim names match the expected values.
* **AADSTS Errors**:
* `AADSTS700016`: Application not found. Verify the Entity ID is correct.
* `AADSTS50011`: Reply URL mismatch. Check the ACS URL configuration.
***
For further assistance, contact our support team.
# Introduction
Source: https://docs.roe-ai.com/introduction
Welcome to Roe's Documentation
![Hero Light]()
![Hero Dark]()
Start analyzing your unstructured data in under 5 minutes
Manage your unstructured data with our Roe API
Learn to use SQL in Roe
# Introduction
Source: https://docs.roe-ai.com/mcp/introduction
Connect ChatGPT, Claude, Claude Code, Codex, and Cursor to Roe over OAuth or a Roe API key
Roe hosts an [MCP](https://modelcontextprotocol.io) server that exposes your
agents, tables, jobs, policies, and connections as tools your AI assistant can
call directly — *"list my Roe agents"*, *"run the merchant-risk agent on this
URL"*, *"query my tables"*. One URL, OAuth sign-in, done.
## Set up
Connect your client to:
```text theme={null}
https://mcp.roe-ai.com/mcp
```
(Single-tenant deployment? Use `https://mcp..roe-ai.com/mcp` everywhere
below.) The first time you connect, a browser window opens the Roe sign-in —
approve it once and the client remembers you.
**Settings → Connectors → Create** (on Plus/Pro, enable Developer mode under
Connectors → Advanced first). Name it `Roe`, paste the MCP URL, keep **OAuth**,
click **Connect**. Enable Roe from the **+ / tools** menu in a chat. Connectors
are account-wide, so web and desktop share it.
**Settings → Connectors → Add custom connector** (same flow on claude.ai and
Claude Desktop). Paste the MCP URL, click **Add → Connect**, finish the Roe
OAuth flow. On Team/Enterprise an Owner adds it org-wide first, then members
connect individually.
```bash theme={null}
claude mcp add --transport http roe https://mcp.roe-ai.com/mcp
```
Then run `/mcp` in a session, pick `roe`, and finish the browser sign-in.
```bash theme={null}
codex mcp add roe --url https://mcp.roe-ai.com/mcp
codex mcp login roe --scopes mcp.tools
```
Restart `codex`; check with `codex mcp list`.
Add to `~/.cursor/mcp.json` and restart Cursor — it prompts for the OAuth
sign-in on first use:
```json theme={null}
{
"mcpServers": {
"roe": { "url": "https://mcp.roe-ai.com/mcp" }
}
}
```
**Verify:** ask your assistant to *"use the Roe whoami tool"*. A successful
reply returns your `user_id`, `org_id`, and `email`.
### Prefer an API key?
Clients that support custom headers (**Claude Code**, **Cursor**, **Codex**)
can skip OAuth — good for scripts and CI. Send both headers on every call:
| Header | Value | Where to get it |
| ----------------------- | ------------------ | ---------------------------------------------------------------------------- |
| `Authorization` | `Bearer ` | [app.roe-ai.com/settings/api-keys](https://app.roe-ai.com/settings/api-keys) |
| `X-Roe-Organization-Id` | `` | **Settings → Organization** in the same Roe app |
For example, in Claude Code:
```bash theme={null}
claude mcp add --transport http roe https://mcp.roe-ai.com/mcp \
--header "Authorization: Bearer your-org-api-key" \
--header "X-Roe-Organization-Id: your-org-uuid"
```
Cursor takes the same two headers in a `headers` block in `mcp.json`; Codex
needs them bridged through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote).
ChatGPT and Claude's connector UIs don't expose custom headers, so they always
use OAuth.
Want to **build workflows** — agents chained into pipelines with loops,
branches, and merges — straight from your assistant? Install the
[Workflow Builder skill](/mcp/skills/workflow-builder); it teaches the model
every workflow-authoring nuance.
## Tools
The exact set depends on your deployment — check the tool list your server
advertises, or ask the assistant to call `get_help`. See the generated
[MCP tools reference](/mcp/tools) for the full current list with inputs and
behavior notes.
`get_agent_job_status` returns an integer: `0` PENDING, `1` STARTED, `2` RETRY,
`3` SUCCESS, `4` FAILURE, `5` CANCELLED, `6` CACHED — stop polling on 3/4/5/6.
For the judgment calls between these tools — sync vs async vs batch, polling,
table-query flow, error handling — install the
[Roe MCP Basics skill](/mcp/skills/roe-mcp-basics).
## Troubleshooting
| Symptom | Fix |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| No Roe tools after editing config | Restart the client — MCP config loads at startup. |
| `401` | OAuth: reconnect through the client's connector UI. API key: check the key isn't revoked and the `X-Roe-Organization-Id` header is present, from the same backend. |
| `503` with `Retry-After` | Rate-limited or briefly unreachable — back off and retry. |
| Wrong tenant | Use your tenant's MCP URL with a key/org-id minted on that same tenant. |
Need help? Email [support@roe-ai.com](mailto:support@roe-ai.com).
# Roe MCP Basics
Source: https://docs.roe-ai.com/mcp/skills/roe-mcp-basics
Teach your assistant the Roe MCP fundamentals — run-mode selection, job polling, table queries, auth and error handling — with one installable skill
The Roe MCP tools are self-describing, but the judgment calls between them —
sync vs async runs, when to batch, how to poll jobs and table queries, what a
`503` means versus a `401` — live across many tool descriptions. This skill
puts all of it in your assistant's context up front, so it picks the right
tool the first time.
Install it alongside the [Workflow Builder skill](/mcp/skills/workflow-builder),
which covers authoring multi-step workflows; this one covers everything else.
## Install the skill
Save the block to `~/.claude/skills/roe-mcp-basics/SKILL.md` (or
`.claude/skills/roe-mcp-basics/SKILL.md` inside a project) and restart Claude
Code.
Save the block to `.cursor/rules/roe-mcp-basics.mdc`, replacing the
`name:`/`description:` frontmatter with Cursor's
[rule frontmatter](https://docs.cursor.com/context/rules):
```markdown theme={null}
---
description: Call Roe agents, tables, jobs, policies, and connections via the Roe MCP server — run-mode selection, job polling, table queries, auth and error handling.
alwaysApply: false
---
```
Append the block's body (everything from `# Roe MCP basics` down) to your
project's `AGENTS.md`, or to `~/.codex/AGENTS.md` to apply it globally.
This page is served as plain Markdown at
[docs.roe-ai.com/mcp/skills/roe-mcp-basics.md](https://docs.roe-ai.com/mcp/skills/roe-mcp-basics.md)
(and listed in [docs.roe-ai.com/llms.txt](https://docs.roe-ai.com/llms.txt)).
Paste it into a system prompt or project instructions.
## The skill
```markdown theme={null}
---
name: roe-mcp-basics
description: Call Roe agents, tables, jobs, policies, and connections via the hosted Roe MCP server. TRIGGER when the user wants to run/list/manage Roe agents, query or upload Roe tables, check Roe jobs, or work with Roe policies/connections. SKIP for authoring multi-step Roe workflows (use the roe-workflow-authoring skill) and for non-Roe MCP servers.
---
# Roe MCP basics
Start with `whoami` to confirm the connection — it returns
`{user_id, org_id, email, source}` (`source` is `mcp-oauth` for OAuth,
`mcp-bearer` for API-key auth). Every call is scoped to that org; you cannot
act outside it. Never invent ids or names — discover them with the `list_*`
tools first. List tools paginate: stop when `len(results) < page_size`.
## Running agents — decision tree
1. One run, expected under ~25 seconds → `run_agent` (synchronous, returns
the result directly).
2. One run, longer than ~25 seconds or you want a job id → `trigger_agent_run`
→ poll `get_agent_job_status` until terminal → `get_agent_job_result`.
3. Three or more input sets for the SAME agent → `run_agents_batch` → poll
`get_agent_jobs_status_batch` → `get_agent_jobs_result_batch`. Batch runs
the agent's CURRENT version only (no `version_id`), and `metadata` is
batch-level, not per input.
Inputs must match the keys in `get_current_agent_version.input_definitions`
(or `get_agent_version.input_definitions` when passing `version_id`).
Reserved input keys: `metadata` on `run_agent`; `idempotency_key`,
`metadata`, `timeout_seconds` on `trigger_agent_run`.
## Job status codes
`get_agent_job_status` returns an integer: 0 PENDING, 1 STARTED, 2 RETRY,
3 SUCCESS, 4 FAILURE, 5 CANCELLED, 6 CACHED. Terminal set is {3, 4, 5, 6} —
stop polling there; anything else means keep polling.
`list_agent_jobs` filters an agent's job history by status, metadata, search,
and date range.
## Tables
Flow: `list_tables` → `describe_table` → usually `preview_table` →
`query_tables` → poll `get_table_query_result`.
- `query_tables` accepts exactly ONE read-only ClickHouse statement
(`SELECT` or `WITH ... SELECT`). Mutating SQL, multiple statements,
database-qualified names, system tables, and Roe SQL functions like
`run_agent` are rejected. `limit` defaults to and maxes at 1000.
- It returns `{table_query_id, status, created_at}` — the rows come from
`get_table_query_result`, polled until terminal. Completed results carry
`{columns, rows, row_count, truncated, execution_time_ms}`; `truncated:
true` means a row cap, byte cap, or a shortened oversized cell.
- `upload_table` creates a table from an inline CSV body (small payloads
only). The `upload_chatgpt_*` tools exist for ChatGPT-host file references.
## Auth & errors
- OAuth or API key. API-key mode requires BOTH headers:
`Authorization: Bearer ` and `X-Roe-Organization-Id: ` — a
`401` reading "X-Roe-Organization-Id header required" means the client
config is missing the second header; fix the config, not the prompt.
- `401` with `resource_metadata` in `WWW-Authenticate` → OAuth token invalid
or expired; reconnect through the client's connector/auth UI.
- `503` with `Retry-After` → upstream Roe backpressure (its 429 surfaces as
MCP 503). Back off for the advertised duration and retry — this is NOT an
auth failure.
- Rate limits are token buckets per tool: keyed by user+org for OAuth, by
bearer key for API-key mode. One drained bucket doesn't block other tools.
- Tool errors arrive as a JSON envelope `{code, message, hint, details}` —
parse it; `details` carries the backend's response body.
## Destructive tools — confirm with the user first
`delete_agent`, `delete_agent_version`, `delete_table`, `delete_policy`,
`delete_connection`, `cancel_agent_job`, `cancel_all_agent_jobs`, and
`agents_jobs_delete_data_create` (irreversibly purges job data). Never call
these without explicit confirmation.
## Don'ts
- Don't paste API keys or OAuth tokens into the chat; use placeholders in
config snippets.
- Don't add an `X-Roe-API-Base-URL` header — the MCP host already selects
the right backend (`mcp.roe-ai.com` or `mcp..roe-ai.com`).
- Don't author WorkflowOrchestrator configs from this skill — call
`get_help` with topic `workflows` (older servers fall back to the general
guide) or use the roe-workflow-authoring skill.
When unsure which tool fits, call `get_help(topic=...)`: topics include
overview, getting-started, auth, tools, and troubleshooting.
```
# Workflow Builder
Source: https://docs.roe-ai.com/mcp/skills/workflow-builder
Build complex Roe workflows from Claude Code, Cursor, Codex, and other AI assistants — install one skill and your assistant knows the full authoring contract
Build complex workflows on Roe directly from **Claude Code**, **Cursor**,
**Codex**, or any AI assistant connected to the
[Roe MCP server](/mcp/introduction) — describe the pipeline you want in plain
language and the assistant creates it with the standard agent tools
(`create_agent`, `create_agent_version`).
A workflow chains your existing Roe agents into a pipeline: feed one agent's
output into the next, loop over arrays with parallel iterations, branch on
conditions, merge branches back together, and reshape fields between steps.
It's the same engine behind the visual workflow builder, so anything your
assistant creates opens — and stays editable — on the canvas in the Roe app.
## Install the skill
Workflow authoring has real nuances (reference syntax, loop/branch configs,
validation rules) that aren't discoverable from the API schema alone. This one
skill file teaches your assistant all of them. Copy the block below with its
copy button, then install it for your client:
Save the block to `~/.claude/skills/roe-workflow-authoring/SKILL.md` (or
`.claude/skills/roe-workflow-authoring/SKILL.md` inside a project to scope it
to that repo) and restart Claude Code. It triggers automatically whenever you
work on Roe workflows.
Save the block to `.cursor/rules/roe-workflow-authoring.mdc`, replacing the
`name:`/`description:` frontmatter with Cursor's
[rule frontmatter](https://docs.cursor.com/context/rules):
```markdown theme={null}
---
description: Author or edit Roe workflows (WorkflowOrchestrator agents) — DAGs of agents with loops, if-branches, merges — via the Roe MCP tools or public API.
alwaysApply: false
---
```
Codex reads `AGENTS.md` automatically. Append the block's body (everything
from `# Roe workflow authoring` down) to your project's `AGENTS.md`, or to
`~/.codex/AGENTS.md` to apply it globally.
This page is also served as plain Markdown at
[docs.roe-ai.com/mcp/skills/workflow-builder.md](https://docs.roe-ai.com/mcp/skills/workflow-builder.md)
(and listed in [docs.roe-ai.com/llms.txt](https://docs.roe-ai.com/llms.txt)).
Paste it into a system prompt or project instructions, or have the assistant
fetch the URL before authoring a workflow.
## The skill
````markdown theme={null}
---
name: roe-workflow-authoring
description: Author or edit Roe workflows (WorkflowOrchestrator agents) — DAGs of agents with loops, if-branches, merges — via the Roe MCP tools or public API. TRIGGER when the user wants to create, modify, debug, or review a Roe workflow / multi-step agent pipeline. SKIP for running existing agents or non-Roe orchestration.
---
# Roe workflow authoring
A Roe workflow is an agent with `engine_class_id: "WorkflowOrchestrator"`.
Author it with `create_agent` / `create_agent_version`; wire **existing**
agents as nodes (create/version children first — a node always uses the child
agent's current version's config, resolved at workflow save time; the workflow
cannot override it).
Sequence: `list_agent_engine_types` → `list_agents` +
`get_current_agent_version` (collect `base_agent_id`s and child
`input_definitions`) → `create_agent` → one test run.
## engine_config you submit
```json
{
"nodes": [...],
"output_node_id": "",
"start_connected_nodes": [""]
}
```
Omit `initial_inputs`, top-level `input_definitions`, and `edges` — the
backend derives/handles them. `layout` is optional: include node `{x, y}`
positions when you want to manually arrange the visual builder, or omit it and
the backend will fill missing/invalid node positions. Agent node minimal shape:
`{ "id", "node_type": "agent", "base_agent_id", "input_mapping" }`. Do not
fill `agent_version_id` / `agent_name` / `workflow_type` even though the
schema marks them required — the backend recomputes them from `base_agent_id`.
Reserved node ids: `initial`, `__start__`, `__end__`. Min 2 nodes, ≥1 agent
node.
## Reference syntax (input_mapping values)
- `initial.` — workflow input; `` — full upstream output dict;
`.` — one field (nested ok: `a.b.c`).
- `"{node.field}"` alone preserves the original type; placeholders embedded in
a longer string interpolate (dicts/lists JSON-encoded). Anything else is a
literal string.
- File page slicing: append `|pages=%` to a file reference to pass only
those pages — `"{initial.pdf_files}|pages=1-3%"`. Specs are 1-indexed: `1`,
`1-3`, `1,2,5-7`. Placeholders interpolate first, so loop items work:
`"{initial.pdf_files}|pages={per_chunk.item}%"`. `pages` is the only
supported modifier; a malformed spec fails at runtime, not at save.
- Skipped if-branch nodes resolve to null.
## Workflow inputs
`initial.*` keys come ONLY from the `input_definitions` of agents listed in
`start_connected_nodes` (plus `${var}` templates in their configs). Each input
gets a `__file_name` companion. Referencing an undeclared initial key
fails validation. The workflow's run inputs = the referenced keys.
`${var}` in child configs: auto-mapped to `initial.` on Start-connected
nodes; everywhere else they must be satisfied via explicit `input_mapping` or
the save fails.
## CRITICAL ordering rule
Execution order is derived ONLY from `input_mapping` references (plus implicit
if→branch edges). Utility-node `config` refs do NOT order the graph. Always
mirror them as synthetic entries:
- loop: `"input_mapping": { "__loop_source": "" }`
- if: `"input_mapping": { "__if_cond_0": "", ... }`
- merge inputs: `"__merge_0"`, `"__merge_1"`, ...
## Utility nodes (`node_type`, `config`)
- **loop** — `{ source_field: [, element_alias: "item",
parallel: true, body_node_ids: [...], body_output_node_id: }`. Body nodes read `.` and `.index`.
Downstream, `` is the ARRAY of per-iteration body outputs
(per-element fields only exist inside the body). Non-list source is wrapped
as one element. No nested loops. Body nodes never go in
`start_connected_nodes`.
- **if_condition** — `{ conditions: [{field, operator, value}], combine:
"all"|"any", true_node_ids: [...], false_node_ids: [...] }`. Operators:
equals, not_equals, contains (str/list), greater_than, less_than (float
coercion), is_empty, is_not_empty, is_true, is_false. `value` is a string,
coerced to the field's type. Output is only `{_branch}` — downstream cannot
read data fields off an If; branch nodes read upstream nodes directly.
Skipped branch outputs become null. If BOTH branch lists are non-empty they
must converge on a shared downstream node (use a merge) or the save fails.
- **merge** — `{ mode: "append" | "combine" }`. `append` flattens inputs into
one array; `combine` shallow-merges dicts (later keys win). Nulls are
dropped. Output field is exactly `merged` → reference `.merged`.
- **edit_fields** — `config: {}`; each `input_mapping` key becomes an output
field. Use for renames, literals, `__file_name`, final output shaping.
## Example: branch + merge
Extract → score → branch on risk → merge → result. `extract` is the only
Start-connected node, so the workflow's run inputs are exactly `extract`'s
declared inputs (here `document`).
```json
{
"name": "Document risk review",
"engine_class_id": "WorkflowOrchestrator",
"engine_config": {
"nodes": [
{ "id": "extract", "node_type": "agent",
"base_agent_id": "",
"input_mapping": { "document": "initial.document" } },
{ "id": "score_agent", "node_type": "agent",
"base_agent_id": "",
"input_mapping": { "text": "extract.text" } },
{ "id": "risk_gate", "node_type": "if_condition",
"config": {
"conditions": [
{ "field": "score_agent.risk_score", "operator": "greater_than", "value": "0.8" }
],
"combine": "all",
"true_node_ids": ["deep_review"],
"false_node_ids": ["auto_approve"]
},
"input_mapping": { "__if_cond_0": "score_agent.risk_score" } },
{ "id": "deep_review", "node_type": "agent",
"base_agent_id": "",
"input_mapping": { "text": "extract.text" } },
{ "id": "auto_approve", "node_type": "edit_fields", "config": {},
"input_mapping": { "verdict": "approved", "score": "score_agent.risk_score" } },
{ "id": "merge_results", "node_type": "merge",
"config": { "mode": "append" },
"input_mapping": { "__merge_0": "deep_review", "__merge_1": "auto_approve" } }
],
"output_node_id": "merge_results",
"start_connected_nodes": ["extract"]
}
}
```
## Example: segment → loop → two-pass extract
The canonical big-document pattern, distilled from a production geotech
pipeline that mines 100+-page drilling reports where only some pages hold the
target charts. One agent finds the relevant pages, a parallel loop slices the
PDF per chunk, and a two-pass extractor pulls the data — with a cheap
classifier feeding document-specific hints into the prompts:
```json
{
"nodes": [
{ "id": "cheatsheet", "node_type": "agent",
"base_agent_id": "",
"input_mapping": { "pdf_files": "{initial.pdf_files}|pages=1-3%" } },
{ "id": "split", "node_type": "agent",
"base_agent_id": "",
"input_mapping": { "pdf_files": "initial.pdf_files" } },
{ "id": "per_chunk", "node_type": "loop",
"config": { "source_field": "split.page_ranges",
"element_alias": "item", "parallel": true,
"body_node_ids": ["extract_depths", "extract_all"],
"body_output_node_id": "extract_all" },
"input_mapping": { "__loop_source": "split.page_ranges" } },
{ "id": "extract_depths", "node_type": "agent",
"base_agent_id": "",
"input_mapping": {
"pdf_files": "{initial.pdf_files}|pages={per_chunk.item}%",
"cheatsheet": "cheatsheet" } },
{ "id": "extract_all", "node_type": "agent",
"base_agent_id": "",
"input_mapping": {
"pdf_files": "{initial.pdf_files}|pages={per_chunk.item}%",
"depths": "extract_depths" } },
{ "id": "final", "node_type": "edit_fields", "config": {},
"input_mapping": { "results": "per_chunk",
"file_id": "initial.pdf_files",
"file_name": "initial.pdf_files__file_name" } }
],
"output_node_id": "final",
"start_connected_nodes": ["split", "cheatsheet"]
}
```
Why it is built this way:
- **`split`** is a `PDFPageSelectionEngine` agent. It returns `page_ranges` —
an array of 1-indexed range strings (`["88-90", "91"]`). Prompt it to
segment into the smallest chunks possible, keeping a multi-page chart in
one range.
- **Page slicing bounds every node's context.** Each iteration reads
`{initial.pdf_files}|pages={per_chunk.item}%` — only its own pages. Never
hand the whole document to a per-chunk node.
- **`cheatsheet` runs once, outside the loop.** A cheap-model classifier with
an enum `output_schema` whose members are the hint strings plus `""` for
none-of-the-above, so unknown documents degrade gracefully instead of
hallucinating a hint. The extractors declare a `cheatsheet` input and put
`${cheatsheet}` inside their instructions — upstream output injected
straight into a downstream prompt.
- **Two passes, anchor-then-fill.** `extract_depths` extracts ONLY the
hardest fields with a small focused schema. `extract_all` receives that
whole output (`"depths": "extract_depths"` → `${depths}` in its
instructions), is told to copy those values verbatim, and fills in the
many easy fields around them. Splitting attention this way beats one agent
juggling 40 fields.
- **`final` (edit_fields)** shapes the deliverable: the loop's output array
plus the file-name companion key.
- `start_connected_nodes` lists only the root agents — never the loop or its
body (body nodes may still reference the `initial.*` keys the roots
declared).
## Choosing the right construct
- **No workflow at all** — if one agent with a sharper prompt and
output_schema can do the job, do that. A workflow earns its complexity when
steps need different models, different page slices, fan-out over an array,
or isolation of a hard sub-task.
- **Loop vs batch** — loop when the items come from an upstream node's output
(page ranges, an extracted list). If the caller already holds N independent
inputs, skip the workflow and use `run_agents_batch`.
- **if_condition vs prompt-level conditionality** — use `if_condition` only
to SKIP expensive nodes (gate a deep-review agent behind a score
threshold). Its operators are mechanical, and two-sided branches force a
converging merge. When both paths feed the same downstream node anyway, or
the condition is fuzzy/semantic, prefer a cheap checker agent that emits an
enum or boolean which downstream nodes consume as an ordinary input — no
branch/merge ceremony.
- **Checker → redo chains** — input_mapping is what orders the graph, so to
force "extract → verify → re-extract", give the second extractor a declared
spare input (e.g. `redo`) and map it to the checker's verdict
(`"redo": "checker.sorry"`). To hand a dict to a text-only checker, embed
it in a string: `"text": "Result:\n{extract_depths}"` (interpolation
JSON-encodes).
- **Model tiering** — small model, medium reasoning for gates, checkers, and
classification; big model, high reasoning only for the heavy extraction
nodes. Anything constant across chunks (vendor, language, document type)
belongs BEFORE the loop: loop cost = body cost × N iterations.
- **First page(s) only** — headers, branding, titles, and tables of contents
live up front; slice them: `"{initial.doc}|pages=1%"` or `|pages=1-3%`.
## Validation & testing
Save-time 400s carry `detail` + per-node `node_errors` (in the MCP error
envelope's `details`) and catch: cycles, orphans (every node must reach
`output_node_id`), bad/self references, undeclared `initial.*`, missing
agents/versions, non-converging two-sided ifs, unresolved `${var}` on
non-Start nodes. NOT caught until runtime: cross-node type mismatches,
references to nonexistent output FIELDS (`extract.txet` → null), if-condition
field typos (conditions aren't validated), stale child agents. So always
test-run: `run_agent` (sync, under ~25s) or `trigger_agent_run` → poll
`get_agent_job_status` (terminal: 3 SUCCESS, 4 FAILURE, 5 CANCELLED,
6 CACHED) → `get_agent_job_result`, and inspect before handing off.
Editing an existing workflow: `get_current_agent_version` → modify the full
`engine_config` → `create_agent_version` (configs are immutable snapshots;
always resend the whole graph).
## Visual builder round-trip
Omitting `layout`/`edges` is safe — the canvas reconstructs edges from
`input_mapping` and `*_node_ids`, and the backend derives a fallback `layout`,
arranging nodes left-to-right by dependency depth so they open spaced out
(not piled at the origin). If the agent has meaningful coordinates, it may
include `layout` manually; valid node positions are preserved, and the backend
only fills missing/invalid node positions. The human can still drag and re-save
to refine it; those saved positions are preserved on later edits. (A minor
cosmetic quirk: an if-branch node placed only by data dependency can land one
column left of its gate — harmless, just nudge it.)
````
## Related pages
* [MCP Server setup](/mcp/introduction) — connect a client and authenticate.
* [Introduction to Agents](/agents/introduction) — the child agents workflows
are built from.
* [Agents API](/api-reference/agents/run) — the underlying REST endpoints.
# MCP tools reference
Source: https://docs.roe-ai.com/mcp/tools
All tools exposed by the Roe MCP server, with parameters and behavior annotations.
This page lists the standard Roe MCP tools. Your deployment may expose additional
workflow-specific tools — check the tool list advertised by your MCP client, or
call `get_help`.
## Agents
### `list_agents`
read-only idempotent
List agents in the caller's Roe organization. Use this to discover agents before running one. Use `get_agent` when the agent id is already known. Returns `{results: [...], page, page_size, total, next, previous}` paginated. Defaults to the first page of 20.
| Parameter | Description |
| ----------- | ------------------------------------------------------------ |
| `page` | 1-indexed page number. |
| `page_size` | Results per page (1-100). 20 is a good default for browsing. |
### `create_agent`
Create a new Roe agent. The first version is created implicitly from `engine_class_id` + `engine_config` + `input_definitions`. Use `create_agent_version` to add subsequent versions. Returns the full agent object (id, name, current\_version, etc.).
Navigation for config/model discovery: call `list_agent_engine_types` to find valid production `engine_class_id` values plus the engine-specific config schema/hints. Call `list_supported_models` to see the available model ids before setting `engine_config.model`. For complete working examples, call `list_agents` then `get_current_agent_version` on an agent with the engine class you want and template from its `engine_config` and `input_definitions`. Models and config can be found with those discovery tools, then made here by passing `engine_class_id`, `engine_config`, and `input_definitions`.
Multi-step workflows: to chain agents into a pipeline (engine\_class\_id `WorkflowOrchestrator` — loops, if-branches, merges), call `get_help` with topic `workflows` FIRST; the engine schema alone is not enough to author a correct workflow config.
Cold-start tip: each engine's schema/hints from `list_agent_engine_types` determine which keys `engine_config` needs. Start from that response or template from `get_current_agent_version`; do not invent `engine_class_id`, config keys, or model ids from memory.
| Parameter | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Human-readable agent name. Must be unique within the org. |
| `engine_class_id` | Engine identifier from `list_agent_engine_types`. Do not invent this value; call that tool for current production ids and choose one from the response. |
| `input_definitions` | List of input field specs: `[{key, data_type, description, accepts_multiple_files?}]`. `key` becomes the input parameter name on `run_agent`. `data_type` is a CLOSED MIME-type enum: use `text/plain` for ordinary strings such as URLs, names and free text — `text`, `string` and `file` are all rejected. Valid values: `text/plain`, `text/html`, `text/xml`, `text/csv`, `text/markdown`, `application/json`, `application/pdf`, `image/jpeg`, `image/png`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-m4a`, `video/mp4`, plus the wildcards `text/*`, `image/*`, `audio/*`, `video/*` and `*/*`. Find working examples with `list_agents` + `get_current_agent_version` and adapt that version's `input_definitions`. |
| `engine_config` | Engine-specific config. Required keys vary by `engine_class_id`. Find config shape with `list_agent_engine_types`; find valid model ids with `list_supported_models`; then create the config here in `engine_config`. To make an investigation agent: also set `policy_version_id` (a policy version UUID from `create_policy` / `list_policy_versions`) to run against a policy SOP, and/or `enable_knowledge_base: true` + `knowledge_base_id` (an active knowledge base id from `list_knowledge_bases` / `finalize_knowledge_base`) to investigate against a typology lens. These are standard keys the backend understands across investigation engines. |
| `version_name` | Optional name for the implicitly-created first version. |
| `description` | Optional free-text description shown in the Roe UI. |
### `get_agent`
read-only idempotent
Fetch one agent's full record by id. Use when you already have the agent\_id (e.g. from `list_agents`) and need its config / current version / metadata. Returns the full agent object.
| Parameter | Description |
| ---------- | --------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
### `update_agent`
idempotent
Update an agent's top-level metadata (name, cache flags). To change engine config / inputs, create a new version with `create_agent_version` instead — agent versions are immutable once created. Returns the updated agent object.
| Parameter | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `name` | New agent name. Unset = leave unchanged. |
| `disable_cache` | Controls whether this agent uses cached results for repeated inputs. Set `disable_cache=false` to allow normal cache reuse; set `disable_cache=true` to force every run to execute instead of returning cached results. Unset/null = leave the current setting unchanged. |
| `cache_failed_jobs` | Controls whether failed runs are also cacheable. Set `cache_failed_jobs=false` to avoid reusing failures so retries can execute again; set `cache_failed_jobs=true` to allow the same failed result to be returned from cache for repeated inputs. Unset/null = leave the current setting unchanged. |
### `delete_agent`
destructive idempotent
Permanently delete an agent and all its versions. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. The agent and its run history are removed; in-flight async jobs may continue but their results become unrecoverable. Returns `{agent_id, deleted: true}` on success.
| Parameter | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `confirm` | Must be `true`. Set only after the user explicitly confirms permanent deletion of this agent and all its versions. |
### `duplicate_agent`
Clone an existing agent — copies its config and current version into a new agent owned by the caller's org. Useful for forking a template agent before modifying it. Returns the new duplicated agent object; the top-level `id` is the id to use with `get_agent`, `run_agent`, `update_agent`, and `delete_agent`.
| Parameter | Description |
| ---------- | --------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
### `list_agent_context_sources`
read-only idempotent
List current-version context sources for an agent, with each source's callable read-only operations inlined (name, description, params\_schema, response\_hint). Use the returned `source_index` plus an operation name with `call_context_source_operation`; indexes are not stable IDs. Sources without operations include an `unsupported_reason`.
| Parameter | Description |
| ---------- | --------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents` or `get_agent`. |
### `call_context_source_operation`
read-only
Call one read-only operation on an agent context source. Get `source_index`, operation names, and parameter schemas from `list_agent_context_sources` first. Custom API connections expose their configured GET endpoints as operations; results are JSON capped at 200KB with a `truncated` flag.
| Parameter | Description |
| ---------------- | ----------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents` or `get_agent`. |
| `source_index` | 0-based index from `list_agent_context_sources`; do not guess. |
| `operation_name` | Operation name from `list_agent_context_sources`; omit only if the source pins one. |
| `parameters` | Operation parameters keyed by the listed params\_schema. |
## Agent versions
### `list_agent_versions`
read-only idempotent
List the full version history for one agent. Returns every version, newest first. Use to compare configurations or to find an older config to restore. Returns `{results: [...], total: N}` — the Roe versions endpoint does not paginate, so this returns all versions in a single response. ROLLBACK: MCP cannot promote an existing version to current. To roll back, read the old version's `engine_config` / `input_definitions` (here or via `get_agent_version`) and re-submit them with `create_agent_version`, which makes that config the new current version. Do NOT try to roll back by deleting newer versions with `delete_agent_version` — that destroys history, and the promotion it triggers is by newest-remaining `created_at`, not by your choice.
| Parameter | Description |
| ---------- | --------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
### `create_agent_version`
Create a new version of an existing agent — the version becomes the agent's `current_version` and serves all subsequent runs. Use to iterate on engine\_config or input\_definitions while keeping agent history. Returns the new version object.
Engine class is INHERITED from the parent agent — do NOT pass `engine_class_id`. Versions can swap `engine_config` and `input_definitions` only; to change the engine class itself, create a new agent with `create_agent`.
Navigation for config/model discovery: call `get_current_agent_version` to inspect the current `engine_config` and `input_definitions` you are changing. Call `list_agent_engine_types` to find config-shape hints for the parent engine class. Call `list_supported_models` to see valid model ids before changing `engine_config.model`. Models and config can be found with those tools, then made here by passing new `engine_config` and/or `input_definitions`. For WorkflowOrchestrator agents, call `get_help` with topic `workflows` first for the authoring contract (node shapes, input\_mapping syntax, loop/if/merge configs).
| Parameter | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `input_definitions` | New input field specs `[{key, data_type, description}]`. Unset = inherit from current version. `data_type` is a CLOSED MIME-type enum: use `text/plain` for ordinary strings such as URLs, names and free text — `text`, `string` and `file` are all rejected. Valid values: `text/plain`, `text/html`, `text/xml`, `text/csv`, `text/markdown`, `application/json`, `application/pdf`, `image/jpeg`, `image/png`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-m4a`, `video/mp4`, plus the wildcards `text/*`, `image/*`, `audio/*`, `video/*` and `*/*`. Find the current shape with `get_current_agent_version`; find working examples with `list_agents` + `get_current_agent_version` on similar agents. |
| `engine_config` | New engine-specific config. Shape varies by parent agent's `engine_class_id`. Find the current config with `get_current_agent_version`; find config schema hints with `list_agent_engine_types`; find valid model ids with `list_supported_models`. Unset = inherit from current version. Investigation keys (same as `create_agent`): `policy_version_id` for a policy SOP, and `enable_knowledge_base: true` + `knowledge_base_id` (active knowledge base id) to investigate against a typology lens. |
| `version_name` | Optional name for this version (shown in the UI). |
| `description` | Optional free-text description for this version. |
### `get_agent_version`
read-only idempotent
Fetch one specific version of an agent. Use when comparing versions or inspecting a historical config. `get_supports_eval=true` includes the eval-support flag. Returns the full version object.
| Parameter | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `version_id` | Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`. |
| `get_supports_eval` | Set true only when deciding whether this version can be used with Roe eval features; omit/null otherwise. |
### `update_agent_version`
idempotent
Update mutable metadata on a version (version\_name, description). Sends PATCH, so a field you omit is left unchanged and an explicit `null` clears it. This does not promote the version or change the agent's current/live version; it only edits name/description metadata. Engine config and input definitions are immutable — to change those, use `create_agent_version`. Returns `{agent_id, version_id, updated: true}`.
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `version_id` | Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`. |
| `version_name` | New version name. Omit to leave it unchanged; a blank or `null` value makes the backend auto-assign `version N`. |
| `description` | New free-text description. Omit to leave it unchanged; pass `null` to clear it. |
### `delete_agent_version`
destructive idempotent
Delete one version of an agent. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. Deleting the agent's CURRENT version is allowed and does NOT fail: the backend silently promotes the next-newest remaining version to current, so the agent immediately starts serving a different config — re-check `get_current_agent_version` afterwards. The one refusal is the agent's ONLY version (400); delete the whole agent with `delete_agent` instead. This is NOT a rollback tool — to go back to an older config, re-submit that config with `create_agent_version`. Returns `{agent_id, version_id, deleted: true}` on success.
| Parameter | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `version_id` | Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`. |
| `confirm` | Must be `true`. Set only after the user explicitly confirms permanent deletion of this agent version. |
### `get_current_agent_version`
read-only idempotent
Fetch the agent's current live version. Use this when the active `engine_config` and `input_definitions` are needed before creating a new version or running the agent. Returns the version object.
| Parameter | Description |
| ---------- | --------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
## Connections
### `list_connections`
read-only idempotent
List saved connections in the caller's Roe organization. Use this to discover connection ids before viewing, testing, or deleting a connection. Returns paginated non-secret connection metadata.
| Parameter | Description |
| ---------------- | ---------------------------------------------------------------------- |
| `page` | 1-indexed page number. |
| `page_size` | Results per page (1-100). 20 is a good default for browsing. |
| `connector_type` | Optional connector type id to filter by, such as `custom_api`. |
| `search` | Optional case-insensitive search over connection name and description. |
### `get_connection`
read-only idempotent
Fetch one saved connection by id. Returns non-secret connection metadata, including whether credentials are configured, without returning secret values.
| Parameter | Description |
| --------------- | ---------------------------------------- |
| `connection_id` | Connection UUID from `list_connections`. |
### `delete_connection`
destructive idempotent
Permanently delete one saved connection and its stored credentials. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. Use `list_connections` first to confirm the id and name. Returns `{connection_id, deleted: true}` on success.
| Parameter | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `connection_id` | Connection UUID from `list_connections` or `get_connection`. |
| `confirm` | Must be `true`. Set only after the user explicitly confirms permanent deletion of this connection and its stored credentials. |
### `test_connection`
read-only idempotent
Test an existing saved connection using access already configured in Roe. Use this to verify that Roe can reach the connected external service. The tool does not expose or accept secret values.
| Parameter | Description |
| --------------- | ------------------------------------------------------------ |
| `connection_id` | Connection UUID from `list_connections` or `get_connection`. |
## Discovery
### `list_supported_models`
read-only idempotent
List non-deprecated LLM model ids that can be used in agent `engine_config.model`. Use this before setting or repairing a model value in `create_agent` or `create_agent_version`; do not hardcode stale model names from examples. Returns `{models, total_count, tenant_scope}` where each model includes the canonical id plus capability, provider, context/output token limits, and feature flags such as JSON mode, structured output, vision, audio, tools, and reasoning support when available. Optional `capability` filters the list to image-, audio-, or video-capable models (text-capable models are always included).
| Parameter | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | Optional capability filter. Typical values are `image`, `audio`, or `video`; omit (default) to return every non-deprecated text-capable model. |
### `list_agent_engine_types`
read-only idempotent
List the production agent engine types that can be used as `engine_class_id` when calling `create_agent`. Use this to find available engines and engine-specific config schema before creating or versioning an agent; use `list_supported_models` separately to list valid model ids. Do not guess engine names from examples. Returns `{engine_types, total_count, engines}` where `engine_types` is the compact list of valid ids and `engines` contains the richer live workflow metadata, including input schema, default configuration hints, and categories when the backend exposes them. EXCEPTION: for `WorkflowOrchestrator` (multi-step workflows) the schema is NOT sufficient — utility-node configs and ordering rules are not expressed in it; call `get_help` with topic `workflows` for the authoring contract before constructing that config. Each engine's `input_schema` is slimmed for LLM context budgets: structural fields (type, properties, required, enum, default, items, oneOf/anyOf/allOf, additionalProperties) are preserved verbatim so a valid `engine_config` can be constructed from the response, while docs-only fields (examples, title, $schema, $id) are dropped and long property descriptions are truncated.
*No parameters.*
## Help
### `get_help`
read-only idempotent
Explain how the Roe MCP works end-to-end and how to get started, with a link to the official docs. Call this when a request is ambiguous or you are unsure which tool to use. Returns guidance plus `docs_url`. Pass `topic` to focus on one of: overview, getting-started, auth, tools, workflows, troubleshooting. Call `get_help` with topic `workflows` before building or editing a multi-step workflow (WorkflowOrchestrator) — it returns the full authoring contract plus a docs link. This is a local tool — it makes no backend call and needs no arguments.
**Local tool** — runs inside the MCP server; no backend API call.
| Parameter | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------------- |
| `topic` | Optional help topic: overview \| getting-started \| auth \| tools \| workflows \| troubleshooting. Omit for the full guide. |
## Identity
### `whoami`
read-only idempotent
Return the authenticated Roe user's profile. Use this as a connection check before listing or running agents. Returns `{user_id, org_id, email, source}`.
*No parameters.*
## Knowledge base
### `list_knowledge_bases`
read-only idempotent
List knowledge bases (Atlas typology lenses) in the caller's Roe organization. A knowledge base whose `status` is `active` has a finalized lens and can be wired to an agent via `engine_config.knowledge_base_id`; `drafting` ones are still generating. Use to discover an existing lens before creating a new one. Returns `{results: [...], page, page_size, total, next, previous}` paginated. Defaults to first page of 20. Stop paging when `len(results) < page_size` or `page * page_size >= total`.
| Parameter | Description |
| ----------- | ------------------------------------------------------------ |
| `page` | 1-indexed page number. |
| `page_size` | Results per page (1-100). 20 is a good default for browsing. |
### `create_knowledge_base`
Start a new knowledge base by kicking off async typology-lens generation from a company + brief. Returns immediately with the created knowledge base `id` and a draft status — generation runs in the background.
This is step 1 of 3: (1) `create_knowledge_base`; (2) `poll_knowledge_base_draft` until the draft `status` is `ready`; (3) `finalize_knowledge_base` to commit it into an `active` lens. Only an `active` knowledge base can be wired to an agent.
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `company` | Company the lens is built for (e.g. 'Acme Corp'). |
| `brief` | Free-text brief (>=10 chars) describing the company/product and the kinds of risk the lens should cover. Drives typology generation. |
| `name` | Optional display name. Defaults to the company name. |
| `product_name` | Optional product name to focus the typology selection. |
| `website_url` | Optional company/product website URL for extra context. |
### `get_knowledge_base`
read-only idempotent
Fetch one knowledge base's full record by id, including `status` (`drafting`/`active`/`orphaned`) and a names-only `lens_snapshot` once active. Use when you already have the id (e.g. from `list_knowledge_bases` or `create_knowledge_base`). Returns the full knowledge base object.
| Parameter | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `knowledge_base_id` | Knowledge base UUID from `list_knowledge_bases`, `create_knowledge_base`, or `finalize_knowledge_base`. |
### `poll_knowledge_base_draft`
read-only idempotent
Poll the async draft for a knowledge base. Returns the projected draft with `status` one of `generating`, `ready`, or `error`. Call repeatedly after `create_knowledge_base` until `status` is `ready` (then `finalize_knowledge_base`) or `error`. Read-only — does not advance the lifecycle.
| Parameter | Description |
| ------------------- | --------------------------------------------------------------------------- |
| `knowledge_base_id` | Knowledge base UUID from `create_knowledge_base` or `list_knowledge_bases`. |
### `finalize_knowledge_base`
Commit a `ready` draft into a permanent lens and mark the knowledge base `active`. Only after this can the knowledge base be wired to an agent via `engine_config.knowledge_base_id`. Check the draft is `ready` with `poll_knowledge_base_draft` first. Finalizing enables MCP access so agents can query the lens. The lens remains org-private by default; pass `public: true` only when public access is intended. Returns the finalized knowledge base object (use its `id`).
| Parameter | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledge_base_id` | Knowledge base UUID from `create_knowledge_base` or `list_knowledge_bases`. Its draft must be `ready` (check with `poll_knowledge_base_draft`). |
| `name` | Optional final lens name. Unset = keep the current name. |
| `public` | Whether the finalized lens is publicly accessible (visible beyond this organization). Defaults to false so the lens remains org-private. Set true only when public access is intended. Finalizing always enables MCP access so agents can query the lens. |
## Policies
### `list_policies`
read-only idempotent
List policies in the caller's Roe organization. Use to discover which policies exist before fetching one — do NOT use to fetch a single policy you already have the id for (use `get_policy`). Returns `{results: [...], page, page_size, total, next, previous}` paginated. Defaults to first page of 20. Stop paging when `len(results) < page_size` or `page * page_size >= total` — requesting beyond the last page returns an empty `results` list, not an error.
| Parameter | Description |
| ----------- | ------------------------------------------------------------ |
| `page` | 1-indexed page number. |
| `page_size` | Results per page (1-100). 20 is a good default for browsing. |
### `create_policy`
Create a new Roe policy with an initial version. A policy is the rulebook a policy-driven agent reasons against — every investigation engine (`AMLInvestigationEngine`, `KYCInvestigationEngine`, `FraudInvestigationEngine`, `MerchantRiskEngine`, `ProductPolicyEngine`, `StrategyEngine`) requires one via `engine_config.policy_version_id`. Returns the created policy object, including `current_version_id`, which is the id to put in `engine_config`.
`content` is NOT free-form. It must match the structured schema below. Content that omits `guidelines.categories` is rejected, because an agent built on it fails at run time with `SOP guidelines.categories is required to build plan steps` — the policy also renders as empty in the Roe UI.
Minimal valid content:
\{"guidelines": \{"categories": \[\{"title": "Prohibited products", "description": "What the merchant may not sell.", "rules": \[\{"title": "No nicotine", "description": "Reject if the site sells vapes, e-cigarettes or nicotine pouches.", "flag": "RED\_FLAG"}]}]}, "dispositions": \{"classifications": \[\{"name": "Reject", "description": "Sells a prohibited product."}, \{"name": "Approve", "description": "Nothing prohibited found."}]}, "instructions": "Review the merchant website against the categories below."}
Field reference:
* `guidelines.categories[]` (REQUIRED, at least one): `{title (required, non-empty), description, rules[]}`. Group related rules under one category.
* `categories[].rules[]`: `{title (required, non-empty), description, flag, sub_rules[]}`. `flag` is `RED_FLAG` or `GREEN_FLAG` or omitted. Put the actual decision logic in `description`.
* `rules[].sub_rules[]`: `{title (required), description}`. Optional; only for genuinely nested conditions.
* `dispositions.classifications[]`: `{name (required, non-empty), description, prompt}`. These are the allowed verdicts the agent may return — define them whenever the agent must reach a decision, and name them exactly as the customer says them.
* `instructions`: free text prepended to the agent's reasoning. Scope and tone, not rules.
* `summary_template.template`: optional handlebars-style report template.
* Do NOT invent top-level keys. A flat dict of your own keys (for example `{"verdicts": [...], "prohibited_items": [...]}`) is the legacy shape, is not readable by the Roe UI, and will fail at run time.
* Omit `id` and `content_uuid` everywhere; the backend assigns them.
Copy the shape from a working policy with `list_policies` then `get_policy_version` before authoring one from scratch. Iterate with `create_policy_version`.
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Human-readable policy name. Must be unique within the org. |
| `content` | Structured policy content. Requires `guidelines.categories[]` with at least one category, each `{title, description, rules[]}`. Add `dispositions.classifications[]` for the allowed verdicts. See the tool description for the full schema and a minimal example. A flat dict of arbitrary keys is rejected. |
| `description` | Optional free-text description shown in the Roe UI. |
| `version_name` | Optional name for the implicitly-created first version. |
### `get_policy`
read-only idempotent
Fetch one policy's full record by id. Use when you already have the policy\_id (e.g. from `list_policies`) and need its metadata / `current_version`. To inspect the policy's actual rule content, fetch the version via `get_policy_version` or `list_policy_versions`. Returns the full policy object.
| Parameter | Description |
| ----------- | ------------------------------------------------------------------- |
| `policy_id` | Policy UUID from `list_policies`, `get_policy`, or `create_policy`. |
### `update_policy`
idempotent
Update a policy's top-level metadata (name, description) only. To change policy `content`, create a new version with `create_policy_version`; existing policy versions are immutable. Returns the updated policy object.
| Parameter | Description |
| ------------- | ------------------------------------------------------------------- |
| `policy_id` | Policy UUID from `list_policies`, `get_policy`, or `create_policy`. |
| `name` | New policy name. Unset = leave unchanged. |
| `description` | New description. Unset = leave unchanged. |
### `delete_policy`
destructive idempotent
Permanently delete a policy and all its versions. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. The policy and its version history are removed; any agent currently referencing this policy will see its lookups start failing. Returns `{policy_id, deleted: true}` on success.
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `policy_id` | Policy UUID from `list_policies`, `get_policy`, or `create_policy`. |
| `confirm` | Must be `true`. Set only after the user explicitly confirms permanent deletion of this policy and all its versions. |
### `list_policy_versions`
read-only idempotent
List the version history for one policy, including each version's `content`. Returns `{results, page, page_size, total, next, previous}` paginated. Defaults to first page of 20. Stop paging when `len(results) < page_size` or `page * page_size >= total`. Use to find a previous version to roll back to (via `create_policy_version` with `base_version_id`) or compare versions.
| Parameter | Description |
| ----------- | ------------------------------------------------------------------- |
| `policy_id` | Policy UUID from `list_policies`, `get_policy`, or `create_policy`. |
| `page` | 1-indexed page number. |
| `page_size` | Results per page (1-100). 20 is a good default for browsing. |
### `create_policy_version`
Create a new version of an existing policy — the version becomes the policy's `current_version` and serves all subsequent lookups. Use to iterate on policy `content` while preserving history. Returns the new version object (server re-fetches the full record after POST).
To fork from a non-current version, set `base_version_id` to a version from `list_policy_versions`, `get_policy_version`, or `create_policy_version`. Default is the current version.
`content` follows the same structured schema as `create_policy` — see that tool's description for the full field reference. It requires `guidelines.categories[]` with at least one category; content that omits it is rejected, because agents built on it fail at run time with `SOP guidelines.categories is required to build plan steps`.
Editing an existing policy: read the current content with `get_policy_version`, change the categories, rules or dispositions you need, and send the WHOLE document back. This is a replace, not a merge — anything you leave out is gone from the new version. Agents do not follow the change on their own: an agent pins `engine_config.policy_version_id`, so after creating a version you must also call `create_agent_version` with the new id for the change to take effect.
| Parameter | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `policy_id` | Policy UUID from `list_policies`, `get_policy`, or `create_policy`. |
| `content` | Complete replacement policy content, same structured schema as `create_policy` (requires `guidelines.categories[]`). Read the current version with `get_policy_version` first and send the whole document back — omitted fields are dropped, not merged. |
| `version_name` | Optional name for this version (shown in the UI). |
| `base_version_id` | Policy version UUID from `list_policy_versions`, `get_policy_version`, or `create_policy_version`. Unset = fork from current version. |
### `get_policy_version`
read-only idempotent
Fetch one specific version of a policy, including its full `content`. Use when comparing versions, inspecting a historical config, or templating `content` for a new policy. Returns the full version object.
| Parameter | Description |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `policy_id` | Policy UUID from `list_policies`, `get_policy`, or `create_policy`. |
| `version_id` | Policy version UUID from `list_policy_versions`, `get_policy_version`, or `create_policy_version`. |
## Runs & jobs
### `cancel_all_agent_jobs`
destructive idempotent
Request cancellation of EVERY in-flight async job for one agent. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. Targets all pending/running jobs scheduled against the agent — for selective cancellation, call `cancel_agent_job` per job\_id instead. ASYNCHRONOUS: the Roe API only enqueues the revocation, so NOTHING is cancelled yet when this tool returns. Returns `{agent_id, task_id, targeted_count, note}`; `targeted_count` is how many non-terminal jobs were targeted, and `targeted_count: 0` with `task_id: null` means the agent had nothing running (no work was queued). The cancelled job\_ids are not enumerated — poll `get_agent_jobs_status_batch` to confirm individual jobs settled to `5 CANCELLED`.
| Parameter | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`; cancels its pending/running jobs. |
| `confirm` | Must be `true`. Set only after the user explicitly confirms cancelling every in-flight job for this agent. |
### `list_agent_jobs`
read-only idempotent
Browse the async run (job) history for ONE agent. Use to find past runs, inspect their outcomes, or locate a `job_id` to pass to `get_agent_job_status` / `get_agent_job_result`. Returns `{results: [...], page, page_size, total, next, previous}` paginated. Defaults to first page of 20. For "failed jobs in the last 7 days", set `status_code="4"` and `created_from` to the ISO-8601 timestamp seven days ago. Stop paging when `len(results) < page_size` or `page * page_size >= total` — requesting beyond the last page returns an empty `results` list, not an error.
Filters combine as AND across distinct parameters, with OR WITHIN a single comma-separated parameter. `status_code` accepts job status codes (0 PENDING, 1 STARTED, 2 RETRY, 3 SUCCESS, 4 FAILURE, 5 CANCELLED, 6 CACHED; terminal set \{3,4,5,6}) — use `status_code="4"` for failed jobs, or `status_code="4,5"` for failed OR cancelled jobs. `version_name` accepts comma-separated version names (OR). `metadata` takes `key:value` pairs (`k1:v1,k2:v2` is AND across pairs). `search` substring-matches the job id, display name, or serialized inputs. `created_from` / `created_to` bound `created_at`; pass ISO-8601 datetimes with timezone, e.g. `2024-01-01T00:00:00Z`. `ordering` sorts (prefix `-` for descending); default is `-created_at`. `limit` caps the most-recent jobs considered and counted (default 100000) so `total` stays cheap for agents with very large histories.
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `page` | 1-indexed page number. |
| `page_size` | Results per page (1-100). 20 is a good default for browsing. |
| `status_code` | Filter by job status integer code(s). Use `4` for failed jobs; comma-separated values are OR'd (e.g. `4,5` for FAILURE or CANCELLED). Codes: 0 PENDING, 1 STARTED, 2 RETRY, 3 SUCCESS, 4 FAILURE, 5 CANCELLED, 6 CACHED; terminal set \{3,4,5,6}. |
| `version_name` | Filter by agent version name(s). Comma-separated values are OR'd. |
| `metadata` | Filter by job metadata as `key:value` pairs. Multiple comma-separated pairs (`k1:v1,k2:v2`) are AND'd together. |
| `search` | Case-insensitive substring match across the job id, display name, and serialized job inputs. |
| `created_from` | Only include jobs created at or after this ISO-8601 datetime (inclusive lower bound on `created_at`). Use a timezone, e.g. `2024-01-01T00:00:00Z`. |
| `created_to` | Only include jobs created at or before this ISO-8601 datetime (inclusive upper bound on `created_at`). Use a timezone, e.g. `2024-01-01T00:00:00Z`. |
| `ordering` | Sort field; prefix with `-` for descending. Supported: `created_at`, `last_updated_at`, `status_code`, `cost`, `id`, `agent_version_name`. Default `-created_at` (newest first). |
| `limit` | Cap on the most-recent jobs considered and counted, across all pages. Bounds the reported `total` so listing stays fast for agents with very large job histories. Defaults to 100000 when omitted; raise it to page deeper into history or lower it for an even cheaper count. |
### `download_job_reference`
read-only idempotent
Download a resource referenced by an async job's output (e.g. a small text/JSON artifact emitted by the agent). Returns `{job_id, resource_id, byte_count, encoding: "base64", content_base64}`.
Use this ONLY for small text-like references (≤\~190 KiB raw, \~256 KiB base64). For large binaries — PDFs, images, audio, video — do NOT use this tool: the base64 inflation will trip the MCP response size cap and return a truncation envelope instead. Prefer reading the `trace_url` field from `get_agent_job_result` and showing the user a link they can open in a browser.
Set `as_attachment=true` if you want the backend to include a `Content-Disposition: attachment` hint (does not affect the bytes returned — useful only if a downstream tool consumes the disposition).
| Parameter | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_id` | Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`. |
| `resource_id` | Resource id referenced from the job's output. Find this value in `get_agent_job_result` output/reference fields for the job. |
| `as_attachment` | If true, request `?download=true` so the backend sets a `Content-Disposition: attachment` header on its response. Default false (in-context display). |
### `get_agent_job_result`
read-only idempotent
Fetch the stored result of a terminal async agent job (3 SUCCESS, 4 FAILURE, 5 CANCELLED, or 6 CACHED). Output data is normally present for 3 SUCCESS and 6 CACHED jobs; 4 FAILURE and 5 CANCELLED jobs are terminal but may have no stored output, so this call can return an error envelope — use `get_agent_job_status` to read why a job failed or was cancelled. Returns `{job_id, output, tokens, cost, trace_url, ended_at}`.
| Parameter | Description |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| `job_id` | Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`; must already be terminal. |
### `get_agent_job_artifact`
read-only idempotent
Fetch the result content of a tool-result artifact produced during an agent job. Use this to expand an artifact key found in `get_agent_job_result` output — e.g. an `evidence_data` value like `MerchantRiskEngine-/extraction_<...>.json` — into the underlying extraction/analysis it points to.
| Parameter | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_id` | Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`. |
| `artifact_key` | Artifact key referenced from the job's output (e.g. an `evidence_data` value). Find it in `get_agent_job_result` output/evidence fields for the job. |
### `cancel_agent_job`
destructive idempotent
Cancel one pending/running async agent job. DESTRUCTIVE. On success returns `{job_id, status: "cancelled"}`. Follow with `get_agent_job_status`; settled jobs should reach `5 CANCELLED`. Already-terminal jobs may return a structured error.
| Parameter | Description |
| --------- | -------------------------------------------------------------------------------- |
| `job_id` | Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`. |
### `purge_agent_job_data`
destructive
Irreversibly purge uploaded inputs, workflow artifacts, and stored blob data (outputs, steps, logs, trace) for one job while retaining DB metadata. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation.
| Parameter | Description |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `job_id` | Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`. |
| `confirm` | Must be `true`. Set only after the user explicitly confirms permanent deletion of this job's stored data. |
### `get_agent_job_status`
read-only idempotent
Get the status of an async agent job from `trigger_agent_run` or `run_batch_agent_jobs`. Use to poll until the job reaches a terminal state. Returns `{job_id, status, progress?, started_at, ended_at?}`.
`status` is the raw integer code used by Roe job status:
0 PENDING — queued, not yet picked up
1 STARTED — running
2 RETRY — backend is retrying after a transient failure (not terminal)
3 SUCCESS — complete, call `get_agent_job_result` for the output
4 FAILURE — terminal, `get_agent_job_result` returns the error
5 CANCELLED — terminal, was cancelled via `cancel_agent_job`
6 CACHED — terminal, result served from the agent's run cache
Terminal set: `{3, 4, 5, 6}`. Stop polling on any of those.
| Parameter | Description |
| --------- | -------------------------------------------------------------------------------- |
| `job_id` | Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`. |
### `get_agent_jobs_result_batch`
read-only idempotent
Fetch stored results for many terminal async jobs in one call (each 3 SUCCESS, 4 FAILURE, 5 CANCELLED, or 6 CACHED). Returns `{results: [{job_id, output, tokens, cost, ...}, ...]}` preserving input order. Output data is normally present for 3 SUCCESS and 6 CACHED jobs; 4 FAILURE and 5 CANCELLED jobs may have no stored output, so those entries can come back as error envelopes — read `get_agent_jobs_status_batch` for why.
Each result may contain the full agent output. Keep `len(job_ids) ≤ 25` per call so the combined payload remains within the MCP response limit. Truncation returns a `{truncated: true, ...}` envelope.
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_ids` | Job UUIDs from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`; each must be terminal. Must contain at least one item. Keep ≤25 because results can be large. |
### `get_agent_jobs_status_batch`
read-only idempotent
Fetch the status of many async jobs in a single call. Use this when polling a batch returned by `run_batch_agent_jobs`. Returns `{statuses: [{job_id, status, ...}, ...]}` preserving input order. `status` values are the integer codes documented on `get_agent_job_status` (terminal set: \{3, 4, 5, 6}).
Roe processes up to 1000 ids in server-side chunks. Keep `len(job_ids) ≤ 100` per call so the response remains within the MCP response limit. Responses past the limit return a `{truncated: true, ...}` envelope.
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `job_ids` | Job UUIDs from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`. Must contain at least one item. Keep ≤100 per call. |
### `run_agent`
Run one Roe agent synchronously when completion is expected within about 25 seconds. Use `trigger_agent_run` for longer work. Inputs must match the selected agent version and must not contain secrets or regulated personal data. Returns the completed result in the same call without a job id.
| Parameter | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `inputs` | Map of input `key` to value. Match `get_current_agent_version.input_definitions`, or `get_agent_version.input_definitions` when `version_id` is set. Do not include reserved key `metadata`; pass `{}` if no inputs are required. |
| `version_id` | Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`. Unset = current version. |
### `trigger_agent_run`
Start one asynchronous Roe agent job. Use this for work expected to exceed about 25 seconds or when job tracking is required. Inputs must match the selected agent version and must not contain secrets or regulated personal data. Returns a job id for status and result retrieval.
| Parameter | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `inputs` | Map of input `key` to value. Match `get_current_agent_version.input_definitions`, or `get_agent_version.input_definitions` when `version_id` is set. Do not include reserved keys `idempotency_key`, `metadata`, or `timeout_seconds`; pass `{}` if no inputs are required. |
| `version_id` | Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`. Unset = current version. |
| `idempotency_key` | Optional client-supplied dedupe key. Reuse the same key only to retrieve the same `job_id` instead of starting a new run. |
### `run_batch_agent_jobs`
Start multiple asynchronous jobs for one agent using its current version. Use this when several input maps should be processed as a batch. Inputs must match the current version and must not contain secrets or regulated personal data. Returns job ids for batch status and result retrieval.
| Parameter | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. |
| `batch_inputs` | List of per-run input maps matching `get_current_agent_version.input_definitions`. Must contain at least one item. Do not put per-input metadata here. |
| `timeout_seconds` | Per-job timeout in seconds. The returned JobBatch includes this value. Unset = backend default. |
| `metadata` | Optional free-form metadata attached to the whole batch, not individual input maps. |
## Tables
### `list_tables`
read-only idempotent
List Roe tables in the caller's organization, including each table's column names and ClickHouse column types. Use this before `preview_table` or when discovering table names created by `upload_table`. Returns `{results: [...], total}`.
*No parameters.*
### `delete_table`
destructive idempotent
Permanently delete one Roe table in the caller's organization. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. Drops the underlying table and removes table-link metadata such as project table links and dataset table sync rows.
| Parameter | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `table_name` | Roe table name to permanently delete. Letters, digits, and underscore only; must start with a letter or underscore. |
| `confirm` | Must be `true`. Set only after the user explicitly confirms permanent deletion of this table and its related metadata. |
### `preview_table`
read-only idempotent
Preview one Roe table in the caller's organization. Returns column metadata plus up to `limit` sample rows keyed by column name. Use after `list_tables` to inspect small examples without running an arbitrary SQL query. Defaults to 3 rows, allows at most 50, and accepts `limit: 0` when you only need table and column metadata without reading sample rows.
| Parameter | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `table_name` | Roe table name to preview. Letters, digits, and underscore only; must start with a letter or underscore. |
| `limit` | Maximum number of sample rows to return. Defaults to 3; maximum 50. Use 0 to return only table and column metadata. |
### `describe_table`
read-only idempotent
Describe one Roe table in the caller's organization without reading rows. Returns column metadata, the total row count when ClickHouse can determine it cheaply, and the latest metadata-modification timestamp (`updated_at`) when available. Use after `list_tables` to inspect a table's schema and size before previewing or querying it.
| Parameter | Description |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| `table_name` | Roe table name to describe. Letters, digits, and underscore only; must start with a letter or underscore. |
### `query_tables`
Submit one bounded read-only ClickHouse SQL query over Roe tables in the caller's organization. Use after `list_tables`, `describe_table`, and usually `preview_table`.
SQL format: pass exactly one `SELECT` or `WITH ... SELECT` statement. Do not include multiple statements. Mutating SQL (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, `ALTER`, etc.), database-qualified names, eval tables, system tables, and Roe SQL functions such as `run_agent` are rejected.
Request shape: `{sql, limit?}`. `limit` defaults to 1000 and maxes at 1000. Returns `{table_query_id, status, created_at}`. Then call `get_table_query_result` with `table_query_id`; keep polling that same tool until status is terminal.
| Parameter | Description |
| --------- | -------------------------------------------------------------------------------------------- |
| `sql` | Single read-only ClickHouse SELECT or WITH ... SELECT statement over public Roe table names. |
| `limit` | Maximum returned rows, 1-1000. Defaults to 1000. |
### `get_table_query_result`
read-only idempotent
Poll or fetch a table SQL query result. Use the `table_query_id` returned by `query_tables`.
If the job is still running, returns `{table_query_id, status, error}` with no rows. If complete, returns `{table_query_id, status, columns, rows, row_count, truncated, execution_time_ms}`. Rows are JSON objects keyed by column name. `truncated: true` means the result hit the row limit, backend result byte cap, or an individual huge cell was shortened; oversized cells may be returned as shortened strings even when the original ClickHouse value was a nested object or array.
| Parameter | Description |
| ---------------- | -------------------------------- |
| `table_query_id` | UUID returned by `query_tables`. |
# Policies
Source: https://docs.roe-ai.com/policies/introduction
Define structured rulesets and guidelines for your agents
Policies allow you to create versioned, structured rulesets that agents use for document processing, compliance checking, and classification tasks. Instead of embedding rules directly in agent prompts, policies provide a centralized way to manage guidelines, instructions, and classification dispositions.
## Use Cases
* **Compliance checking**: Define rules and red/green flags for reviewing documents against regulatory requirements
* **Document classification**: Create disposition categories for agents to classify documents into
* **Structured extraction**: Provide hierarchical guidelines that agents follow when extracting information
* **Audit workflows**: Maintain versioned policies for traceability and rollback capabilities
## How Policies Work
1. **Create a policy** at the organization level with a name and description
2. **Add versions** to the policy, each containing structured content (guidelines, instructions, dispositions)
3. **Link the policy** to one or more agents via the agent's engine configuration
4. **Run agent jobs** - agents apply the policy's current version when processing documents
5. **Update policies** by creating new versions without breaking existing agent configurations
## Policy Versioning
Policies use a versioning model similar to agents:
* Each policy has multiple **versions** containing the actual content
* One version is marked as the **current version**
* Agents reference a specific policy version via `policy_version_id`
* Creating a new version automatically sets it as current
* You can switch back to previous versions at any time
```mermaid theme={null}
graph LR
P[Policy] --> V1[Version 1]
P --> V2[Version 2]
P --> V3[Version 3]
P -.->|current| V3
A[Agent] -->|policy_version_id| V3
```
## Policy Content Structure
Each policy version contains structured JSON content with four optional sections:
### Guidelines
A hierarchical structure for organizing rules:
```json theme={null}
{
"guidelines": {
"categories": [
{
"title": "Document Verification",
"description": "Rules for verifying document authenticity",
"rules": [
{
"title": "Check signatures",
"description": "Verify all required signatures are present",
"flag": "RED_FLAG",
"sub_rules": [
{
"title": "Authorized signatories",
"description": "Signatures must match authorized personnel list"
}
]
}
]
}
]
}
}
```
| Field | Description |
| ------------ | --------------------------------------------- |
| `categories` | Top-level groupings of related rules |
| `rules` | Individual rules within a category |
| `sub_rules` | Nested rules for additional detail |
| `flag` | Optional `GREEN_FLAG` or `RED_FLAG` indicator |
### Instructions
Free-form text instructions for the agent:
```json theme={null}
{
"instructions": "Review all documents for compliance with company policy. Flag any discrepancies and provide detailed reasoning for each decision."
}
```
### Dispositions
Classification options for agent outputs:
```json theme={null}
{
"dispositions": {
"classifications": [
{
"name": "Approved",
"description": "Document meets all requirements",
"prompt": "Select this when all compliance checks pass"
},
{
"name": "Rejected",
"description": "Document fails one or more requirements",
"prompt": "Select this when any critical rule is violated"
},
{
"name": "Needs Review",
"description": "Document requires manual review",
"prompt": "Select this for edge cases or unclear situations"
}
]
}
}
```
### Summary Template
A Handlebars-style template for generating structured summaries:
```json theme={null}
{
"summary_template": {
"template": "## Review Summary\n\n**Decision**: {{disposition}}\n\n**Findings**:\n{{#each findings}}\n- {{this}}\n{{/each}}"
}
}
```
## Linking Policies to Agents
Policies are linked to agents through the agent's engine configuration. When creating or updating an agent version, specify the `policy_version_id` to use:
```json theme={null}
{
"engine_config": {
"policy_version_id": "123e4567-e89b-12d3-a456-426614174000"
}
}
```
Policies cannot be deleted while they are in use by any agent. You must first unlink all agents before deleting a policy.
## API Reference
Get all policies in your organization
Create a new policy with initial version
Add a new version to an existing policy
Change which version is active
# Quickstart
Source: https://docs.roe-ai.com/quickstart
Start analyzing your unstructured data in under 5 minutes
Build Agents to process your unstructured data.
Put your Agents to work at scale.
# Release 1.0.84
Source: https://docs.roe-ai.com/release-notes/release-1-0-84
Workflow builder upgrades, new MCP and connector capabilities, stronger audit visibility, and reliability improvements across agents and APIs.
**June 14, 2026**
This release sharpens workflow building, expands MCP and connector support, and improves visibility into workspace activity. It also adds model and security updates while making agent runs and document-heavy workflows more reliable.
## What's new
* Agents Job sidebar filters now support disposition filtering. A Remember toggle can also save filters per agent across reloads.
* Agents Browser Use runs are more resilient. Timeouts, heartbeats, and trace views were improved for long-running browser tasks.
* Agents Large PDF extraction is more reliable. Page selection now runs in smaller windows to stay within execution time limits.
* Agents Research workflows now fail cleanly on invalid structured output. Roe validates and repairs schema mismatches before returning results.
* Agents SQL context sources now include table descriptions in agent instructions. Agents get better context about the data they can query.
* Platform Organization context now lives in the URL path. Org-specific pages are easier to share, bookmark, and navigate.
* Integrations Custom MCP connectors are now supported. Roe can connect to external MCP servers and expose their tools to agents.
* Integrations Custom MCP connections now show a live tools list. You can inspect tool details and filter enabled tools from the connector page.
* Integrations Snowflake connectors now support key pair authentication. Programmatic access token auth remains available.
* Integrations SharePoint triggers are more durable. Roe now handles subscription lifecycle events and supports multiple document libraries per agent on the same connection.
* QA Dataset uploads now deduplicate new files more reliably. Re-uploads and restore flows are handled more safely.
* QA Streamed web document uploads for PDF extraction are more reliable. Large uploads now complete cleanly and failed partial uploads are cleaned up.
* Dashboard Billing now shows a daily usage meter with a live reset countdown. Daily limits are clearer in Settings.
* Dashboard Usage reporting for workflows is more accurate. Workflow costs now roll up correctly without double-counting orchestrator overhead.
* Dashboard Activity Log is live in Settings. Workspace actions across agents, connections, triggers, webhooks, and related resources are now easier to review.
* API Roe MCP OAuth is now enabled for shared staging and production environments. The consent flow also works better for users with many organizations.
* API Roe MCP adds direct ChatGPT file upload tools for CSV and PDF inputs. ChatGPT files can now be uploaded into Roe tables or datasets with durable file references.
* API Roe MCP get\_help now includes a workflows topic. AI clients get the workflow authoring contract directly in the MCP surface.
* API OpenAPI and SDK contracts were tightened across the public API. Generated clients now reflect auth, request shapes, enums, and error responses more accurately.
* API Async agent run APIs now return the correct 404s for missing agents and honor the requested agent version. Rate limit responses also now use 429 only for real throttling.
* Models Claude Fable 5 is now available in Roe. Azure model routing also adds support for the US North Central region.
* Security Security updates shipped across Roe services. Known dependency vulnerabilities in the app and API stack were patched.
* Workflows Workflow Builder now supports nested field selection and If-node pass-through. Complex mappings and conditions are easier to build without workarounds.
* Workflows Workflow Builder nodes now link directly to the underlying agent. Execution traces also link back to agents for faster debugging.
* Workflows Workflow runs are more reliable under load. Orchestrator child jobs now respect concurrency limits and use idempotent job creation to prevent duplicate runs on retries.
# Release 1.0.85
Source: https://docs.roe-ai.com/release-notes/release-1-0-85
Faster job views, stronger public API and MCP coverage, and major upgrades to knowledge base and workflow tooling.
**June 20, 2026**
This release focuses on speed and scale across agent operations, plus broader public API and MCP capabilities. It also adds new knowledge base workflows, better batch exports, and stronger security protections.
## What's new
* Agents Knowledge Base is now a first-class product area with draft, create, and detail views for building and refining lenses.
* Agents Knowledge Base capabilities now plug into AML and fraud workflows through a reusable subagent. Typology investigation is more complete and returns richer evidence summaries.
* Agents Browser Use recordings now open directly on the target site. Session videos skip the watermarked landing page at the start.
* Agents Reference images from web analysis and browser tasks now render reliably in job results. Access is validated from the job itself instead of browser headers.
* Agents Large PDFs now process in parallel page windows. Extraction is faster and more reliable on long documents.
* Agents Agent planning uses fewer back-and-forth calls. Planning-enabled investigations run with less overhead.
* Platform Agent job lists and metrics load faster at high volume. Roe now uses bounded history windows and feed-style pagination to keep large job histories responsive.
* Platform Job details now show who started the run. Creator information appears in job lists, job detail views, and workflow result pages.
* Platform Large integer IDs in workflow inputs now display exactly as entered. Roe preserves full precision for long alert and case identifiers.
* Integrations Exa deep research now uses the current search flow and supports structured output more consistently. Research and answer calls align better with Exa’s latest API.
* Integrations Merchant risk workflows now use the Resellbot API directly for seller revenue data. This removes a browser step and makes the lookup more direct.
* QA Batch export links now open in the correct organization context. Shared CSV and JSON exports land on the right job view.
* QA Self-hosted Browser Use runs now track cost correctly. Execution traces show more accurate per-step and total usage.
* QA PDF cleanup now removes sticky-note comments without stripping stamps or free-text content. Annotated files preserve the content users expect to keep.
* Dashboard Diagnostics reruns now let you choose the agent version explicitly. New diagnostic runs also default to the current version.
* Dashboard Diagnostic report text now renders in monospace where needed. Inline code, quotes, and markdown are easier to read.
* API Agent context sources are now available through the API and Roe MCP. You can list a source’s read-only operations and call them directly.
* API Public API access to job artifacts now supports result-only retrieval. The endpoint returns just the result payload and strips internal metadata and usage details.
* API Custom MCP connectors now support skill sections. You can upload or paste reusable guidance that gets added to agent instructions when that connector is used.
* API The v1 agent cancel-all endpoint now runs asynchronously. Large cancellation requests return quickly and continue in the background.
* API Roe’s public SDK surface is broader and more complete. More allowlisted operations now have first-class client methods across supported SDKs.
* Security Dataset file access is more tightly scoped to the right organization. Download and image retrieval paths now enforce stronger authorization checks.
* Security Sensitive OTP values are no longer written to logs.
* Security Security patches shipped across Roe services and frontend dependencies. This release includes fixes for newly disclosed vulnerabilities.
* Workflows Workflow inputs are available everywhere in the orchestration canvas. The Workflow Inputs card now stays visible while building mappings and conditions.
* Workflows Workflow orchestrations handle large fanouts and loops more efficiently. Roe now batches preparation work and shards large loop bodies to keep big runs stable.
* Workflows Batch runs can now be exported as CSV from the job sidebar. The export includes original batch inputs, status, and agent results for each row.
# Release 1.0.86
Source: https://docs.roe-ai.com/release-notes/release-1-0-86
Policy editing, agent review workflows, pricing controls, and security hardening across Roe.
**June 27, 2026**
This release improves how teams configure, review, and scale agents in Roe. Highlights include the new policy WYSIWYG editor, reviewer comments on agent outputs, configurable pricing rules, and a broad set of security hardening updates.
## What's new
* Agents Agent result pages now support threaded comments, highlights, replies, and resolved notes.
* Agents Agent jobs now support batch-level metadata at run time and after launch.
* Agents Agent job pages now show total job counts, including filtered counts.
* Agents Agent lists and detail pages now load job counts without full-history recounts.
* Agents Stale agent jobs now reconcile against closed workflow states before timing out.
* Agents Merchant Risk agents now expose add-on toggles in agent configuration.
* Agents AML agents now include social scraping during investigations.
* Agents Fraud Investigation agents now support IP, email, phone, and distance enrichment tools.
* Agents Interactive web agents now support custom output schemas and flat per-step billing.
* Platform Agent configuration sliders now drag smoothly and stop resetting while typing.
* SOPs Policy instructions now open in a WYSIWYG editor when the content is supported.
* SOPs Knowledge bases can now be linked to agents by Roe knowledge base ID.
* SOPs Knowledge bases now support unlinking without deleting the underlying Atlas lens.
* SOPs Knowledge base pages now load from the correct routes and return larger lists.
* Dashboard Non-policy agents now use the standard metrics view again.
* API Agent job APIs now return customer-safe cost breakdowns for completed jobs.
* API Agent job comments are now available through backend APIs.
* API Agent pricing now resolves from configurable organization and agent-level rules.
* Security Dataset lists and project APIs now enforce validated organization scope server-side.
* Security Dataset uploads now block active web files and force unsafe previews to download.
* Security Webhook callbacks now block internal and non-public destinations.
* Security SQL editor queries now block cross-database access and database enumeration.
* Security SQL query errors now return sanitized messages instead of raw database details.
* Security SQL query helper requests now enforce stricter per-user and per-organization rate limits.
* Security Ingress TLS policies now disable weak TLS 1.2 CBC cipher suites.
* Workflows Large workflow loops now run in shards of 25 items.
* Workflows Workflow live trace streaming now caps at 250 events with a truncation marker.
* Workflows Workflow scheduler admission now reserves separate capacity for orchestrator parents.
# Release 1.0.87
Source: https://docs.roe-ai.com/release-notes/release-1-0-87
Browser automation, agent management, and new Google Workspace connectors headline this release.
**July 4, 2026**
This release improves browser-based workflows, speeds up agent management views, and expands data access with new Google Docs, Google Sheets, and Roe Tables options. It also tightens workflow field handling and upgrades schedule and trace visibility.
## What's new
* Agents Browser Use now captures HTML and Markdown page artifacts in execution traces.
* Agents Interactive web workflows now support configurable proxy country selection.
* Agents Workflow traces now deep-link directly to the specific child agent job.
* Agents Knowledge base subagent runs now compact long conversations after 25 turns.
* Platform The main navigation now groups agent views with a simpler sidebar layout.
* Platform Agent creation and versioning now consistently hide restricted workflow fields from non-staff users.
* Platform Temporal agent forms now use the visual output schema editor.
* Platform Context source tool and endpoint filters now use a dropdown chip picker.
* Platform JSON schema previews are taller, vertically resizable, and include copy buttons.
* Integrations Google Docs and Google Sheets connectors now target individual files.
* Integrations Roe Tables context sources now support multiple tables in one source.
* Integrations Firecrawl link extraction now uses the supported map request format.
* QA Agent list and job feed queries now return large histories much faster.
* QA Agent version details now display empty, false, and zero config values correctly.
* QA PDF files now render in Roe instead of downloading unexpectedly.
* QA StateStreet model polling now retries transient retrieve failures.
* Dashboard The agents table now loads rows first and fills in job stats asynchronously.
* Dashboard Agent list filters now support server-side filtering across more columns.
* Dashboard Schedules now show linked job status and include a Run now action.
* Security Workflow field redaction now blocks restricted fields in API and MCP requests.
# Release 1.0.88
Source: https://docs.roe-ai.com/release-notes/release-1-0-88
Browser Use upgrades, new Google Workspace tools, Roe MCP updates, and new GPT-5.6 models.
**July 13, 2026**
This release sharpens Roe’s browser and document workflows, expands Google Workspace actions, and improves public API and MCP support. It also adds new GPT-5.6 models and strengthens ID verification tools for fraud workflows.
## What's new
* Agents Browser Use now captures full-page screenshots in execution traces. Configurable per step or final step.
* Agents Browser Use now treats null output schemas as standard text output for public runs.
* Agents Fraud investigation workflows now include face match, barcode extraction, and void detection tools.
* Integrations Google Drive tools now support creating folders inside connected Drive sources.
* Integrations Google Sheets tools now filter rows from projected columns instead of broad range reads.
* SOPs Policy guidelines now render rules without sub-rules instead of failing.
* QA Agent creation now accepts workflows with required runtime inputs and validates them at run time.
* API Agent job listing is now available in the Python, TypeScript, and Go SDKs.
* API Roe MCP now supports OpenAI plugin onboarding with updated OAuth and well-known metadata.
* API MCP file upload tools now use a stricter file reference schema for ChatGPT-compatible uploads.
* Models GPT-5.6 Sol, Terra, and Luna are now available in Roe.
* Models Extraction now defaults to GPT-5.4.
# Release 1.0.89
Source: https://docs.roe-ai.com/release-notes/release-1-0-89
KYC and ID verification upgrades, review mode, and agent workflow improvements.
**July 20, 2026**
This release expands Roe’s identity verification workflows and sharpens review and browser-based investigation experiences. It also adds richer Google Sheets data access and clearer agent management views.
## What's new
* Agents KYC investigations are now available as a dedicated agentic workflow for identity verification.
* Agents ID verification now includes deterministic punched-hole void detection from document images.
* Agents ID verification now reads MRZ data and cross-checks it against barcode and applicant details.
* Agents ID verification now reports selfie face counts and flags extra advisory void markers.
* Agents Merchant Risk investigations now check platform enforcement signals more explicitly.
* Agents Browser Use now returns compact results to parent models while keeping full traces saved.
* Platform Agent lists now sort by Updated On by default and show recent edits first.
* Platform Agent lists now place agents with no job history at the bottom.
* Integrations Google Sheets row filtering now returns smart chip and hyperlink URLs in selected columns.
* QA Browser Use full-page screenshots now fall back to tiled capture on large or slow pages.
* QA Browser traces now hide steps that only contain failed full-page screenshot attempts.
* QA Browser actions override settings are now kept server-controlled and hidden from model inputs.
* QA PDF page selection now runs windows concurrently without duplicating boundary-page extraction.
* Dashboard Workflow reports now render document evidence stored as extracted document artifacts.
* Dashboard Execution traces now show internal cost without customer step billing.
* API SDK run examples now include the skip-cache input for manual runs.
* Workflows Review mode is live on policy-aware agent pages with batch progress, notes, and navigation.
* Workflows Review batches now track reviewed state and support single-agent batch creation.
# Release 1.0.90
Source: https://docs.roe-ai.com/release-notes/release-1-0-90
KYC tooling, workflow inputs, connector runtime configuration, and dashboard updates.
**July 25, 2026**
This release expands KYC and workflow capabilities while improving connector flexibility, review workflows, and reporting. It also adds new model options and security hardening across public job surfaces.
## What's new
* Agents KYC workflows now include MRZ reading, barcode extraction, face matching, and void detection.
* Agents ID verification now handles rotated selfies, large faces, and harder-to-read barcodes more reliably.
* Agents Agents now receive the current date in context for recency and expiry checks.
* Integrations Google Drive now supports XLSX files by converting every worksheet into labeled text.
* Integrations Connectors now support runtime inputs for values supplied at execution time.
* Dashboard Review now opens from a full-width batch table with progress, previews, and deep links.
* Dashboard Execution traces now include a Download JSON action.
* Dashboard Agent metrics now include richer quality signals, p95 duration, and improved batch analysis.
* API SDK release targets now version independently by language.
* Models Gemini 3.6 Flash is now available, and older Gemini Flash tiers now resolve to it.
* Security Public agent job errors now use sanitized customer-safe messages.
* Security Agent status callbacks now require authenticated, validated payloads.
* Workflows Workflow templates now support nested inputs inside agent settings and arrays.
# Release 1.0.91
Source: https://docs.roe-ai.com/release-notes/release-1-0-91
New result dashboards, stronger job error handling, expanded file and document workflows, and updated default models.
**August 1, 2026**
This release improves how Roe handles complex workflows, results, and failures. You’ll see richer workflow outputs, broader document and file support, and safer, more consistent job and MCP behavior.
## What's new
* Agents Seller Risk now supports flexible metric weights with normalized score shares.
* Agents Data Analysis now accepts images, PDFs, CSV, JSON, Markdown, and text files.
* Agents Browser agent outputs now preserve task-level final results alongside page text.
* Agents PDF page selection now uses cached page images and windowed processing for large documents.
* Agents PDF source tracking now keeps heartbeats running during heavy citation matching.
* Agents KYC now adds China national ID checksum validation and visa MRZ checks.
* Agents Face match now uses ArcFace-based recognition with a gender mismatch review signal.
* Agents Knowledge base investigation agents now ship with built-in base skills and richer findings.
* QA Agent tools now include stricter output schema guidance for structured results.
* QA Web, search, scraping, and PDF child workflows now use larger timeout buffers.
* QA Bright Data Reddit and social scraping now wait longer for status polling.
* Dashboard Workflow results now support dashboard-style output blocks and a dedicated dashboard tab.
* Dashboard Risk results now use a shared score ruler and clearer score composition.
* Dashboard Connector tables now remember filters, search, page size, and sorting per organization.
* API Trace responses now use a shared typed contract with payload status metadata.
* Models Claude Opus 5 and Claude Sonnet 5 are now available in Roe.
* Models GPT-5.6 Sol is now the default model for agents.
* Models Job name generation now preserves non-Latin characters and uses GPT-5.4 Mini.
* Security Job failures now show one consistent customer-safe error while private diagnostics stay hidden.
* Security Destructive MCP tools now require explicit confirmation before deletion runs.
* Security MCP responses now redact stored connector credentials and default finalized knowledge bases to private.
* Workflows Reruns now work for completed jobs that were created without per-job inputs.
# Release 1.0.92
Source: https://docs.roe-ai.com/release-notes/release-1-0-92
Skills versioning, approval gates, new workflow tools, and reliability improvements across Roe.
**August 8, 2026**
This release expands how teams build, customize, and monitor agents in Roe. Highlights include a new versioned skills library, approval gates in workflows, richer trace exports, and stronger reliability for PDF, browser, and job execution flows.
## What's new
* Agents Knowledge base agents now use versioned skill sets, structured measurements, and follow-up prompts.
* Agents Roe Tables sources now expose deterministic read, lookup, and search tools.
* Agents Web Insights now supports direct Amazon product URLs.
* Agents Merchant Risk and Seller Risk agents now support TikTok Shop scraping.
* Agents Google Drive tools now support uploading Roe files into Drive folders.
* Agents Job display names now use final workflow output for better subject naming.
* Agents AML, Fraud, and KYC prompts now use shared prompt blocks.
* Agents Browser artifact analysis now runs through a dedicated extraction path.
* SOPs Skills library now supports version history, rollback, downloads, and agent selection.
* SOPs Skill generation drafts create new skill versions from prompts and attachments.
* QA PDF source tracking now stays responsive during heavy citation matching and OCR.
* QA Agent job failures and cancellations now show one consistent error state across views.
* QA Connection lists now paginate deterministically, and browser result context is bounded.
* QA Roe agents API now avoids a job-startup failure path in its event loop.
* Dashboard Agents list now uses a portfolio view with search, filters, sorting, and pagination.
* Dashboard Execution traces now include an Export to Phoenix action for completed jobs.
* API Completed agent jobs now support trace export to Phoenix by API.
* Security Google Drive and Sheets runtime input overrides now require signed requests.
* Security High-severity dependency fixes shipped across backend, agents, MCP, and frontend.
* Workflows Approval Gate nodes are now available in the workflow builder.
* Workflows Approval Gates now act as unconditional pass-through checkpoints with trigger selection.
* Workflows Workflow editors now surface unused agent input mappings and let you remove them.
# Release 1.0.93
Source: https://docs.roe-ai.com/release-notes/release-1-0-93
Agent management, investigation workflows, and data tooling updates across Roe.
**August 15, 2026**
This release sharpens how teams manage agents, inspect investigations, and work with evidence inside Roe. It also expands workflow capabilities for livestream monitoring, skills, and document verification.
## What's new
* Agents Investigation Maps reconstruct completed AML and fraud investigations as interactive graphs.
* Agents Investigation Maps now show every grouped query with paging, selection, and reruns.
* Agents Execution traces now capture richer tool results, errors, and source attribution.
* Agents SQL query trace summaries now show the model-written query purpose.
* Agents Workflow screenshots and extracted images now load directly into agent context.
* Agents Web extraction now imports public images into workflow-scoped references before visual loading.
* Agents Livestream Monitoring now captures evidence across TikTok and browser-based livestream pages.
* Agents Livestream Monitoring now plans by policy category and researches source pages after capture.
* Platform Agents now use a portfolio view with URL-backed search, filters, sorting, and pagination.
* Platform Context sources now link directly to connector details or the exact Roe Table.
* Integrations Snowflake connectors now validate one read-only SQL statement and preview results inline. Up to 1,000 rows.
* SOPs Policy editor @ mentions now open at the caret with hover-intent tooltips.
* SOPs Policy summaries and workflow summaries now support collapsible Markdown sections.
* SOPs Product Policy now uses shared prompt blocks and aligned tool names.
* QA KYC MRZ checks now separate format warnings from true check-digit failures.
* QA National ID checksum validation now covers India, Brazil, Ecuador, Mexico, and Spain.
* QA PDF citations now preserve original page numbers for sparse page selections.
* Dashboard Skills review now walks files one at a time and records the exact version used.
* Dashboard Skill generation now reads policy dispositions, web research, and profiled CSV tables.
* API Job webhooks now send raw status names like SUCCESS, FAILURE, and CACHED.
* Security Security updates patched frontend and backend dependency advisories.
* Workflows Approval gates now simply wait for approval instead of using trigger types.
* Workflows Manual approval gates now create durable gate instances and keep gated branches closed.
# Release 1.0.94
Source: https://docs.roe-ai.com/release-notes/release-1-0-94
Workflow versioning, richer connectors, new models, and reliability improvements across Roe.
**August 26, 2026**
Release 1.0.94 sharpens workflow editing, expands connector flexibility, and adds new agent capabilities. It also improves reliability in tracing, extraction, scheduling, and model failover.
## What's new
* Agents Agent schedules now support five-field cron expressions.
* Agents Memory profiles now work across agentic workflows and workflow feedback.
* Agents TikTok live search now finds sellers by keyword or product category.
* Agents Federal court record search now surfaces PACER party matches in Roe agents.
* Agents Browser Use context sources now return validated structured output.
* Agents Self-hosted browser login now follows multi-step sign-in flows across sibling domains.
* Agents Meta agent now guides onboarding with skill-based agent building and async job updates.
* Integrations Custom API connectors now support structured JSON request bodies and no-auth connections.
* Integrations Custom API connectors now sign requests with configurable HMAC authentication.
* Integrations Custom API connectors now send JSON object and array strings as structured bodies.
* Integrations Intercom channels now support selectable tools, including tool-free silent channels.
* Integrations Fillout webhooks now accept native file objects and boolean answers.
* QA PDF citations now open the correct original page after sparse page extraction.
* QA Artifact citations now use shorter keys and drop evidence that resolves to nothing.
* QA Investigation maps now recover tool arguments and results from current trace fields.
* QA Phone carrier checks now distinguish possible numbers, offline validity, and provider lookups.
* QA Phone results now hide provider account-state messages from agent outputs.
* QA Azure model routing now retries healthier regions and falls back to OpenAI when needed.
* QA Workflow and agent traces now avoid serialization failures and duplicate sanitization work.
* Dashboard Agent, connection, and policy pickers now search past the first 100 results.
* Dashboard Review pages now show inline @file attachments as one file, not fragments.
* Dashboard Support event logs now group activity by run and include context-source calls.
* API Webhooks now support custom headers and manual resend for completed jobs.
* Models Gemini 3.7 Flash is now available and replaces deprecated Gemini 3.6 Flash.
* Models Qwen3.8 27B and Gemma 4 31B are now available as hosted models.
* Models Web search ranking now defaults to GPT-5.6 Luna.
* Security Backend SQL parsing now uses a patched dependency version for recent security fixes.
* Workflows Workflow canvas now lets you open, compare, and restore historical versions.
* Workflows Workflow canvas now autosaves layout changes without creating new workflow versions.
* Workflows Workflow saves now skip version bumps for layout-only edits.
* Workflows Workflow saves now show child-agent version changes before creating a new version.
* Workflows Approval gates now resume the held workflow branch when a reviewer submits.
* Workflows Multi-agent workflow steps now accept the same file-list inputs as single-agent runs.
* Workflows Workflow step inputs now preserve quoted text and inline file tags exactly.
# Release 1.0.95
Source: https://docs.roe-ai.com/release-notes/release-1-0-95
New browser connectors, approval workflows, fraud monitoring, and model controls across Roe.
**August 29, 2026**
This release expands agent capabilities across browser automation, livestream monitoring, and fraud analysis. It also adds in-product approval flows, tighter MCP and callback security, and more precise model controls.
## What's new
* Agents Fraud Investigation agents now support event-driven fraud pattern monitoring with advisory pattern search.
* Agents Livestream Monitoring now supports Whatnot as a source, including offline seller review.
* Agents Browser tools now return images directly in tool output for multimodal workflows.
* Integrations Shield is now available as a self-hosted browser connector with connector-owned tools.
* Integrations Self-hosted browser connectors now support connector-scoped tool selection.
* QA Thinking controls now stay scoped to supported providers instead of reaching unsupported models.
* QA Self-hosted browser allowlists now correctly handle sibling domains, private suffixes, and IP addresses.
* QA Output schema validation no longer loops on rerender in the agent builder.
* API Webhook resend now treats webhook ID as optional in the Go SDK.
* API Public MCP tool names now use run\_batch\_agent\_jobs and purge\_agent\_job\_data.
* API Public MCP now excludes credential entry, connector schema, and raw file upload tools.
* Models Qwen thinking is now a per-request SageMaker option and defaults off.
* Security Grader score callbacks now require internal service authentication when configured.
* Workflows Completed runs now include an Approvals tab for reviewing and submitting manual gates.
# Release 1.0.97
Source: https://docs.roe-ai.com/release-notes/release-1-0-97
Metabase and Google Sheets expand agent access, interactive web browsing upgrades, and connector security hardens.
**September 12, 2026**
This release expands what Roe agents can read and browse while tightening connector security. It also adds new model options and improves a few high-friction workflow and UI behaviors.
## What's new
* Agents Livestream monitoring now shows auction lots as a third synchronized timeline lane.
* Platform Hover-expanded sidebar stays open while footer menus are in use.
* Integrations Metabase connectors let agents run scoped read-only SQL and use saved cards as tools.
* Integrations Google Sheets tools let agents inspect tabs and run bounded row queries.
* QA Metabase table scoping now preserves schema boundaries for queries and saved cards.
* QA Password-protected PDFs now show a locked state instead of a looping browser prompt.
* API OpenAPI schema generation now produces Go-compatible SDKs for nullable enums.
* Models Claude Fable 5.1 is now available in Roe.
* Security Connector URL validation now blocks unsafe destinations and credentialed cross-host redirects.
* Workflows Abandoned support sessions now close without charging unresolved investigations.
# Introduction
Source: https://docs.roe-ai.com/sql-reference/introduction
Manage your unstructured data in Roe with SQL
Please refer to [clickhouse SQL documentation](https://clickhouse.com/docs).
# Introduction
Source: https://docs.roe-ai.com/use-cases/finance
Coming soon
# Webhooks
Source: https://docs.roe-ai.com/webhooks/introduction
Receive real-time notifications when agent jobs complete
Webhooks allow you to receive HTTP notifications when your agent jobs complete. Instead of polling for job status, configure a webhook URL and Roe will automatically send the job results to your endpoint.
## Use Cases
* **Real-time data pipelines**: Trigger downstream processing as soon as agent jobs finish
* **Notifications**: Send alerts to Slack, email, or other services when jobs complete
* **Database updates**: Automatically store extracted data in your systems
* **Workflow automation**: Chain agent outputs into other processes
## How Webhooks Work
1. **Create a webhook** at the organization level with a name and destination URL
2. **Link the webhook** to one or more agents
3. **Run agent jobs** as usual via the UI, API, or SQL workspace
4. **Receive payloads** at your URL when jobs complete (success or failure)
## Creating Webhooks
You can create webhooks via the [API](/api-reference/webhooks/create-webhook) or the Roe UI.
A webhook requires:
* **Name**: The name to reference
* **URL**: The endpoint that will receive POST requests
## Linking Webhooks to Agents
After creating a webhook, link it to one or more agents. When any linked agent completes a job, the webhook will fire.
You can link agents via the [API](/api-reference/webhooks/link-agents) or the dashboard.
### Testing Webhooks
Before going live, you can test that your webhook endpoint is correctly configured. Send a test payload to verify your endpoint receives and processes the webhook correctly.
To test a webhook linked to an agent, use the test endpoint:
```bash theme={null}
POST /v1/agents/{agent_id}/webhooks/{webhook_id}/test/
```
This sends a sample payload to your webhook URL so you can verify connectivity and response handling without running an actual agent job.
## Webhook Payload
When an agent job completes, Roe sends a POST request to your webhook URL with a JSON payload.
### Payload Fields
| Field | Description |
| -------------------- | ----------------------------------------------------------------------------------- |
| `timestamp` | ISO 8601 timestamp when the webhook was sent |
| `agent.id` | UUID of the base agent |
| `agent.name` | Name of the agent |
| `agent_version.id` | UUID of the specific agent version that ran |
| `agent_version.name` | Version name (e.g., "v1") |
| `job.id` | UUID of the completed job |
| `job.status` | Either `"succeeded"` or `"failed"` |
| `job.status_code` | Numeric status code |
| `job.cost` | Cost of the job in USD |
| `job.created_at` | When the job was created |
| `job.completed_at` | When the job finished |
| `job.output` | The extracted data from the agent (structure depends on your agent's output schema) |
| `job.metadata` | Any metadata attached to the job |
| `organization.id` | UUID of the organization |
| `organization.name` | Name of the organization |
## Deleting Webhooks
Webhooks are protected from accidental deletion. If a webhook is still linked to one or more agents, the delete operation will fail with a `400 Bad Request` error.
To delete a webhook:
1. First, unlink all agents from the webhook using the [Unlink Agent](/api-reference/webhooks/unlink-agent) endpoint
2. Then delete the webhook using the [Delete Webhook](/api-reference/webhooks/delete-webhook) endpoint
## API Reference
Get all webhooks in your organization
Create a new webhook
Connect agents to a webhook
Remove a webhook
]