Skip to main content

​
Overview

The VaryOn API provides programmatic access to all four products: Drift, Convergence, Cascade, and Meridian. Our RESTful API uses standard HTTP methods and returns JSON responses.

​
Base URL

All API requests should be made to: 
https://api.varyon.ai/v1
For EU customers: 
https://eu.api.varyon.ai/v1

​
Authentication

All API requests require authentication using an API key.
Include your API key in the Authorization header: 
Authorization: Bearer sk_live_your_api_key_here

curl https://api.varyon.ai/v1/drift/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_123"}'

​
API Keys

​
Key Types

TypePrefixUsageRate Limits
Livesk_live_Production useBased on plan
Testsk_test_Development/testing1000 req/day
Restrictedsk_rstr_Limited scopeCustom

​
Managing API Keys

Generate and manage API keys from your dashboard:
  1. Navigate to Settings → API Keys
  2. Click Generate New Key
  3. Set permissions and rate limits
  4. Copy the key (shown only once)
Never expose API keys in client-side code or public repositories. Use environment variables or secure key management services.

​
Rate Limits

Rate limits vary by product and pricing tier:
ProductFree TrialStarterProfessionalEnterprise
Drift100/hour1,000/hour10,000/hourUnlimited
Convergence50/hour500/hour5,000/hourUnlimited
Cascade10/hour100/hour1,000/hourCustom
Meridian1,000/hour10,000/hour100,000/hourUnlimited

​
Rate Limit Headers

Every response includes rate limit information: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Response Format

All responses follow a consistent format:

​
Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "metadata": {
    "request_id": "req_abc123",
    "timestamp": "2024-03-01T10:00:00Z",
    "processing_time_ms": 124
  }
}

​
Error Response

{
  "success": false,
  "error": {
    "type": "validation_error",
    "message": "Invalid agent_id format",
    "code": "INVALID_AGENT_ID",
    "details": {
      "field": "agent_id",
      "expected": "string",
      "received": "number"
    }
  },
  "metadata": {
    "request_id": "req_xyz789",
    "timestamp": "2024-03-01T10:00:00Z"
  }
}

​
Error Codes

HTTP StatusError CodeDescription
400BAD_REQUESTInvalid request parameters
401UNAUTHORIZEDInvalid or missing API key
403FORBIDDENInsufficient permissions
404NOT_FOUNDResource not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error
503SERVICE_UNAVAILABLETemporary outage

​
Pagination

List endpoints support pagination using cursor-based pagination: 
GET /v1/drift/analyses?limit=100&cursor=eyJpZCI6MTIzfQ==
Response includes pagination metadata: 
{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6MjIzfQ==",
    "total_count": 1543
  }
}

​
Webhooks

Configure webhooks to receive real-time events: 
POST /v1/webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["drift.shadow_detected", "convergence.collusion_found"],
  "secret": "whsec_your_secret"
}

​
Webhook Security

Verify webhook signatures to ensure authenticity: 
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

​
Idempotency

Prevent duplicate operations using idempotency keys: 
curl -X POST https://api.varyon.ai/v1/drift/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: unique_key_123" \
  -d '{"agent_id": "agent_123"}'

​
Versioning

The API is versioned via the URL path. The current version is v1. When we introduce breaking changes:
  1. New version endpoint created (e.g., v2)
  2. Previous version supported for 12 months
  3. Migration guide provided
  4. Deprecation notices sent 6 months in advance

​
SDKs & Libraries

Official SDKs available for:

Python

pip install varyon

JavaScript/TypeScript

npm install @varyon/sdk

Go

go get github.com/varyon/go-sdk

Ruby

gem install varyon

Java

<dependency>
  <groupId>ai.varyon</groupId>
  <artifactId>varyon-sdk</artifactId>
</dependency>

C#/.NET

dotnet add package VaryOn.SDK

​
API Endpoints

Drift API

Shadow principal detection endpoints

Convergence API

Collusion detection endpoints

Cascade API

Risk simulation endpoints

Meridian API

Data quality gate endpoints

​
Testing

Use test mode to safely develop and test your integration:
  1. Use sk_test_ API keys
  2. All operations are sandboxed
  3. No charges applied
  4. Synthetic data available

​
Test Data

Generate test data for development: 
POST /v1/test/generate
{
  "product": "drift",
  "scenario": "shadow_principal_detected",
  "count": 100
}

​
Support

Need help with the API? We’re here to assist: