Skip to main content
Get up and running with the Orcho Risk Generation API quickly. This guide will walk you through authentication, your first API call, and interpreting results.

Prerequisites

Before you begin, make sure you have:
  • An Orcho API account
  • Your API key (available in your dashboard)
  • Basic knowledge of REST APIs
Don’t have an API key yet? Sign up at orcho.ai to get started.

Step 1: Get Your API Key

1

Sign in to your dashboard

Navigate to companyName.orcho.ai and sign in with your credentials.
2

Generate API key

Go to Settings → API Keys and click “Create New Key”. Store this key securely.
Your API key provides access to your account. Never share it publicly or commit it to version control.
3

Test your key

Verify your key works by calling the health check endpoint:
curl https://app.orcho.ai/health \
  -H 'Authorization: Bearer YOUR_API_KEY'
You should receive a response with "status": "healthy"

Step 2: Make Your First Request

Let’s assess a simple prompt to see the API in action.
curl -X POST 'https://app.orcho.ai/risk/api/v1/generate-risk' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Delete all records from the users table"
  }'
You should see a high-risk response due to the dangerous nature of the prompt:
{
  "success": true,
  "timestamp": "2025-01-08T15:30:00Z",
  "overall_score": 0.8950,
  "overall_risk_level": "critical",
  "recommendations": [
    "BLOCK - High risk detected"
  ],
  "weights": {
    "data_sensitivity": 0.20,
    "input_clarity": 0.40,
    "blast_radius": 0.40
  },
  "scores": {
    "data_sensitivity": 0.85,
    "input_clarity": 0.92
  },
  "computations": {
    "data_sensitivity": {
      "score": 0.85,
      "risk_level": "high"
    },
    "input_clarity": {
      "score": 0.92,
      "suggestions": ["Add WHERE clause", "Require confirmation"]
    }
  }
}

Step 3: Understanding the Response

The API returns several key fields:
The aggregate risk score combining all risk factors. Decimal value where higher scores indicate greater risk.
  • < 0.2: Minimal risk - safe to proceed
  • 0.2 - 0.39: Low risk - monitor
  • 0.4 - 0.59: Medium risk - review recommended
  • 0.6 - 0.79: High risk - review required
  • ≥ 0.8: Critical risk - manual intervention needed
Scores are decimal values (0.0 to 1.0), not percentages. A score of 0.65 means high risk.
A categorical risk level for quick decision making:
  • "minimal" - Very low risk (< 0.2)
  • "low" - Low risk (0.2 - 0.39)
  • "medium" - Moderate risk (0.4 - 0.59)
  • "high" - Significant risk (0.6 - 0.79)
  • "critical" - Critical risk (≥ 0.8)
An array of simple action strings based on risk level:
  • "SAFE - Minimal risk"
  • "MONITOR - Low risk"
  • "REVIEW_RECOMMENDED - Some risk factors detected"
  • "REVIEW_REQUIRED - Significant risk factors present"
  • "BLOCK - High risk detected"
Individual scores for each risk factor (all 0.0-1.0 decimal values):
  • data_sensitivity - Presence of PII, credentials, or sensitive data
  • input_clarity - Completeness and clarity of the prompt
  • blast_radius - Impact scope (only when context provided)
Only successfully computed risk factors appear in scores. Unavailable factors are omitted.
The actual weights used in calculation after any redistribution. The API automatically redistributes weights when some risk factors are unavailable:
  • 1 available factor: Gets 100%
  • 2 available factors: Largest gets 65%, second gets 35%
  • 3 available factors: Largest 65%, second 25%, smallest 10%
Check original_weights in the response to see the weights you provided before redistribution.
Detailed results from each risk factor computation including reasoning and evidence.

Step 4: Try a Code Assessment

For more accurate assessments of code changes, use the context endpoint:
import requests
import os

API_KEY = os.environ.get('ORCHO_API_KEY')

response = requests.post(
    'https://app.orcho.ai/risk/api/v1/generate-risk-with-context',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'prompt': 'Add rate limiting to the API endpoints',
        'context': {
            'repo_full_name': 'mycompany/api-server',
            'current_file': 'src/middleware/rate_limiter.py',
            'other_files': [
                'src/config/limits.py',
                'tests/test_rate_limiting.py'
            ]
        }
    }
)

result = response.json()

# Display results
print(f"Risk Score: {result['overall_score']}")
print(f"Risk Level: {result['overall_risk_level']}")
print(f"\nRecommendations:")
for rec in result['recommendations']:
    print(f"  - {rec}")

# Check blast radius
if 'blast_radius' in result['scores']:
    print(f"\nBlast Radius Score: {result['scores']['blast_radius']}")
    if 'affected_files' in result['computations']['blast_radius']:
        files = result['computations']['blast_radius']['affected_files']
        print(f"Affected Files: {files}")

Step 5: Implement Decision Logic

Use the risk scores to make automated decisions:
def should_proceed(risk_score):
    """Basic threshold-based decision"""
    if risk_score < 0.2:
        return True, "Automatically approved - minimal risk"
    elif risk_score < 0.4:
        return True, "Approved with monitoring - low risk"
    elif risk_score < 0.6:
        return False, "Requires review - medium risk"
    elif risk_score < 0.8:
        return False, "Review required - high risk"
    else:
        return False, "Blocked - critical risk"

result = assess_risk(prompt)
approved, reason = should_proceed(result['overall_score'])

if approved:
    execute_task()
else:
    request_manual_review(reason)

Common Use Cases

Next Steps

1

Explore the API reference

Learn about all available endpoints and parameters in the API Reference.
2

Set up dependency graphs

Configure dependency graphs for your repositories to enable blast radius calculations. Contact support for setup assistance.
3

Customize risk weights

Adjust risk factor weights based on your specific use case and risk tolerance. See Generate Risk Score for details.
4

Integrate with your workflow

Add risk assessment to your CI/CD pipeline, pre-commit hooks, or code review process.

Best Practices

Store API keys securely: Use environment variables or secure secret management systems. Never commit keys to version control.
Start with low-risk tests: Test the API with non-production prompts first to understand the scoring before integrating into critical workflows.
Review recommendations: The recommendations array provides actionable steps. Don’t just look at the score—implement the suggestions.
Adjust thresholds: Different environments and use cases require different risk tolerances. Start conservative and adjust based on experience.
Monitor and iterate: Track risk scores over time to identify patterns and refine your risk management strategy.

Troubleshooting

Check that your API key is valid and properly formatted in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Make sure there’s a space after “Bearer” and no extra characters.
For the context endpoint, ensure:
  • The repository name is in owner/repo format
  • The repository’s dependency graph has been loaded
  • You have access to the repository
Contact support to set up dependency graphs for new repositories.
If you hit rate limits:
  • Implement exponential backoff in your retry logic
  • Batch requests during off-peak hours
  • Contact support for higher rate limits
If scores seem off:
  • Verify you’re providing complete context for code assessments
  • Check that custom weights sum to 1.0
  • Review the computations object for detailed scoring rationale
  • Ensure prompts are clear and complete

Support

Need help getting started?