Python & TypeScript

SDKs & Libraries

Execute AI protocols, enforce governance, emit evidence, and check compliance — in Python, TypeScript, or from the command line.

Request Early Access API Reference

Python SDK

Full-featured Python client with type hints, async support, and built-in retry logic. Ideal for backend services, data pipelines, and ML workflows.

TypeScript SDK

First-class TypeScript support with full type inference, tree-shakeable modules, and browser + Node.js compatibility.

CLI Tool

Command-line interface for scripting, CI/CD pipelines, and quick operations. Pipe-friendly JSON output.

MCP Server

ARQERA as a Model Context Protocol server. Give Claude, ChatGPT, and other AI assistants direct access to your governance engine.

Widget SDK

Embeddable compliance widget for customer-facing applications. Display real-time governance status and audit evidence.

REST API

990+ endpoints with full OpenAPI spec. Every SDK method maps 1:1 to a documented REST endpoint.

PythonMIT License

pip install arqera

Python 3.9+Type hints includedAsync support

TypeScriptMIT License

npm install @arqera/sdk

Node.js 18+ / BrowserFull type inferenceTree-shakeable

Python SDK

Full-featured client for backend services, pipelines, and ML workflows

Quick Start

bash

pip install arqera

# Verify installation
python -c "import arqera; print(arqera.__version__)"

Initialize the Client

python

from arqera import ArqeraClient

# API key authentication (server-side)
client = ArqeraClient(api_key="ak_live_your_key_here")

# Or use environment variables (recommended)
import os
client = ArqeraClient(api_key=os.environ["ARQERA_API_KEY"])

# Or OAuth token for user sessions
client = ArqeraClient()
tokens = client.auth.login(email="[email protected]", password="...")
client.set_access_token(tokens.access_token)
# Token auto-refresh is handled automatically

Core Methods

protocol.execute()

Execute an AI protocol with governance evaluation

python

from arqera import ArqeraClient

client = ArqeraClient(api_key="ak_live_...")

# Execute a protocol — governance is evaluated automatically
result = client.protocol.execute(
    manifest_id="customer-support-v2",
    input={
        "query": "Should we approve this $5,000 refund?",
        "context": {"customer_tier": "enterprise", "account_age_days": 730},
    },
    options={"require_approval": True, "timeout_seconds": 30},
)

print(f"Decision: {result.output}")
print(f"Execution ID: {result.execution_id}")
print(f"Evidence hash: {result.evidence_hash}")
# Decision: APPROVED — Enterprise customer, 2yr tenure, within policy limits
# Execution ID: exec_a1b2c3d4
# Evidence hash: sha256:9f86d08...

ara.execute()

Send a natural language instruction to Ara with action tier enforcement

python

# Ara executes with action tier enforcement
# AUTO = instant, SOFT = 30s undo window, HARD = requires approval

action = client.ara.execute(
    instruction="Send the quarterly report to the finance team",
    context={"tenant_id": "tenant_abc123"},
)

if action.tier == "HARD":
    print(f"Approval required: {action.approval_url}")
    # User approves via dashboard or Slack bot
    approved = client.ara.approve(action.action_id)
elif action.tier == "SOFT":
    print(f"Executed. Undo within 30s: {action.undo_url}")
else:
    print(f"Completed: {action.result}")

evidence.emit()

Emit tamper-evident audit artifacts for any action

python

# Emit evidence for audit trail — every action leaves a trace
artifact = client.evidence.emit(
    event_type="refund.approved",
    payload={
        "customer_id": "cust_xyz",
        "amount": 5000,
        "currency": "USD",
        "approved_by": "ara-agent-v2",
        "governance_score": 0.94,
    },
    artifact_type="financial_decision",
)

print(f"Artifact ID: {artifact.id}")
print(f"Hash: {artifact.hash}")  # SHA-256, tamper-evident
print(f"Timestamp: {artifact.created_at}")  # ISO 8601, immutable

compliance.check()

Run compliance checks against SOC 2, GDPR, EU AI Act frameworks

python

# Check SOC 2 compliance status for your tenant
report = client.compliance.check(
    framework="soc2",
    scope={"categories": ["access_control", "data_encryption", "audit_logging"]},
)

print(f"Status: {report.status}")       # COMPLIANT | NON_COMPLIANT | PARTIAL
print(f"Score: {report.score}/100")      # 94/100
print(f"Findings: {len(report.findings)}")

for finding in report.findings:
    print(f"  [{finding.severity}] {finding.title}")
    # [LOW] API key rotation recommended within 30 days

Async Support

python

from arqera import AsyncArqeraClient
import asyncio

async def main():
    client = AsyncArqeraClient(api_key="ak_live_...")

    # All methods have async equivalents
    result = await client.protocol.execute(
        manifest_id="customer-support-v2",
        input={"query": "Check order status for #12345"},
    )

    # Run multiple checks in parallel
    soc2, gdpr, ai_act = await asyncio.gather(
        client.compliance.check(framework="soc2"),
        client.compliance.check(framework="gdpr"),
        client.compliance.check(framework="eu_ai_act"),
    )

    print(f"SOC 2: {soc2.score}/100")
    print(f"GDPR: {gdpr.score}/100")
    print(f"EU AI Act: {ai_act.score}/100")

asyncio.run(main())

TypeScript SDK

First-class types, tree-shakeable, browser and Node.js compatible

Quick Start

bash

npm install @arqera/sdk
# or
yarn add @arqera/sdk
# or
pnpm add @arqera/sdk

