Vienna SDK API Reference
#The Vienna OS SDK provides a TypeScript/JavaScript client for integrating with the Vienna governance platform. This reference documents all available methods, parameters, and return types.
https://console.regulator.aiAPI Version:
v1Authentication: API key via Bearer token or session cookie
# Install the SDK
npm install @vienna/sdk
# Or via yarn
yarn add @vienna/sdkimport { ViennaClient } from '@vienna/sdk';
const vienna = new ViennaClient({
apiKey: 'vna_your_api_key_here',
baseUrl: 'https://console.regulator.ai', // optional
});
// Submit an intent
const result = await vienna.intent.submit({
action: 'wire_transfer',
source: 'billing-bot',
payload: { amount: 75000, currency: 'USD' },
});
console.log('Intent status:', result.status);Authentication
#The Vienna SDK uses API keys for authentication. You can obtain an API key from the Vienna Console or via the authentication endpoint.
const vienna = new ViennaClient({
apiKey: process.env.VIENNA_API_KEY,
});ViennaClient
#The main client class that provides access to all Vienna OS modules. Initialize once and reuse across your application.
constructor
#new ViennaClient(config: ViennaConfig)Creates a new Vienna client instance with the provided configuration.
Parameters
config—ViennaConfigConfiguration object containing API key and optional settings
Returns
ViennaClientExample
import { ViennaClient } from '@vienna/sdk';
const vienna = new ViennaClient({
apiKey: 'vna_your_api_key',
baseUrl: 'https://console.regulator.ai', // optional
timeout: 30000, // optional, default 30s
retries: 3, // optional, default 3
onError: (error) => console.error('Vienna error:', error), // optional
});ViennaConfig
#interface ViennaConfigConfiguration interface for the Vienna client.
Parameters
apiKey—stringAPI key for authentication (starts with 'vna_')
baseUrl—string(optional)Base URL of the Vienna OS API
timeout—number(optional)Request timeout in milliseconds
retries—number(optional)Number of automatic retries on 429/5xx errors
onError—(error: Error) => void(optional)Global error handler invoked on every request failure
Returns
ViennaConfigExample
const config: ViennaConfig = {
apiKey: process.env.VIENNA_API_KEY!,
baseUrl: 'https://console.regulator.ai',
timeout: 60000, // 1 minute
retries: 5,
onError: (error) => {
console.error('[Vienna SDK Error]', error.message);
// Send to error tracking service
errorTracker.captureException(error);
},
};Intent Module
#The Intent module handles agent action submissions, status tracking, and simulation. This is the primary interface for governing agent behavior.
submit
#vienna.intent.submit(intent: IntentRequest, options?: RequestOptions): Promise<IntentResult>Submit an agent intent for governance evaluation and execution. The action flows through policy evaluation, risk assessment, approval (if required), and execution.
Parameters
intent—IntentRequestThe intent request describing the action to perform
options—RequestOptions(optional)Optional request configuration (timeout, abort signal)
Returns
Promise<IntentResult>Example
// Submit a wire transfer intent
const result = await vienna.intent.submit({
action: 'wire_transfer',
source: 'billing-bot',
tenantId: 'acme-corp',
payload: {
amount: 75000,
currency: 'USD',
recipient: 'vendor-123',
reason: 'Monthly vendor payment',
},
metadata: {
requestId: 'req-abc123',
context: 'scheduled_payment',
},
});
// Handle the result based on status
switch (result.status) {
case 'executed':
console.log('Payment processed:', result.executionId);
break;
case 'pending_approval':
console.log('Awaiting approval:', result.approvalId);
// Set up webhook or polling to wait for approval
break;
case 'denied':
console.log('Payment denied:', result.reason);
break;
}status
#vienna.intent.status(intentId: string, options?: RequestOptions): Promise<IntentStatusResponse>Check the current status of a previously submitted intent. Returns the full intent lifecycle including policy matches, approvals, and execution results.
Parameters
intentId—stringThe intent identifier (e.g., 'int-abc123')
options—RequestOptions(optional)Optional request configuration
Returns
Promise<IntentStatusResponse>Example
// Check intent status
const status = await vienna.intent.status('int-abc123');
console.log('Status:', status.status);
console.log('Risk tier:', status.riskTier);
console.log('Policy matches:', status.policyMatches);
if (status.status === 'executed') {
console.log('Execution ID:', status.executionId);
console.log('Warrant ID:', status.warrantId);
}simulate
#vienna.intent.simulate(intent: IntentRequest, options?: RequestOptions): Promise<IntentSimulationResult>Simulate an intent without executing it (dry-run). Useful for testing policy configurations and understanding governance outcomes before actual submission.
Parameters
intent—IntentRequestThe intent to simulate
options—RequestOptions(optional)Optional request configuration
Returns
Promise<IntentSimulationResult>Example
// Simulate a high-value transfer to test policies
const simulation = await vienna.intent.simulate({
action: 'wire_transfer',
source: 'billing-bot',
payload: {
amount: 500000, // Half a million
currency: 'USD',
recipient: 'external-vendor',
},
});
console.log('Would execute?', simulation.wouldExecute);
console.log('Final status:', simulation.status);
console.log('Risk tier:', simulation.riskTier);
console.log('Required approvals:', simulation.requiredApprovals);
console.log('Policy matches:', simulation.policyMatches);list
#vienna.intent.list(params?: { status?: string; source?: string; limit?: number }): Promise<IntentStatusResponse[]>List recent intents with optional filtering by status or source agent.
Parameters
params—object(optional)Optional filter parameters
Returns
Promise<IntentStatusResponse[]>Example
// List all pending intents
const pendingIntents = await vienna.intent.list({
status: 'pending_approval',
limit: 20
});
// List intents from specific agent
const agentIntents = await vienna.intent.list({
source: 'billing-bot'
});Policies Module
#The Policies module manages governance rules that evaluate agent intents. Policies determine risk tiers, approval requirements, and execution constraints.
create
#vienna.policies.create(params: PolicyCreateParams, options?: RequestOptions): Promise<PolicyRule>Create a new governance policy rule. The policy will be evaluated against all future intents according to its priority.
Parameters
params—PolicyCreateParamsPolicy configuration including name, conditions, and actions
options—RequestOptions(optional)Optional request configuration
Returns
Promise<PolicyRule>Example
// Create a policy for high-value transaction approval
const policy = await vienna.policies.create({
name: 'High-Value Transaction Gate',
description: 'Require T2 approval for transfers over $50,000',
priority: 100,
enabled: true,
conditions: [
{
field: 'action',
operator: 'equals',
value: 'wire_transfer',
},
{
field: 'payload.amount',
operator: 'gt',
value: 50000,
},
],
actionOnMatch: 'require_approval',
approvalTier: 'T2',
tags: ['financial', 'high-risk'],
});
console.log('Created policy:', policy.id);update
#vienna.policies.update(policyId: string, params: PolicyUpdateParams, options?: RequestOptions): Promise<PolicyRule>Update an existing policy rule. Changes take effect immediately for new intent evaluations.
Parameters
policyId—stringThe policy identifier to update
params—PolicyUpdateParamsFields to update (partial)
options—RequestOptions(optional)Optional request configuration
Returns
Promise<PolicyRule>Example
// Update policy priority and enable it
const updated = await vienna.policies.update('pol-123', {
priority: 150,
enabled: true,
description: 'Updated: Require approval for high-value transfers',
});
// Disable a policy temporarily
await vienna.policies.update('pol-456', {
enabled: false,
});delete
#vienna.policies.delete(policyId: string, options?: RequestOptions): Promise<void>Delete a policy rule. The policy is soft-deleted (retained in audit trail) but immediately removed from the evaluation set.
Parameters
policyId—stringThe policy identifier to delete
options—RequestOptions(optional)Optional request configuration
Returns
Promise<void>Example
// Delete a policy
await vienna.policies.delete('pol-123');
console.log('Policy deleted');list
#vienna.policies.list(params?: PolicyListParams, options?: RequestOptions): Promise<PolicyRule[]>List all policies with optional filtering by status, tenant, or tags.
Parameters
params—PolicyListParams(optional)Optional filter parameters
options—RequestOptions(optional)Optional request configuration
Returns
Promise<PolicyRule[]>Example
// List all active policies
const activePolicies = await vienna.policies.list({
enabled: true,
});
// List policies for specific tenant
const tenantPolicies = await vienna.policies.list({
tenantId: 'acme-corp',
});
// List policies by tag
const financialPolicies = await vienna.policies.list({
tag: 'financial',
});evaluate
#vienna.policies.evaluate(payload: Record<string, unknown>, options?: RequestOptions): Promise<PolicyEvaluation>Evaluate policies against a test payload (dry-run). Returns which policies would match and what action would be taken without executing anything.
Parameters
payload—Record<string, unknown>Test payload to evaluate against policies
options—RequestOptions(optional)Optional request configuration
Returns
Promise<PolicyEvaluation>Example
// Test a policy evaluation
const evaluation = await vienna.policies.evaluate({
action: 'wire_transfer',
payload: {
amount: 100000,
currency: 'USD',
recipient: 'external-vendor',
},
source: 'billing-bot',
tenantId: 'acme-corp',
});
console.log('Matched policies:', evaluation.matchedPolicies);
console.log('Final action:', evaluation.finalAction);
console.log('Risk tier:', evaluation.riskTier);
console.log('Details:', evaluation.details);templates
#vienna.policies.templates(options?: RequestOptions): Promise<PolicyTemplate[]>List available industry policy templates that can be imported as starting points for common compliance requirements.
Parameters
options—RequestOptions(optional)Optional request configuration
Returns
Promise<PolicyTemplate[]>Example
// Get available policy templates
const templates = await vienna.policies.templates();
templates.forEach(template => {
console.log(`Template: ${template.name}`);
console.log(`Industry: ${template.industry}`);
console.log(`Description: ${template.description}`);
});
// Example templates:
// - Financial Services (SOX compliance)
// - Healthcare (HIPAA compliance)
// - DevOps (deployment gates)
// - Legal (filing controls)Fleet Module
#The Fleet module manages agents, their trust scores, activity monitoring, and alerts. Use this to register new agents, track performance, and respond to issues.
register
#vienna.fleet.register(params: { name: string; type?: string; capabilities?: string[] }): Promise<FleetAgent>Register a new agent with the fleet. This creates an identity and initial trust profile for the agent.
Parameters
params—objectAgent registration parameters
Returns
Promise<FleetAgent>Example
// Register a new agent
const agent = await vienna.fleet.register({
name: 'customer-support-bot',
type: 'autonomous',
capabilities: ['send_email', 'query_database', 'create_ticket'],
metadata: {
framework: 'langchain',
version: '1.0.0',
owner: 'support-team',
},
});
console.log('Agent registered:', agent.id);
console.log('Initial trust score:', agent.trustScore);get
#vienna.fleet.get(agentId: string, options?: RequestOptions): Promise<FleetAgent>Get detailed information about a specific agent including trust history, capabilities, and current status.
Parameters
agentId—stringThe agent identifier
options—RequestOptions(optional)Optional request configuration
Returns
Promise<FleetAgent>Example
// Get agent details
const agent = await vienna.fleet.get('agt-abc123');
console.log('Agent name:', agent.name);
console.log('Status:', agent.status);
console.log('Trust score:', agent.trustScore);
console.log('Risk tier:', agent.riskTier);
console.log('Total intents:', agent.totalIntents);
console.log('Denied intents:', agent.deniedIntents);
console.log('Last activity:', agent.lastActivityAt);update
#vienna.fleet.update(agentId: string, params: Partial<FleetAgent>): Promise<FleetAgent>Update agent configuration such as capabilities, metadata, or operational status.
Parameters
agentId—stringThe agent identifier to update
params—Partial<FleetAgent>Fields to update
Returns
Promise<FleetAgent>Example
// Update agent capabilities
const updated = await vienna.fleet.update('agt-abc123', {
description: 'Enhanced support bot with new capabilities',
capabilities: ['send_email', 'query_database', 'create_ticket', 'escalate_to_human'],
tags: ['support', 'production', 'enhanced'],
});
// Suspend an agent
await vienna.fleet.update('agt-abc123', {
status: 'suspended',
});metrics
#vienna.fleet.metrics(agentId: string, options?: RequestOptions): Promise<AgentMetrics>Get performance metrics for a specific agent including intent success rates, response times, and trust score evolution.
Parameters
agentId—stringThe agent identifier
options—RequestOptions(optional)Optional request configuration
Returns
Promise<AgentMetrics>Example
// Get agent metrics
const metrics = await vienna.fleet.metrics('agt-abc123');
console.log('Total intents:', metrics.totalIntents);
console.log('Approved intents:', metrics.approvedIntents);
console.log('Denied intents:', metrics.deniedIntents);
console.log('Pending intents:', metrics.pendingIntents);
console.log('Average response time:', metrics.avgResponseTimeMs, 'ms');
console.log('Current trust score:', metrics.trustScore);
console.log('Risk tier:', metrics.riskTier);
console.log('Period:', metrics.periodStart, 'to', metrics.periodEnd);activity
#vienna.fleet.activity(agentId: string, pagination?: PaginationParams, options?: RequestOptions): Promise<PaginatedList<AgentActivity>>Get paginated activity log for an agent showing recent intents, executions, and governance events.
Parameters
agentId—stringThe agent identifier
pagination—PaginationParams(optional)Pagination parameters (limit, offset)
options—RequestOptions(optional)Optional request configuration
Returns
Promise<PaginatedList<AgentActivity>>Example
// Get recent agent activity
const activity = await vienna.fleet.activity('agt-abc123', {
limit: 50,
offset: 0,
});
console.log('Total activities:', activity.total);
activity.items.forEach(item => {
console.log(`${item.timestamp}: ${item.action} - ${item.status}`);
if (item.details) {
console.log('Details:', item.details);
}
});
// Get next page
const nextPage = await vienna.fleet.activity('agt-abc123', {
limit: 50,
offset: 50,
});alerts
#vienna.fleet.alerts(params?: FleetAlertParams, options?: RequestOptions): Promise<FleetAlert[]>List fleet-wide alerts with optional filtering by resolution status, severity, or specific agent.
Parameters
params—FleetAlertParams(optional)Optional filter parameters
options—RequestOptions(optional)Optional request configuration
Returns
Promise<FleetAlert[]>Example
// Get unresolved alerts
const unresolvedAlerts = await vienna.fleet.alerts({
resolved: false,
});
// Get critical alerts for specific agent
const criticalAlerts = await vienna.fleet.alerts({
severity: 'critical',
agentId: 'agt-abc123',
});
unresolvedAlerts.forEach(alert => {
console.log(`Alert ${alert.id}: ${alert.severity}`);
console.log('Message:', alert.message);
console.log('Agent:', alert.agentId);
console.log('Created:', alert.createdAt);
});Approvals Module
#The Approvals module handles operator review workflows for T1 and T2 risk tier intents. Operators can approve or deny pending actions through this interface.
list
#vienna.approvals.list(params?: ApprovalListParams, options?: RequestOptions): Promise<Approval[]>List pending and recent approvals with optional filtering by status, source agent, or risk tier.
Parameters
params—ApprovalListParams(optional)Optional filter parameters
options—RequestOptions(optional)Optional request configuration
Returns
Promise<Approval[]>Example
// Get pending approvals
const pending = await vienna.approvals.list({
status: 'pending',
});
// Get approvals from specific agent
const agentApprovals = await vienna.approvals.list({
source: 'billing-bot',
});
// Get high-risk approvals
const highRisk = await vienna.approvals.list({
riskTier: 'T2',
});
pending.forEach(approval => {
console.log(`Approval ${approval.id}:`);
console.log('Intent:', approval.intentId);
console.log('Action:', approval.action);
console.log('Source:', approval.source);
console.log('Risk tier:', approval.riskTier);
console.log('Expires at:', approval.expiresAt);
});approve
#vienna.approvals.approve(approvalId: string, params: ApproveParams, options?: RequestOptions): Promise<Approval>Approve a pending intent. If this satisfies all required approvals, a warrant will be issued and execution will begin.
Parameters
approvalId—stringThe approval identifier
params—ApproveParamsApproval details including operator and optional notes
options—RequestOptions(optional)Optional request configuration
Returns
Promise<Approval>Example
// Approve a pending intent
const approved = await vienna.approvals.approve('apr-abc123', {
operator: 'jane.doe',
notes: 'Approved after verifying vendor details and payment amount',
});
console.log('Approval status:', approved.status);
console.log('Approved by:', approved.operator);
console.log('Notes:', approved.notes);
console.log('Approved at:', approved.updatedAt);
// Check if intent is now executing
const intentStatus = await vienna.intent.status(approved.intentId);
console.log('Intent status:', intentStatus.status);deny
#vienna.approvals.deny(approvalId: string, params: DenyParams, options?: RequestOptions): Promise<Approval>Deny a pending intent. The intent will be cancelled and the agent will be notified of the denial reason.
Parameters
approvalId—stringThe approval identifier
params—DenyParamsDenial details including operator and reason
options—RequestOptions(optional)Optional request configuration
Returns
Promise<Approval>Example
// Deny a pending intent
const denied = await vienna.approvals.deny('apr-abc123', {
operator: 'john.smith',
reason: 'Payment amount exceeds approved vendor contract limit',
});
console.log('Denial status:', denied.status);
console.log('Denied by:', denied.operator);
console.log('Reason:', denied.reason);
console.log('Denied at:', denied.updatedAt);Integrations Module
#The Integrations module manages external service connections for notifications and webhooks. Configure Slack channels, email alerts, PagerDuty, or custom webhooks to receive governance events.
create
#vienna.integrations.create(params: IntegrationCreateParams, options?: RequestOptions): Promise<Integration>Create a new integration for receiving notifications about governance events.
Parameters
params—IntegrationCreateParamsIntegration configuration including type, name, and connection details
options—RequestOptions(optional)Optional request configuration
Returns
Promise<Integration>Example
// Create a Slack integration
const slackIntegration = await vienna.integrations.create({
type: 'slack',
name: 'Engineering Alerts',
config: {
webhook_url: 'https://hooks.slack.com/services/YOUR_SLACK_WEBHOOK_URL',
channel: '#ai-governance',
},
eventTypes: [
'approval_required',
'execution_failed',
'policy_violation',
'agent_suspended',
],
});
// Create a webhook integration
const webhookIntegration = await vienna.integrations.create({
type: 'webhook',
name: 'Monitoring Dashboard',
config: {
url: 'https://monitoring.acme.com/vienna-webhooks',
secret: 'whsec_your_webhook_secret',
headers: {
'Authorization': 'Bearer your_api_key',
},
},
eventTypes: ['execution_complete', 'verification_mismatch'],
});list
#vienna.integrations.list(options?: RequestOptions): Promise<Integration[]>List all configured integrations with their current status and settings.
Parameters
options—RequestOptions(optional)Optional request configuration
Returns
Promise<Integration[]>Example
// List all integrations
const integrations = await vienna.integrations.list();
integrations.forEach(integration => {
console.log(`Integration ${integration.id}: ${integration.name}`);
console.log('Type:', integration.type);
console.log('Enabled:', integration.enabled);
console.log('Event types:', integration.eventTypes);
console.log('Last tested:', integration.lastTestedAt);
});test
#vienna.integrations.test(integrationId: string, options?: RequestOptions): Promise<IntegrationTestResult>Send a test event to an integration to verify connectivity and configuration.
Parameters
integrationId—stringThe integration identifier to test
options—RequestOptions(optional)Optional request configuration
Returns
Promise<IntegrationTestResult>Example
// Test an integration
const testResult = await vienna.integrations.test('int-abc123');
if (testResult.success) {
console.log('Integration test successful!');
console.log('Latency:', testResult.latencyMs, 'ms');
} else {
console.log('Integration test failed:', testResult.error);
}
// Test result includes:
// - success: boolean
// - latencyMs: number
// - error?: stringdelete
#vienna.integrations.delete(integrationId: string, options?: RequestOptions): Promise<void>Delete an integration. All future events will stop being sent to this endpoint.
Parameters
integrationId—stringThe integration identifier to delete
options—RequestOptions(optional)Optional request configuration
Returns
Promise<void>Example
// Delete an integration
await vienna.integrations.delete('int-abc123');
console.log('Integration deleted');Compliance Module
#The Compliance module generates audit reports and provides compliance statistics for regulatory requirements. Generate reports for specific time periods or get quick stats for monitoring.
generate
#vienna.compliance.generate(params: ComplianceGenerateParams, options?: RequestOptions): Promise<ComplianceReport>Generate a new compliance report for a specified time period. Reports include all governance events, policy evaluations, and audit trails.
Parameters
params—ComplianceGenerateParamsReport parameters including type and time period
options—RequestOptions(optional)Optional request configuration
Returns
Promise<ComplianceReport>Example
// Generate a quarterly compliance report
const report = await vienna.compliance.generate({
type: 'quarterly',
periodStart: '2026-01-01',
periodEnd: '2026-03-31',
tenantId: 'acme-corp', // optional
});
console.log('Report ID:', report.id);
console.log('Status:', report.status);
console.log('Type:', report.type);
console.log('Period:', report.periodStart, 'to', report.periodEnd);
if (report.status === 'ready') {
console.log('Download URL:', report.downloadUrl);
console.log('Summary:', report.summary);
} else {
console.log('Report is still generating...');
}get
#vienna.compliance.get(reportId: string, options?: RequestOptions): Promise<ComplianceReport>Get a compliance report by ID with current status and summary data if available.
Parameters
reportId—stringThe report identifier
options—RequestOptions(optional)Optional request configuration
Returns
Promise<ComplianceReport>Example
// Get a compliance report
const report = await vienna.compliance.get('rpt-abc123');
if (report.status === 'ready') {
console.log('Report ready!');
console.log('Total intents:', report.summary.totalIntents);
console.log('Approved intents:', report.summary.approvedIntents);
console.log('Denied intents:', report.summary.deniedIntents);
console.log('Policy violations:', report.summary.policyViolations);
console.log('Compliance score:', report.summary.complianceScore);
// Download the report
const response = await fetch(report.downloadUrl);
const pdfBuffer = await response.arrayBuffer();
}quickStats
#vienna.compliance.quickStats(params: QuickStatsParams, options?: RequestOptions): Promise<ComplianceSummary>Get quick compliance statistics for a rolling window without generating a full report.
Parameters
params—QuickStatsParamsStats parameters including number of days
options—RequestOptions(optional)Optional request configuration
Returns
Promise<ComplianceSummary>Example
// Get stats for the last 30 days
const stats = await vienna.compliance.quickStats({
days: 30,
tenantId: 'acme-corp', // optional
});
console.log('Last 30 days stats:');
console.log('Total intents:', stats.totalIntents);
console.log('Approved intents:', stats.approvedIntents);
console.log('Denied intents:', stats.deniedIntents);
console.log('Pending approvals:', stats.pendingApprovals);
console.log('Policy violations:', stats.policyViolations);
console.log('Average response time:', stats.avgResponseTimeMs, 'ms');
console.log('Compliance score:', stats.complianceScore, '%');
// Top violating agents
console.log('Top violating agents:');
stats.topViolatingAgents.forEach(agent => {
console.log(`- ${agent.agentId}: ${agent.violations} violations`);
});Ready to start building?
Install the SDK and start governing your agents in minutes.