API Reference

Complete endpoint documentation with request/response formats, authentication, and error codes

REST API JSON Only No Rate Limits

Base URL

POST https://analyzecompliance-vrbinbrbkq-uc.a.run.app

All API requests are made to this endpoint using HTTP POST. ViriSIM accepts one audit submission at a time - batch processing is not supported.

Authentication

Every request must include a valid API key in the request header. API keys are generated from your dashboard under Integration → API Keys.

X-API-Key: sk-viri-your-api-key-here
Content-Type: application/json
Security: Never expose your API key in client-side code. Use environment variables or secure backend proxies.
API Key Format: Keys follow the pattern sk-viri-xxxxxxxxxxxxxxxxxxxx. You will only see the full key once upon creation - store it securely!

Submit Audit

Send an AI interaction (input + output) for compliance auditing. ViriSIM processes one request at a time and returns a submission ID immediately. The actual audit runs asynchronously.

 Request Body

{
  "user_id": "string",                    // Required: Your unique user identifier
  "company_name": "string",               // Required: Your organization name
  "use_case": "string",                   // Required: Primary use case (e.g., "Customer Support")
  "timestamp": new Date(),           // Required: Current timestamp (do not modify)
  "your_company_user_id": "string",       // Optional: Your internal user ID
  "your_company_user_session_id": "string", // Optional: Session ID for context
  "model_version": "string",              // Required: Your AI model version
 
"your_company_signature": "string",     // Optional: ECDSA signature proving your company signed this I/O before submission
"your_company_signing_key_id": "string", // Optional: KMS key path used to verify the signature
  "input": {
    "value": "string",                    // Required: Raw user input
    "format": "text|json",                // Required: "text" or "json"
    "country": "string"                   // Required: User's country or "global"
  },
  "output": {
    "value": "string",                    // Required: Raw AI-generated output
    "format": "text|json",                // Required: "text" or "json"
    "country": "string"                   // Required: Your country or "global"
  }
}

 Field Reference

FieldTypeRequiredDescription
user_idstring✓Your unique user identifier
company_namestring✓Your organization name
use_casestring✓Primary use of your AI (e.g., "Customer Support", "Financial Services")
timestampISO 8601✓Current timestamp - do not modify to ensure log accuracy(new Date())
your_company_user_idstring✗Your internal user ID for filtering logs
your_company_user_session_idstring✗Session ID for context analysis
model_versionstring✓Your AI model version for traceability
your_company_signaturestring✗ECDSA signature proving your company signed this I/O before submission
your_company_signing_key_idstring✗KMS key path used to verify the signature
input.valuestring✓Raw user input to your AI
input.formatstring✓"text" or "json"
input.countrystring✓User's country or "global"
output.valuestring✓Raw AI-generated output
output.formatstring✓"text" or "json"
output.countrystring✓Your country of business or "global"

 Success Response (200)

{
  "submission_id": "VIRI-0001234Xabcde",
  "message": "Success, entry undergoing audit.",
  "status": "success"
}
Important: The API returns immediately after validation. The actual audit runs asynchronously. Results are available in your dashboard under I/O Logs - there is no GET endpoint to retrieve results programmatically.
Token Limit: Each audit submission is limited to 2,000 tokens combined (input + output). Larger submissions will be rejected with error Tokens above the limit of 2k.

Response Times

Audit processing time depends on the size of the text being analyzed:

Token CountTypical Processing Time
< 500 tokens~2-5 seconds
500 - 1,000 tokens~5-10 seconds
1,000 - 2,000 tokens~10-20 seconds
Note: Times are estimates and may vary based on current system load and the complexity of the content being analyzed.

Rate Limits & Retry

To prevent overlapping audits from the same user and ensure audit integrity, ViriSIM enforces a 20-second cooldown per user_id. If you submit a second audit before the cooldown has elapsed, you'll receive a 429 Too Many Requests response.

Why this exists: Compliance audits read, modify, and write shared per-user state (token balance, monthly analytics, compliance streak). Running two audits concurrently for the same user can cause lost updates. The cooldown ensures clean sequential processing.

How to Retry Correctly

When you receive a 429, do not retry immediately. Read the Retry-After response header - it tells you exactly how many seconds remain before the next submission is allowed.