Initialize the Client

typescript

import { ArqeraClient } from '@arqera/sdk';

// API key authentication
const client = new ArqeraClient({
  apiKey: process.env.ARQERA_API_KEY!,
  // baseUrl defaults to https://api.arqera.io
});

// With retry configuration
const resilientClient = new ArqeraClient({
  apiKey: process.env.ARQERA_API_KEY!,
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,      // Base delay in ms
    retryOn: [429, 503],   // Status codes to retry
  },
});

Core Methods

protocol.execute()

Execute an AI protocol with full type inference

typescript

import { ArqeraClient, type ExecuteResponse } from '@arqera/sdk';

const client = new ArqeraClient({
  apiKey: process.env.ARQERA_API_KEY!,
});

// Full type inference on request and response
const result: ExecuteResponse = await client.protocol.execute({
  manifest_id: 'customer-support-v2',
  input: {
    query: 'Should we approve this $5,000 refund?',
    context: { customer_tier: 'enterprise', account_age_days: 730 },
  },
  options: { require_approval: true, timeout_seconds: 30 },
});

console.log(`Decision: ${result.output}`);
console.log(`Evidence: ${result.evidence_hash}`);

ara.execute()

Natural language AI execution with action tiers

typescript

// Ara enforces action tiers automatically
// AUTO = instant | SOFT = 30s undo | HARD = requires approval

const action = await client.ara.execute({
  instruction: 'Send the quarterly report to the finance team',
  context: { tenant_id: 'tenant_abc123' },
});

switch (action.tier) {
  case 'HARD':
    console.log(`Approval needed: ${action.approval_url}`);
    const approved = await client.ara.approve(action.action_id);
    break;
  case 'SOFT':
    console.log(`Done. Undo: ${action.undo_url}`);
    break;
  case 'AUTO':
    console.log(`Completed: ${action.result}`);
    break;
}

evidence.emit()

Typed evidence emission with SHA-256 hashing

typescript

import type { EvidenceArtifact } from '@arqera/sdk';

const artifact: EvidenceArtifact = await client.evidence.emit({
  event_type: 'refund.approved',
  payload: {
    customer_id: 'cust_xyz',
    amount: 5000,
    currency: 'USD',
    approved_by: 'ara-agent-v2',
    governance_score: 0.94,
  },
  artifact_type: 'financial_decision',
});

console.log(`Hash: ${artifact.hash}`); // SHA-256, immutable

compliance.check()

Async compliance verification against multiple frameworks

typescript

const report = await client.compliance.check({
  framework: 'gdpr',
  scope: {
    categories: ['data_processing', 'consent_management', 'right_to_erasure'],
  },
});

console.log(`GDPR Status: ${report.status}`);  // COMPLIANT
console.log(`Score: ${report.score}/100`);       // 97/100

for (const finding of report.findings) {
  console.log(`  [${finding.severity}] ${finding.title}`);
}

Full Type Exports

typescript

import {
  ArqeraClient,
  ArqeraError,
  // Request types
  type ExecuteRequest,
  type EvidenceEmitRequest,
  type ComplianceCheckRequest,
  type AraExecuteRequest,
  // Response types
  type ExecuteResponse,
  type EvidenceArtifact,
  type ComplianceReport,
  type AraAction,
  // Enums
  type ActionTier,      // 'AUTO' | 'SOFT' | 'HARD'
  type ComplianceStatus, // 'COMPLIANT' | 'NON_COMPLIANT' | 'PARTIAL'
  type ProviderHealth,   // 'healthy' | 'degraded' | 'down'
} from '@arqera/sdk';

Same API, Your Language

Every method is available in both Python and TypeScript with identical behavior and response shapes.

Python

python

from arqera import ArqeraClient

client = ArqeraClient(api_key="ak_live_...")

# 1. Execute protocol with governance
result = client.protocol.execute(
    manifest_id="deploy-approval-v1",
    input={"service": "payments", "env": "production"},
)

# 2. Emit evidence for the decision
artifact = client.evidence.emit(
    event_type="deploy.approved",
    payload={"service": "payments", "version": "2.4.1"},
)

# 3. Verify compliance
report = client.compliance.check(framework="soc2")
print(f"Clear to deploy: {report.status == 'COMPLIANT'}")

TypeScript

typescript

import { ArqeraClient } from '@arqera/sdk';

const client = new ArqeraClient({
  apiKey: 'ak_live_...',
});

// 1. Execute protocol with governance
const result = await client.protocol.execute({
  manifest_id: 'deploy-approval-v1',
  input: { service: 'payments', env: 'production' },
});

// 2. Emit evidence for the decision
const artifact = await client.evidence.emit({
  event_type: 'deploy.approved',
  payload: { service: 'payments', version: '2.4.1' },
});

// 3. Verify compliance
const report = await client.compliance.check({
  framework: 'soc2',
});
console.log(`Clear to deploy: ${report.status === 'COMPLIANT'}`);

CLI Tool

Command-line interface for scripting, CI/CD, and quick operations

Installation

bash

# Install via pip (includes the CLI)
pip install arqera

# Authenticate
arqera auth login --api-key ak_live_your_key

# Verify
arqera whoami

Commands

arqera ara execute

Execute an Ara instruction from the terminal

arqera ara execute "Check SOC 2 compliance status" --format json

arqera governance evaluate

Evaluate a governance policy against input data

arqera governance evaluate --manifest customer-support-v2 --input '{"query":"approve refund"}'

