Skip to main content
POST
/
api
/
risk
/
v1
/
generate-risk-with-context
curl -X POST 'https://app.orcho.ai/risk/api/v1/generate-risk-with-context' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Refactor the authentication middleware to support JWT tokens",
    "context": {
      "repo_full_name": "company/api-gateway",
      "current_file": "middleware/auth.py",
      "other_files": [
        "middleware/jwt_validator.py",
        "config/auth_settings.py",
        "tests/test_auth.py"
      ]
    },
    "weights": {
      "data_sensitivity": 0.25,
      "input_clarity": 0.35,
      "blast_radius": 0.40
    }
  }'
{
  "success": true,
  "timestamp": "2025-01-08T15:45:00Z",
  "prompt": "Refactor the authentication middleware to support JWT tokens",
  "current_file": "middleware/auth.py",
  "repo_full_name": "company/api-gateway",
  "overall_score": 0.5230,
  "overall_risk_level": "high",
  "recommendations": [
    "REVIEW_REQUIRED - Significant risk factors present"
  ],
  "scores": {
    "data_sensitivity": 0.45,
    "input_clarity": 0.35,
    "blast_radius": 0.72
  },
  "computations": {
    "data_sensitivity": {
      "score": 0.45,
      "risk_level": "medium",
      "reasoning": "Authentication middleware handles sensitive user credentials and session data",
      "evidence": ["Password handling", "Session tokens", "User authentication"]
    },
    "input_clarity": {
      "score": 0.35,
      "suggestions": [
        "Specify JWT library to use",
        "Define migration strategy",
        "Address backward compatibility"
      ]
    },
    "blast_radius": {
      "score": 0.72
    }
  },
  "weights": {
    "data_sensitivity": 0.10,
    "input_clarity": 0.25,
    "blast_radius": 0.65
  },
  "original_weights": {
    "data_sensitivity": 0.20,
    "input_clarity": 0.40,
    "blast_radius": 0.40
  }
}
Generate a comprehensive risk assessment that includes code context, dependency analysis, and blast radius calculations. This endpoint provides the most accurate risk scoring by analyzing how changes might impact your entire codebase.

Use Cases

Use this endpoint when you need to:
  • Assess risk of code changes before execution
  • Calculate blast radius of modifications
  • Analyze impact across file dependencies
  • Evaluate context complexity for AI tasks
  • Get comprehensive risk analysis for production deployments

Authentication

Authorization
string
required
Bearer token for API authentication. Format: Bearer YOUR_API_KEY

Request Body

prompt
string
required
The AI prompt or task description to assess for risk.Example: "Add error handling to the payment processing function"
context
object
required
Code context information for dependency and impact analysis.
weights
object
Optional custom weights for each risk factor. All weights should sum to 1.0. Weights are subject to your implementation requirements.
If some risk factors cannot be computed, the API automatically redistributes weights among available factors. The response includes both weights (actual used) and original_weights (your provided values).

Response

success
boolean
required
Indicates whether the request was successful
timestamp
string
required
ISO 8601 formatted timestamp of when the assessment was performed
overall_score
number
required
Aggregate risk score from 0.0 to 1.0 (decimal), where higher values indicate greater risk. Example: 0.65 means high risk.
overall_risk_level
string
required
Risk classification: "minimal", "low", "medium", "high", or "critical"
  • "minimal": score < 0.2
  • "low": 0.2 ≤ score < 0.4
  • "medium": 0.4 ≤ score < 0.6
  • "high": 0.6 ≤ score < 0.8
  • "critical": score ≥ 0.8
recommendations
array
required
List of action recommendations 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"
scores
object
required
Individual risk factor scores (0.0-1.0). Only includes successfully computed factors.
Unavailable risk factors are not included in the scores object. Check unavailable_parameters for details on why factors were omitted.
computations
object
required
Detailed computation results for each risk factor including reasoning, evidence, and metrics
weights
object
required
The actual weights used in calculation after any automatic redistribution. May differ from original_weights if some factors were unavailable.
When factors are unavailable, weights are redistributed:
  • 1 factor: gets 100%
  • 2 factors: 65% and 35%
  • 3 factors: 65%, 25%, and 10%
original_weights
object
required
The weights you provided (or defaults) before any redistribution. Use this to compare against weights to see if redistribution occurred.
prompt
string
required
Echo of the original prompt that was assessed
current_file
string
required
The file being modified
repo_full_name
string
required
The repository containing the file
available_parameters
array
List of parameter names that were successfully computed and included in the weighted score. Only present if some parameters were unavailable.
unavailable_parameters
object
Map of parameter names to reason strings explaining why they couldn’t be computed. Only present if some parameters were unavailable.Example: {"context_complexity": "module not available"}
curl -X POST 'https://app.orcho.ai/risk/api/v1/generate-risk-with-context' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Refactor the authentication middleware to support JWT tokens",
    "context": {
      "repo_full_name": "company/api-gateway",
      "current_file": "middleware/auth.py",
      "other_files": [
        "middleware/jwt_validator.py",
        "config/auth_settings.py",
        "tests/test_auth.py"
      ]
    },
    "weights": {
      "data_sensitivity": 0.25,
      "input_clarity": 0.35,
      "blast_radius": 0.40
    }
  }'
{
  "success": true,
  "timestamp": "2025-01-08T15:45:00Z",
  "prompt": "Refactor the authentication middleware to support JWT tokens",
  "current_file": "middleware/auth.py",
  "repo_full_name": "company/api-gateway",
  "overall_score": 0.5230,
  "overall_risk_level": "high",
  "recommendations": [
    "REVIEW_REQUIRED - Significant risk factors present"
  ],
  "scores": {
    "data_sensitivity": 0.45,
    "input_clarity": 0.35,
    "blast_radius": 0.72
  },
  "computations": {
    "data_sensitivity": {
      "score": 0.45,
      "risk_level": "medium",
      "reasoning": "Authentication middleware handles sensitive user credentials and session data",
      "evidence": ["Password handling", "Session tokens", "User authentication"]
    },
    "input_clarity": {
      "score": 0.35,
      "suggestions": [
        "Specify JWT library to use",
        "Define migration strategy",
        "Address backward compatibility"
      ]
    },
    "blast_radius": {
      "score": 0.72
    }
  },
  "weights": {
    "data_sensitivity": 0.10,
    "input_clarity": 0.25,
    "blast_radius": 0.65
  },
  "original_weights": {
    "data_sensitivity": 0.20,
    "input_clarity": 0.40,
    "blast_radius": 0.40
  }
}

Dependency Graph Requirements

This endpoint relies on dependency graph data to calculate blast radius. The dependency graph must be pre-loaded into the database for your repository.
If your repository’s dependency graph is not available, the API will still function but blast_radius calculations may be limited. Contact support to set up dependency graph generation for your repositories.

Blast Radius Calculation

Blast radius measures how many parts of your codebase could be affected by changes to the target file:
1

Identify direct dependencies

Find all files that directly import or depend on the current file
2

Traverse dependency chain

Follow dependencies recursively to identify indirect impacts
3

Calculate affected scope

Count total affected files and measure dependency depth
4

Generate risk score

Higher affected file counts and deeper dependency chains result in higher blast radius scores

Best Practices

Use this endpoint for any code-related risk assessment:
  • Pre-commit checks: Assess changes before committing
  • Pull request validation: Evaluate PR impact automatically
  • CI/CD pipelines: Gate deployments based on risk scores
  • Code review assistance: Help reviewers prioritize high-risk changes
  • Production deployments: Require approval for high-risk changes
For non-code prompts, use the simpler Generate Risk endpoint.
Better context leads to more accurate risk assessments:
  • Always specify the repository: Use exact owner/repo format
  • Include related files: Add configuration, test, and dependent files to other_files
  • Keep files relevant: Only include files that provide meaningful context
  • Update dependency graphs regularly: Ensure your repository’s dependency graph is current
Example of good context:
{
  "repo_full_name": "mycompany/payment-api",
  "current_file": "src/billing/processor.py",
  "other_files": [
    "src/billing/config.py",
    "src/billing/models.py",
    "tests/test_billing.py"
  ]
}
Blast radius scores indicate potential impact on a 0.0-1.0 scale:
  • 0.0 - 0.2: Isolated changes with minimal dependencies
  • 0.21 - 0.4: Moderate impact on related components
  • 0.41 - 0.6: Significant impact across multiple modules
  • 0.61 - 0.8: High impact on core functionality
  • 0.81 - 1.0: Critical changes affecting major systems
The blast radius score is the criticality score of the most critical file being modified. Higher scores indicate files that are heavily depended upon by other parts of the codebase.
Adjust weights based on your risk tolerance and priorities. Weights are subject to your implementation requirements.High-risk production systems:
{
  "blast_radius": 0.35,
  "data_sensitivity": 0.25,
  "input_clarity": 0.15,
  "context_complexity": 0.15,
  "legal_ip_risk": 0.05,
  "model_hallucination": 0.05
}
Experimental features:
{
  "input_clarity": 0.30,
  "model_hallucination": 0.25,
  "blast_radius": 0.20,
  "data_sensitivity": 0.15,
  "context_complexity": 0.10,
  "legal_ip_risk": 0.00
}
Security-focused:
{
  "data_sensitivity": 0.40,
  "legal_ip_risk": 0.25,
  "blast_radius": 0.20,
  "input_clarity": 0.10,
  "model_hallucination": 0.05,
  "context_complexity": 0.00
}
When you receive high-risk scores (≥ 0.6):
  1. Review recommendations: Check the recommendations field for the risk level assessment
  2. Consider manual review: High scores (0.6-0.79) and critical scores (≥ 0.8) warrant human oversight
  3. Implement safeguards: Add feature flags, canary deployments, or rollback procedures
  4. Break down changes: Split large changes into smaller, lower-risk modifications
  5. Improve context: Provide more detailed prompts and additional context files
Never ignore high-risk scores (≥ 0.6) in production environments.

Integration Examples

pre-commit-hook.py
#!/usr/bin/env python3
import sys
import requests
import subprocess

def get_changed_files():
    result = subprocess.run(
        ['git', 'diff', '--cached', '--name-only'],
        capture_output=True,
        text=True
    )
    return result.stdout.strip().split('\n')

def assess_risk(file_path, prompt):
    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': prompt,
            'context': {
                'repo_full_name': 'mycompany/myrepo',
                'current_file': file_path
            }
        }
    )
    return response.json()

# Check each changed file
for file_path in get_changed_files():
    result = assess_risk(file_path, f'Modifying {file_path}')
    
    if result['overall_score'] > 0.75:
        print(f'HIGH RISK: {file_path} (score: {result["overall_score"]:.2f})')
        print('Recommendations:')
        for rec in result['recommendations']:
            print(f'  - {rec}')
        sys.exit(1)  # Block commit

sys.exit(0)  # Allow commit

Rate Limiting

This endpoint is subject to rate limiting. Dependency graph queries add processing overhead, so limits may be lower than the prompt-only endpoint.
Rate limit: 60 requests per minute per API key. For higher limits or batch processing, contact [email protected].