HTTP/1.1 429 Too Many Requests
Retry-After: 13
Content-Type: application/json

{
  "error": "Too many requests. Retry in 13 seconds."
}

Recommended Retry Pattern

The simplest client-side approach is to read the Retry-After header on 429 and schedule your retry after that many seconds. Example in JavaScript:

async function submitAuditWithRetry(payload, apiKey, maxRetries = 3) {
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
        const response = await fetch('https://analyzecompliance-vrbinbrbkq-uc.a.run.app', {
            method: 'POST',
            headers: {
                'X-API-Key': apiKey,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        // Success
        if (response.ok) {
            return await response.json();
        }

        // Rate limited - wait and retry
        if (response.status === 429) {
            const retryAfter = parseInt(response.headers.get('Retry-After') || '20', 10);
            console.log(`Rate limited. Retrying in ${retryAfter}s...`);
            await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
            continue;
        }

        // Other errors - don't retry
        const error = await response.json();
        throw new Error(error.error || `HTTP ${response.status}`);
    }

    throw new Error('Max retries exceeded');
}

Retry Decision Guide

ResponseActionReason
200 Done - audit queued Submission accepted
429 Wait Retry-After seconds, then retry Cooldown active - safe to retry
400 Do not retry - fix the request Malformed input or over token limit
401 Do not retry - fix the API key Authentication failure
403 Do not retry - top up or activate Insufficient tokens or no plan
500 Optional retry with backoff Transient server error
Best practice for batching: If you need to submit many audits for the same user_id, queue them client-side and space submissions by at least 20 seconds. This avoids all 429 responses.

Error Codes

StatusError MessageDescription & Solution
401 API key required in X-API-Key header Missing API key header. Add X-API-Key to your request headers.
401 Unauthorized access! Invalid or inactive API key. Generate a new key from the dashboard.
403 Insufficient Tokens Your account has run out of tokens. Purchase more tokens from Pricing → Buy Tokens.
403 No Subscription No active plan. Activate the Free Plan or purchase a Premium plan first.
400 Tokens above the limit of 2k Your input + output exceeds 2,000 tokens. Truncate before sending.
400 user_id required in request body Missing required user_id field in the request body.
400 Input format claims to be JSON but content is not valid JSON input.format is set to "json" but the content is invalid JSON.
429 Too Many Requests Only one audit per user per 20 seconds. Read the Retry-After header for exact seconds to wait before retrying.
500 Internal Server Error Unexpected server error. Contact support if persistent.

Viewing Audit Results

After submitting an audit, results are available in the ViriSIM dashboard:

  1. Log into your ViriSIM dashboard
  2. Navigate to I/O Logs
  3. Find your submission by submission_id or filter by date
  4. Click on any log to see the full audit report

 What Each Audit Includes:

  • Compliance Status: Fully Compliant / Review Needed / Non-Compliant
  • Risk Score: 0-10 (0 = lowest risk, 10 = highest)
  • Regulation Violations: Specific laws/regulations violated (GDPR, EU AI Act, HIPAA, etc.)
  • PII Detection: Identified personally identifiable information
  • Safety Issues: Content safety concerns flagged
  • Remediation Steps: Recommended actions to fix violations
  • Safe Input/Output: Redacted, compliant versions of your content
Export Options: You can download audit results in multiple formats (JSON, CSV, PDF) directly from the dashboard. Export settings are available in each log detail view.

Example Request

Here's a complete example of submitting an audit for a customer support interaction:

curl -X POST https://analyzecompliance-vrbinbrbkq-uc.a.run.app \
  -H "X-API-Key: sk-viri-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_12345",
    "company_name": "Example Corp",
    "use_case": "Customer Support",
    "timestamp": new Date(),
    "your_company_user_id": "internal_user_001",
    "your_company_user_session_id": "session_abc123",
    "model_version": "gpt-4-turbo",
"your_company_signature": "MEUCIQDxK9cF8mN2vR5jH7sT3wB6dL0pA1qY4uW8eR2oG5tSJgIgV7kM3nB4cD5fG6hJ8kL0mN1pQ2rS3tU4vW5xY6zA7==",
"your_company_signing_key_id": "projects/customer-project-123/locations/europe-west3/keyRings/compliance-signing-ring/cryptoKeys/audit-signing-key/cryptoKeyVersions/1",
    "input": {
        "value": "How do I delete my account?",
        "format": "text",
        "country": "Germany"
    },
    "output": {
        "value": "To delete your account, please click the 'Delete Account' button in settings. Your data will be removed within 30 days.",
        "format": "text",
        "country": "global"
    }
}'
// ViriSIM Audit Submission - JavaScript/Fetch
async function submitAudit(userInput, aiOutput) {
    const response = await fetch('https://analyzecompliance-vrbinbrbkq-uc.a.run.app', {
        method: 'POST',
        headers: {
            'X-API-Key': 'sk-viri-your-api-key-here',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            user_id: "user_12345",
            company_name: "Example Corp",
            use_case: "Customer Support",
            timestamp: new Date().toISOString(),
            your_company_user_id: "internal_user_001",
            your_company_user_session_id: "session_abc123",
            model_version: "gpt-4-turbo",
"your_company_signature": "MEUCIQDxK9cF8mN2vR5jH7sT3wB6dL0pA1qY4uW8eR2oG5tSJgIgV7kM3nB4cD5fG6hJ8kL0mN1pQ2rS3tU4vW5xY6zA7==",
"your_company_signing_key_id": "projects/customer-project-123/locations/europe-west3/keyRings/compliance-signing-ring/cryptoKeys/audit-signing-key/cryptoKeyVersions/1",
            input: {
                value: userInput,
                format: "text",
                country: "Germany"
            },
            output: {
                value: aiOutput,
                format: "text",
                country: "global"
            }
        })
    });
    
    const result = await response.json();
    
    if (response.ok) {
        console.log(` Audit submitted: ${result.submission_id}`);
        console.log(` View results at: I/O Logs in dashboard`);
    } else {
        console.error(` Error: ${result.error}`);
    }
    
    return result;
}