arqera evidence export

Export evidence artifacts as JSON or CSV

arqera evidence export --from 2026-01-01 --to 2026-02-19 --format csv > audit.csv

arqera compliance check

Run a compliance check and output results

arqera compliance check --framework soc2 --scope access_control,encryption

arqera protocol list

List all registered protocol manifests

arqera protocol list --status active --format table

arqera providers health

Check AI provider health and latency

arqera providers health --provider anthropic --verbose

CI/CD Pipeline Example

bash

# GitHub Actions — pre-deploy compliance gate
- name: Compliance Gate
  run: |
    pip install arqera
    arqera auth login --api-key ${{ secrets.ARQERA_API_KEY }}

    # Check compliance before deploying
    arqera compliance check --framework soc2 --fail-on non_compliant

    # Execute deployment protocol
    arqera ara execute "Deploy payments service v2.4.1 to production" \
      --wait-for-approval \
      --timeout 300

    # Export evidence for audit
    arqera evidence export --last 1 --format json > deploy-evidence.json

MCP Server

Give AI assistants direct access to your governance engine

ARQERA exposes a Model Context Protocol (MCP) server, letting AI assistants like Claude and ChatGPT execute governed actions, query compliance status, and emit evidence — all through natural language with full governance enforcement.

Claude Desktop Configuration

json

{
  "mcpServers": {
    "arqera": {
      "command": "npx",
      "args": ["-y", "@arqera/mcp-server"],
      "env": {
        "ARQERA_API_KEY": "ak_live_your_key_here",
        "ARQERA_BASE_URL": "https://api.arqera.io"
      }
    }
  }
}

Available MCP Tools

arqera_execute_protocolarqera_check_compliancearqera_emit_evidencearqera_list_manifestsarqera_get_governance_statusarqera_approve_actionarqera_query_evidencearqera_check_provider_health

Governance stays enforced. Even when an AI assistant calls ARQERA via MCP, action tiers are enforced. HARD actions still require human approval through the dashboard or Slack bot — the AI cannot bypass governance.

Widget SDK

Embeddable compliance and governance displays for your applications

Embed a real-time compliance badge or governance dashboard directly in your customer-facing application. Show your customers that AI decisions are governed, auditable, and compliant.

Embed the Widget

html

<!-- Add to your HTML -->
<script src="https://cdn.arqera.io/widget/v1/arqera-widget.js"></script>

<div
  id="arqera-compliance-badge"
  data-tenant-id="tenant_abc123"
  data-framework="soc2"
  data-theme="dark"
></div>

<script>
  ArqeraWidget.init({
    apiKey: 'ak_pub_your_publishable_key',
    element: '#arqera-compliance-badge',
    display: 'badge',        // 'badge' | 'card' | 'dashboard'
    frameworks: ['soc2', 'gdpr'],
    refreshInterval: 300,    // seconds
  });
</script>

React Component

typescript

import { ArqeraComplianceBadge } from '@arqera/widget-react';

export function Footer() {
  return (
    <footer>
      <ArqeraComplianceBadge
        tenantId="tenant_abc123"
        frameworks={['soc2', 'gdpr']}
        theme="auto"
        display="badge"
      />
    </footer>
  );
}

Authentication

API keys, OAuth tokens, and JWT — choose the right method for your use case

API Key

Server-side apps, CI/CD

X-API-Key: ak_live_...

Scoped permissions, instant rotation, tenant-isolated. Generate from Settings > API Keys.

OAuth 2.0

User-facing apps

Authorization: Bearer eyJ...

PKCE flow for SPAs, authorization code for backends. Auto-refresh via SDK.

JWT (Service)

Machine-to-machine

Authorization: Bearer eyJ...

RS256-signed service tokens for automated systems. No user context required.

Environment Variables

Variable	Description	Default
ARQERA_API_KEY	API key for authentication	`Required`
ARQERA_BASE_URL	API base URL	`https://api.arqera.io`
ARQERA_TIMEOUT	Request timeout in seconds	`30`
ARQERA_MAX_RETRIES	Maximum retry attempts	`3`
ARQERA_DEBUG	Enable debug logging	`false`

Error Handling

Typed error classes with structured codes for predictable failure handling

Python

python

from arqera import ArqeraClient, ArqeraError
from arqera.errors import (
    AuthenticationError,
    AuthorizationError,
    RateLimitError,
    GovernanceRejectedError,
    ValidationError,
)

try:
    result = client.protocol.execute(
        manifest_id="high-risk-action",
        input={"amount": 50000},
    )
except GovernanceRejectedError as e:
    print(f"Governance blocked: {e.message}")
    print(f"Policy: {e.policy_id}")
    print(f"Reason: {e.rejection_reason}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key — rotate and retry")
except ArqeraError as e:
    print(f"API error [{e.code}]: {e.message}")
    print(f"Status: {e.status_code}")
    print(f"Request ID: {e.request_id}")

TypeScript

typescript

import {
  ArqeraClient,
  ArqeraError,
  GovernanceRejectedError,
  RateLimitError,
  AuthenticationError,
} from '@arqera/sdk';

try {
  const result = await client.protocol.execute({
    manifest_id: 'high-risk-action',
    input: { amount: 50000 },
  });
} catch (error) {
  if (error instanceof GovernanceRejectedError) {
    console.error(`Blocked: ${error.message}`);
    console.error(`Policy: ${error.policyId}`);
  } else if (error instanceof RateLimitError) {
    console.error(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ArqeraError) {
    console.error(`[${error.code}]: ${error.message}`);
    console.error(`Request: ${error.requestId}`);
  } else {
    throw error;
  }
}

Error Code Reference

Code	Status	Description	Resolution
authentication_failed	401	Invalid or expired API key / token	Rotate your API key or refresh your OAuth token
authorization_denied	403	Insufficient permissions for this action	Check API key scopes or user role assignments
resource_not_found	404	Requested manifest, artifact, or entity not found	Verify the resource ID exists in your tenant
validation_error	422	Request body fails schema validation	Check request body against the OpenAPI spec
rate_limit_exceeded	429	Too many requests in the current window	Implement exponential backoff or upgrade your plan
governance_rejected	451	Action rejected by governance evaluation	Review the governance policy or request manual approval
provider_unavailable	503	AI provider is temporarily unavailable	Auto-fallback will route to backup providers
execution_timeout	504	Protocol execution exceeded timeout	Increase timeout_seconds or simplify the request

Built-in Retry with Exponential Backoff

typescript

// Both SDKs include configurable retry logic
const client = new ArqeraClient({
  apiKey: 'ak_live_...',
  retryConfig: {
    maxRetries: 3,         // Retry up to 3 times
    retryDelay: 1000,      // Start with 1s delay
    retryOn: [429, 503],   // Retry on rate limit and service unavailable
    backoffMultiplier: 2,  // Double delay each retry (1s, 2s, 4s)
  },
});

// Python equivalent:
// client = ArqeraClient(
//     api_key="ak_live_...",
//     max_retries=3,
//     retry_delay=1.0,
//     retry_on=[429, 503],
// )

Rate Limits

Per-tier rate limits to ensure fair usage and predictable performance

Tier	Requests	Burst	Protocols/day	Evidence/day	Compliance/day
Free	60/min	10	100/day	500/day	50/day
Team	300/min	50	5,000/day	25,000/day	2,500/day
Business	1,000/min	200	50,000/day	250,000/day	25,000/day
Enterprise	Custom	Custom	Unlimited	Unlimited	Unlimited

Rate Limit Headers

Every response includes rate limit headers so you can track your usage in real time.

bash

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1708300800
Retry-After: 12    # Only on 429 responses

Need Higher Limits?

Enterprise plans include custom rate limits, dedicated infrastructure, and priority routing. Contact sales for a tailored plan.

Request Access |Contact sales

Advanced Patterns

Pagination, streaming, webhooks, and real-world integration patterns

Pagination

python

# Python — iterate all pages
def get_all_manifests(client):
    page = 1
    while True:
        result = client.protocol.list_manifests(
            page=page, page_size=50
        )
        yield from result.items
        if not result.has_next:
            break
        page += 1

for manifest in get_all_manifests(client):
    print(manifest.name)

typescript

// TypeScript — async generator
async function* getAllManifests(client: ArqeraClient) {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await client.protocol.listManifests({
      page,
      page_size: 50,
    });
    yield* result.items;
    hasMore = result.has_next;
    page++;
  }
}

for await (const manifest of getAllManifests(client)) {
  console.log(manifest.name);
}

Webhook Verification

python

from arqera.webhooks import verify_signature

# Verify incoming webhook (Express/Flask handler)
def handle_webhook(request):
    payload = request.body
    signature = request.headers["X-Arqera-Signature"]
    timestamp = request.headers["X-Arqera-Timestamp"]

    if not verify_signature(payload, signature, timestamp, webhook_secret):
        return {"error": "Invalid signature"}, 401

    event = json.loads(payload)
    match event["type"]:
        case "evidence.emitted":
            handle_evidence(event["data"])
        case "compliance.check.completed":
            handle_compliance(event["data"])
        case "governance.action.approved":
            handle_approval(event["data"])

    return {"ok": True}, 200

The ARQERA Pattern: Execute, Govern, Evidence

Every significant action in ARQERA follows the same three-step pattern: execute the action through the protocol engine, let governance evaluate the decision, and emit tamper-evident evidence for the audit trail.

python

# The canonical ARQERA pattern
from arqera import ArqeraClient

client = ArqeraClient(api_key="ak_live_...")

# Step 1: Execute through protocol — governance is embedded
result = client.protocol.execute(
    manifest_id="send-customer-email-v1",
    input={
        "to": "[email protected]",
        "subject": "Q4 Governance Report",
        "body": "Please find attached...",
        "attachments": ["report_q4_2026.pdf"],
    },
)

# Step 2: Check if governance requires approval
if result.requires_approval:
    print(f"Awaiting approval: {result.approval_url}")
    # Approval happens via dashboard, Slack bot, or API
    # client.ara.approve(result.action_id)
else:
    print(f"Sent automatically (tier: {result.action_tier})")

# Step 3: Evidence is emitted automatically
# Every execution produces an immutable evidence artifact
print(f"Evidence: {result.evidence_hash}")
print(f"Audit trail: https://app.arqera.io/evidence/{result.execution_id}")

Compatibility

Both SDKs are tested against all supported runtimes on every release.

Python SDK

Packagearqera

Python3.9, 3.10, 3.11, 3.12, 3.13

Type hintsFull (PEP 484 + PEP 604)

AsyncAsyncArqeraClient via asyncio

Dependencieshttpx, pydantic

LicenseMIT

TypeScript SDK

Package@arqera/sdk

Node.js18, 20, 22 (LTS)

BrowserES2020+ (Chrome, Firefox, Safari, Edge)

TypeScript5.0+

Bundle size~18 KB gzipped (tree-shakeable)

LicenseMIT

Start building with ARQERA

Get your API key and start integrating in under 5 minutes. Full SDK access on every plan.

Request Early Access Back to Docs

Python & TypeScript

SDKs & Libraries

Execute AI protocols, enforce governance, emit evidence, and check compliance — in Python, TypeScript, or from the command line.

Request Early Access API Reference

Python SDK

Full-featured Python client with type hints, async support, and built-in retry logic. Ideal for backend services, data pipelines, and ML workflows.

TypeScript SDK

First-class TypeScript support with full type inference, tree-shakeable modules, and browser + Node.js compatibility.

CLI Tool

Command-line interface for scripting, CI/CD pipelines, and quick operations. Pipe-friendly JSON output.

MCP Server

ARQERA as a Model Context Protocol server. Give Claude, ChatGPT, and other AI assistants direct access to your governance engine.

Widget SDK

Embeddable compliance widget for customer-facing applications. Display real-time governance status and audit evidence.

REST API

990+ endpoints with full OpenAPI spec. Every SDK method maps 1:1 to a documented REST endpoint.

PythonMIT License

pip install arqera

Python 3.9+Type hints includedAsync support

TypeScriptMIT License

npm install @arqera/sdk

Node.js 18+ / BrowserFull type inferenceTree-shakeable

Python SDK

Full-featured client for backend services, pipelines, and ML workflows

Quick Start

bash

pip install arqera

# Verify installation
python -c "import arqera; print(arqera.__version__)"

Initialize the Client

python

from arqera import ArqeraClient

# API key authentication (server-side)
client = ArqeraClient(api_key="ak_live_your_key_here")

# Or use environment variables (recommended)
import os
client = ArqeraClient(api_key=os.environ["ARQERA_API_KEY"])

# Or OAuth token for user sessions
client = ArqeraClient()
tokens = client.auth.login(email="[email protected]", password="...")
client.set_access_token(tokens.access_token)
# Token auto-refresh is handled automatically

Core Methods

protocol.execute()

Execute an AI protocol with governance evaluation

python

from arqera import ArqeraClient

client = ArqeraClient(api_key="ak_live_...")

# Execute a protocol — governance is evaluated automatically
result = client.protocol.execute(
    manifest_id="customer-support-v2",
    input={
        "query": "Should we approve this $5,000 refund?",
        "context": {"customer_tier": "enterprise", "account_age_days": 730},
    },
    options={"require_approval": True, "timeout_seconds": 30},
)

print(f"Decision: {result.output}")
print(f"Execution ID: {result.execution_id}")
print(f"Evidence hash: {result.evidence_hash}")
# Decision: APPROVED — Enterprise customer, 2yr tenure, within policy limits
# Execution ID: exec_a1b2c3d4
# Evidence hash: sha256:9f86d08...

ara.execute()

Send a natural language instruction to Ara with action tier enforcement

python

# Ara executes with action tier enforcement
# AUTO = instant, SOFT = 30s undo window, HARD = requires approval

action = client.ara.execute(
    instruction="Send the quarterly report to the finance team",
    context={"tenant_id": "tenant_abc123"},
)

if action.tier == "HARD":
    print(f"Approval required: {action.approval_url}")
    # User approves via dashboard or Slack bot
    approved = client.ara.approve(action.action_id)
elif action.tier == "SOFT":
    print(f"Executed. Undo within 30s: {action.undo_url}")
else:
    print(f"Completed: {action.result}")

evidence.emit()

Emit tamper-evident audit artifacts for any action

python

# Emit evidence for audit trail — every action leaves a trace
artifact = client.evidence.emit(
    event_type="refund.approved",
    payload={
        "customer_id": "cust_xyz",
        "amount": 5000,
        "currency": "USD",
        "approved_by": "ara-agent-v2",
        "governance_score": 0.94,
    },
    artifact_type="financial_decision",
)

print(f"Artifact ID: {artifact.id}")
print(f"Hash: {artifact.hash}")  # SHA-256, tamper-evident
print(f"Timestamp: {artifact.created_at}")  # ISO 8601, immutable

compliance.check()

Run compliance checks against SOC 2, GDPR, EU AI Act frameworks

python

# Check SOC 2 compliance status for your tenant
report = client.compliance.check(
    framework="soc2",
    scope={"categories": ["access_control", "data_encryption", "audit_logging"]},
)

print(f"Status: {report.status}")       # COMPLIANT | NON_COMPLIANT | PARTIAL
print(f"Score: {report.score}/100")      # 94/100
print(f"Findings: {len(report.findings)}")

for finding in report.findings:
    print(f"  [{finding.severity}] {finding.title}")
    # [LOW] API key rotation recommended within 30 days

Async Support

python

from arqera import AsyncArqeraClient
import asyncio

async def main():
    client = AsyncArqeraClient(api_key="ak_live_...")

    # All methods have async equivalents
    result = await client.protocol.execute(
        manifest_id="customer-support-v2",
        input={"query": "Check order status for #12345"},
    )

    # Run multiple checks in parallel
    soc2, gdpr, ai_act = await asyncio.gather(
        client.compliance.check(framework="soc2"),
        client.compliance.check(framework="gdpr"),
        client.compliance.check(framework="eu_ai_act"),
    )

    print(f"SOC 2: {soc2.score}/100")
    print(f"GDPR: {gdpr.score}/100")
    print(f"EU AI Act: {ai_act.score}/100")

asyncio.run(main())

TypeScript SDK

First-class types, tree-shakeable, browser and Node.js compatible

Quick Start

bash

npm install @arqera/sdk
# or
yarn add @arqera/sdk
# or
pnpm add @arqera/sdk

Initialize the Client

typescript

import { ArqeraClient } from '@arqera/sdk';

// API key authentication
const client = new ArqeraClient({
  apiKey: process.env.ARQERA_API_KEY!,
  // baseUrl defaults to https://api.arqera.io
});

// With retry configuration
const resilientClient = new ArqeraClient({
  apiKey: process.env.ARQERA_API_KEY!,
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,      // Base delay in ms
    retryOn: [429, 503],   // Status codes to retry
  },
});

Core Methods

protocol.execute()

Execute an AI protocol with full type inference

typescript

import { ArqeraClient, type ExecuteResponse } from '@arqera/sdk';

const client = new ArqeraClient({
  apiKey: process.env.ARQERA_API_KEY!,
});

// Full type inference on request and response
const result: ExecuteResponse = await client.protocol.execute({
  manifest_id: 'customer-support-v2',
  input: {
    query: 'Should we approve this $5,000 refund?',
    context: { customer_tier: 'enterprise', account_age_days: 730 },
  },
  options: { require_approval: true, timeout_seconds: 30 },
});

console.log(`Decision: ${result.output}`);
console.log(`Evidence: ${result.evidence_hash}`);

ara.execute()

Natural language AI execution with action tiers

typescript

// Ara enforces action tiers automatically
// AUTO = instant | SOFT = 30s undo | HARD = requires approval

const action = await client.ara.execute({
  instruction: 'Send the quarterly report to the finance team',
  context: { tenant_id: 'tenant_abc123' },
});

switch (action.tier) {
  case 'HARD':
    console.log(`Approval needed: ${action.approval_url}`);
    const approved = await client.ara.approve(action.action_id);
    break;
  case 'SOFT':
    console.log(`Done. Undo: ${action.undo_url}`);
    break;
  case 'AUTO':
    console.log(`Completed: ${action.result}`);
    break;
}

evidence.emit()

Typed evidence emission with SHA-256 hashing

typescript

import type { EvidenceArtifact } from '@arqera/sdk';

const artifact: EvidenceArtifact = await client.evidence.emit({
  event_type: 'refund.approved',
  payload: {
    customer_id: 'cust_xyz',
    amount: 5000,
    currency: 'USD',
    approved_by: 'ara-agent-v2',
    governance_score: 0.94,
  },
  artifact_type: 'financial_decision',
});

console.log(`Hash: ${artifact.hash}`); // SHA-256, immutable

compliance.check()

Async compliance verification against multiple frameworks

typescript

const report = await client.compliance.check({
  framework: 'gdpr',
  scope: {
    categories: ['data_processing', 'consent_management', 'right_to_erasure'],
  },
});

console.log(`GDPR Status: ${report.status}`);  // COMPLIANT
console.log(`Score: ${report.score}/100`);       // 97/100

for (const finding of report.findings) {
  console.log(`  [${finding.severity}] ${finding.title}`);
}

Full Type Exports

typescript

import {
  ArqeraClient,
  ArqeraError,
  // Request types
  type ExecuteRequest,
  type EvidenceEmitRequest,
  type ComplianceCheckRequest,
  type AraExecuteRequest,
  // Response types
  type ExecuteResponse,
  type EvidenceArtifact,
  type ComplianceReport,
  type AraAction,
  // Enums
  type ActionTier,      // 'AUTO' | 'SOFT' | 'HARD'
  type ComplianceStatus, // 'COMPLIANT' | 'NON_COMPLIANT' | 'PARTIAL'
  type ProviderHealth,   // 'healthy' | 'degraded' | 'down'
} from '@arqera/sdk';

Same API, Your Language

Every method is available in both Python and TypeScript with identical behavior and response shapes.

Python

python

from arqera import ArqeraClient

client = ArqeraClient(api_key="ak_live_...")

# 1. Execute protocol with governance
result = client.protocol.execute(
    manifest_id="deploy-approval-v1",
    input={"service": "payments", "env": "production"},
)

# 2. Emit evidence for the decision
artifact = client.evidence.emit(
    event_type="deploy.approved",
    payload={"service": "payments", "version": "2.4.1"},
)

# 3. Verify compliance
report = client.compliance.check(framework="soc2")
print(f"Clear to deploy: {report.status == 'COMPLIANT'}")

TypeScript

typescript

import { ArqeraClient } from '@arqera/sdk';

const client = new ArqeraClient({
  apiKey: 'ak_live_...',
});

// 1. Execute protocol with governance
const result = await client.protocol.execute({
  manifest_id: 'deploy-approval-v1',
  input: { service: 'payments', env: 'production' },
});

// 2. Emit evidence for the decision
const artifact = await client.evidence.emit({
  event_type: 'deploy.approved',
  payload: { service: 'payments', version: '2.4.1' },
});

// 3. Verify compliance
const report = await client.compliance.check({
  framework: 'soc2',
});
console.log(`Clear to deploy: ${report.status === 'COMPLIANT'}`);

CLI Tool

Command-line interface for scripting, CI/CD, and quick operations

Installation

bash

# Install via pip (includes the CLI)
pip install arqera

# Authenticate
arqera auth login --api-key ak_live_your_key

# Verify
arqera whoami