// Example call
submitAudit(
    "How do I delete my account?",
    "To delete your account, please click the 'Delete Account' button..."
);
import requests
from datetime import datetime

def submit_audit(user_input, ai_output):
    url = "https://analyzecompliance-vrbinbrbkq-uc.a.run.app"
    headers = {
        "X-API-Key": "sk-viri-your-api-key-here",
        "Content-Type": "application/json"
    }
    
    payload = {
        "user_id": "user_12345",
        "company_name": "Example Corp",
        "use_case": "Customer Support",
        "timestamp": datetime.now().isoformat(),
        "your_company_user_id": "internal_user_001",
        "your_company_user_session_id": "session_abc123",
        "model_version": "gpt-4-turbo",
"your_company_signature": "MEUCIQDxK9cF8mN2vR5jH7sT3wB6dL0pA1qY4uW8eR2oG5tSJgIgV7kM3nB4cD5fG6hJ8kL0mN1pQ2rS3tU4vW5xY6zA7==",
"your_company_signing_key_id": "projects/customer-project-123/locations/europe-west3/keyRings/compliance-signing-ring/cryptoKeys/audit-signing-key/cryptoKeyVersions/1",
        "input": {
            "value": user_input,
            "format": "text",
            "country": "Germany"
        },
        "output": {
            "value": ai_output,
            "format": "text",
            "country": "global"
        }
    }
    
    response = requests.post(url, json=payload, headers=headers)
    result = response.json()
    
    if response.ok:
        print(f" Audit submitted: {result['submission_id']}")
    else:
        print(f" Error: {result.get('error', 'Unknown error')}")
    
    return result

# Example
submit_audit(
    "How do I delete my account?",
    "To delete your account, please click the 'Delete Account' button..."
)

No Rate Limits: ViriSIM does not enforce rate limits on API calls. However, each audit consumes tokens from your purchased plan. Monitor your token usage in the dashboard under Analytics → Token Usage.

 Security Note: The examples above are for illustration only. Never hardcode API keys in your code. Use environment variables instead - e.g., process.env.VIRIDEED_API_KEY

Ready to Start Auditing?

Go to ViriSIM, get your API key and run your first compliance audit in under 30 minutes.

Go to ViriSIM