Commands

arqera ara execute

Execute an Ara instruction from the terminal

arqera ara execute "Check SOC 2 compliance status" --format json

arqera governance evaluate

Evaluate a governance policy against input data

arqera governance evaluate --manifest customer-support-v2 --input '{"query":"approve refund"}'

arqera evidence export

Export evidence artifacts as JSON or CSV

arqera evidence export --from 2026-01-01 --to 2026-02-19 --format csv > audit.csv

arqera compliance check

Run a compliance check and output results

arqera compliance check --framework soc2 --scope access_control,encryption

arqera protocol list

List all registered protocol manifests

arqera protocol list --status active --format table

arqera providers health

Check AI provider health and latency

arqera providers health --provider anthropic --verbose

CI/CD Pipeline Example

bash

# GitHub Actions — pre-deploy compliance gate
- name: Compliance Gate
  run: |
    pip install arqera
    arqera auth login --api-key ${{ secrets.ARQERA_API_KEY }}

    # Check compliance before deploying
    arqera compliance check --framework soc2 --fail-on non_compliant

    # Execute deployment protocol
    arqera ara execute "Deploy payments service v2.4.1 to production" \
      --wait-for-approval \
      --timeout 300

    # Export evidence for audit
    arqera evidence export --last 1 --format json > deploy-evidence.json

MCP Server

Give AI assistants direct access to your governance engine

Claude Desktop Configuration

json

{
  "mcpServers": {
    "arqera": {
      "command": "npx",
      "args": ["-y", "@arqera/mcp-server"],
      "env": {
        "ARQERA_API_KEY": "ak_live_your_key_here",
        "ARQERA_BASE_URL": "https://api.arqera.io"
      }
    }
  }
}

Available MCP Tools

arqera_execute_protocolarqera_check_compliancearqera_emit_evidencearqera_list_manifestsarqera_get_governance_statusarqera_approve_actionarqera_query_evidencearqera_check_provider_health

Widget SDK

Embeddable compliance and governance displays for your applications

Embed a real-time compliance badge or governance dashboard directly in your customer-facing application. Show your customers that AI decisions are governed, auditable, and compliant.

Embed the Widget

html

<!-- Add to your HTML -->
<script src="https://cdn.arqera.io/widget/v1/arqera-widget.js"></script>

<div
  id="arqera-compliance-badge"
  data-tenant-id="tenant_abc123"
  data-framework="soc2"
  data-theme="dark"
></div>

<script>
  ArqeraWidget.init({
    apiKey: 'ak_pub_your_publishable_key',
    element: '#arqera-compliance-badge',
    display: 'badge',        // 'badge' | 'card' | 'dashboard'
    frameworks: ['soc2', 'gdpr'],
    refreshInterval: 300,    // seconds
  });
</script>

React Component

typescript

import { ArqeraComplianceBadge } from '@arqera/widget-react';

export function Footer() {
  return (
    <footer>
      <ArqeraComplianceBadge
        tenantId="tenant_abc123"
        frameworks={['soc2', 'gdpr']}
        theme="auto"
        display="badge"
      />
    </footer>
  );
}

Authentication

API keys, OAuth tokens, and JWT — choose the right method for your use case

API Key

Server-side apps, CI/CD

X-API-Key: ak_live_...

Scoped permissions, instant rotation, tenant-isolated. Generate from Settings > API Keys.

OAuth 2.0

User-facing apps

Authorization: Bearer eyJ...

PKCE flow for SPAs, authorization code for backends. Auto-refresh via SDK.

JWT (Service)

Machine-to-machine

Authorization: Bearer eyJ...

RS256-signed service tokens for automated systems. No user context required.

Environment Variables

Variable	Description	Default
ARQERA_API_KEY	API key for authentication	`Required`
ARQERA_BASE_URL	API base URL	`https://api.arqera.io`
ARQERA_TIMEOUT	Request timeout in seconds	`30`
ARQERA_MAX_RETRIES	Maximum retry attempts	`3`
ARQERA_DEBUG	Enable debug logging	`false`

Error Handling

Typed error classes with structured codes for predictable failure handling

Python

python

from arqera import ArqeraClient, ArqeraError
from arqera.errors import (
    AuthenticationError,
    AuthorizationError,
    RateLimitError,
    GovernanceRejectedError,
    ValidationError,
)

try:
    result = client.protocol.execute(
        manifest_id="high-risk-action",
        input={"amount": 50000},
    )
except GovernanceRejectedError as e:
    print(f"Governance blocked: {e.message}")
    print(f"Policy: {e.policy_id}")
    print(f"Reason: {e.rejection_reason}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key — rotate and retry")
except ArqeraError as e:
    print(f"API error [{e.code}]: {e.message}")
    print(f"Status: {e.status_code}")
    print(f"Request ID: {e.request_id}")

TypeScript

typescript

import {
  ArqeraClient,
  ArqeraError,
  GovernanceRejectedError,
  RateLimitError,
  AuthenticationError,
} from '@arqera/sdk';

try {
  const result = await client.protocol.execute({
    manifest_id: 'high-risk-action',
    input: { amount: 50000 },
  });
} catch (error) {
  if (error instanceof GovernanceRejectedError) {
    console.error(`Blocked: ${error.message}`);
    console.error(`Policy: ${error.policyId}`);
  } else if (error instanceof RateLimitError) {
    console.error(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ArqeraError) {
    console.error(`[${error.code}]: ${error.message}`);
    console.error(`Request: ${error.requestId}`);
  } else {
    throw error;
  }
}

Error Code Reference

Code	Status	Description	Resolution
authentication_failed	401	Invalid or expired API key / token	Rotate your API key or refresh your OAuth token
authorization_denied	403	Insufficient permissions for this action	Check API key scopes or user role assignments
resource_not_found	404	Requested manifest, artifact, or entity not found	Verify the resource ID exists in your tenant
validation_error	422	Request body fails schema validation	Check request body against the OpenAPI spec
rate_limit_exceeded	429	Too many requests in the current window	Implement exponential backoff or upgrade your plan
governance_rejected	451	Action rejected by governance evaluation	Review the governance policy or request manual approval
provider_unavailable	503	AI provider is temporarily unavailable	Auto-fallback will route to backup providers
execution_timeout	504	Protocol execution exceeded timeout	Increase timeout_seconds or simplify the request

Built-in Retry with Exponential Backoff

typescript

// Both SDKs include configurable retry logic
const client = new ArqeraClient({
  apiKey: 'ak_live_...',
  retryConfig: {
    maxRetries: 3,         // Retry up to 3 times
    retryDelay: 1000,      // Start with 1s delay
    retryOn: [429, 503],   // Retry on rate limit and service unavailable
    backoffMultiplier: 2,  // Double delay each retry (1s, 2s, 4s)
  },
});

// Python equivalent:
// client = ArqeraClient(
//     api_key="ak_live_...",
//     max_retries=3,
//     retry_delay=1.0,
//     retry_on=[429, 503],
// )

Rate Limits

Per-tier rate limits to ensure fair usage and predictable performance

Tier	Requests	Burst	Protocols/day	Evidence/day	Compliance/day
Free	60/min	10	100/day	500/day	50/day
Team	300/min	50	5,000/day	25,000/day	2,500/day
Business	1,000/min	200	50,000/day	250,000/day	25,000/day
Enterprise	Custom	Custom	Unlimited	Unlimited	Unlimited

Rate Limit Headers

Every response includes rate limit headers so you can track your usage in real time.

bash

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1708300800
Retry-After: 12    # Only on 429 responses

Need Higher Limits?

Enterprise plans include custom rate limits, dedicated infrastructure, and priority routing. Contact sales for a tailored plan.

Request Access |Contact sales

Advanced Patterns

Pagination, streaming, webhooks, and real-world integration patterns

Pagination

python

# Python — iterate all pages
def get_all_manifests(client):
    page = 1
    while True:
        result = client.protocol.list_manifests(
            page=page, page_size=50
        )
        yield from result.items
        if not result.has_next:
            break
        page += 1

for manifest in get_all_manifests(client):
    print(manifest.name)

typescript

// TypeScript — async generator
async function* getAllManifests(client: ArqeraClient) {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await client.protocol.listManifests({
      page,
      page_size: 50,
    });
    yield* result.items;
    hasMore = result.has_next;
    page++;
  }
}

for await (const manifest of getAllManifests(client)) {
  console.log(manifest.name);
}

Webhook Verification

python

from arqera.webhooks import verify_signature

# Verify incoming webhook (Express/Flask handler)
def handle_webhook(request):
    payload = request.body
    signature = request.headers["X-Arqera-Signature"]
    timestamp = request.headers["X-Arqera-Timestamp"]

    if not verify_signature(payload, signature, timestamp, webhook_secret):
        return {"error": "Invalid signature"}, 401

    event = json.loads(payload)
    match event["type"]:
        case "evidence.emitted":
            handle_evidence(event["data"])
        case "compliance.check.completed":
            handle_compliance(event["data"])
        case "governance.action.approved":
            handle_approval(event["data"])

    return {"ok": True}, 200

The ARQERA Pattern: Execute, Govern, Evidence

python

# The canonical ARQERA pattern
from arqera import ArqeraClient

client = ArqeraClient(api_key="ak_live_...")

# Step 1: Execute through protocol — governance is embedded
result = client.protocol.execute(
    manifest_id="send-customer-email-v1",
    input={
        "to": "[email protected]",
        "subject": "Q4 Governance Report",
        "body": "Please find attached...",
        "attachments": ["report_q4_2026.pdf"],
    },
)

# Step 2: Check if governance requires approval
if result.requires_approval:
    print(f"Awaiting approval: {result.approval_url}")
    # Approval happens via dashboard, Slack bot, or API
    # client.ara.approve(result.action_id)
else:
    print(f"Sent automatically (tier: {result.action_tier})")

# Step 3: Evidence is emitted automatically
# Every execution produces an immutable evidence artifact
print(f"Evidence: {result.evidence_hash}")
print(f"Audit trail: https://app.arqera.io/evidence/{result.execution_id}")

Compatibility

Both SDKs are tested against all supported runtimes on every release.

Python SDK

Packagearqera

Python3.9, 3.10, 3.11, 3.12, 3.13

Type hintsFull (PEP 484 + PEP 604)

AsyncAsyncArqeraClient via asyncio

Dependencieshttpx, pydantic

LicenseMIT

TypeScript SDK

Package@arqera/sdk

Node.js18, 20, 22 (LTS)

BrowserES2020+ (Chrome, Firefox, Safari, Edge)

TypeScript5.0+

Bundle size~18 KB gzipped (tree-shakeable)

LicenseMIT

Start building with ARQERA

Get your API key and start integrating in under 5 minutes. Full SDK access on every plan.

Request Early Access Back to Docs