Skip to main content
POST
/
risk
/
api
/
v1
/
generate-risk
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": "Update the database schema to add a new user_email field and migrate existing data",
    "weights": {
      "data_sensitivity": 0.25,
      "input_clarity": 0.35,
      "blast_radius": 0.40
    }
  }'

{
  "success": true,
  "timestamp": "2025-01-08T15:30:00Z",
  "prompt": "Update the database schema to add a new user_email field and migrate existing data",
  "current_file": null,
  "overall_score": 0.2850,
  "overall_risk_level": "low",
  "recommendations": [
    "MONITOR - Low risk"
  ],
  "scores": {
    "data_sensitivity": 0.35,
    "input_clarity": 0.42
  },
  "computations": {
    "data_sensitivity": {
      "score": 0.35,
      "risk_level": "low",
      "reasoning": "Prompt mentions user data (email) which is PII",
      "evidence": ["user_email field", "existing data migration"]
    },
    "input_clarity": {
      "score": 0.42,
      "suggestions": [
        "Specify which database and table",
        "Clarify migration strategy",
        "Add rollback procedures"
      ]
    },
    "blast_radius": {
      "error": "current_file and dependency_graph required"
    }
  },
  "weights": {
    "data_sensitivity": 0.35,
    "input_clarity": 0.65
  },
  "original_weights": {
    "data_sensitivity": 0.20,
    "input_clarity": 0.40,
    "blast_radius": 0.40
  },
  "unavailable_parameters": {
    "blast_radius": "current_file and dependency_graph required"
  },
  "available_parameters": [
    "data_sensitivity",
    "input_clarity"
  ]
}
Generate a risk assessment based on prompt text only. This endpoint analyzes the prompt for data sensitivity and input clarity without requiring code context or dependency information.

​
Use Cases

Use this endpoint when you need to:
  • Quickly assess prompt safety before execution
  • Evaluate prompts that don’t involve code changes
  • Screen for sensitive data in user inputs
  • Validate prompt completeness and clarity

​
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: "Deploy the updated payment processing code to production"
​
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, with the highest risk factor holding the heighest weight. 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 may include error messages for failed computations.
​
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 | null
Always null for this endpoint (context not provided)
​
repo_full_name
string | null
Always null for this endpoint (context not provided)
​
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: {"blast_radius": "current_file and dependency_graph required"}
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": "Update the database schema to add a new user_email field and migrate existing data",
    "weights": {
      "data_sensitivity": 0.25,
      "input_clarity": 0.35,
      "blast_radius": 0.40
    }
  }'

{
  "success": true,
  "timestamp": "2025-01-08T15:30:00Z",
  "prompt": "Update the database schema to add a new user_email field and migrate existing data",
  "current_file": null,
  "overall_score": 0.2850,
  "overall_risk_level": "low",
  "recommendations": [
    "MONITOR - Low risk"
  ],
  "scores": {
    "data_sensitivity": 0.35,
    "input_clarity": 0.42
  },
  "computations": {
    "data_sensitivity": {
      "score": 0.35,
      "risk_level": "low",
      "reasoning": "Prompt mentions user data (email) which is PII",
      "evidence": ["user_email field", "existing data migration"]
    },
    "input_clarity": {
      "score": 0.42,
      "suggestions": [
        "Specify which database and table",
        "Clarify migration strategy",
        "Add rollback procedures"
      ]
    },
    "blast_radius": {
      "error": "current_file and dependency_graph required"
    }
  },
  "weights": {
    "data_sensitivity": 0.35,
    "input_clarity": 0.65
  },
  "original_weights": {
    "data_sensitivity": 0.20,
    "input_clarity": 0.40,
    "blast_radius": 0.40
  },
  "unavailable_parameters": {
    "blast_radius": "current_file and dependency_graph required"
  },
  "available_parameters": [
    "data_sensitivity",
    "input_clarity"
  ]
}

​
Best Practices

This endpoint is ideal for quick risk assessments when you don’t have code context available. Use it for:
  • Screening user-submitted prompts
  • Validating prompts before sending to AI models
  • Quick safety checks in interactive applications
  • Batch processing of prompt libraries
For more accurate assessments involving code changes, use the Generate Risk with Context endpoint instead.
Risk scores are weighted averages of individual risk factors on a 0.0-1.0 scale:
  • < 0.2: Minimal risk - safe to proceed automatically
  • 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 - block execution
When context is not provided:
  • blast_radius will be unavailable and excluded from scores
  • Weights are automatically redistributed among available factors
  • Check available_parameters and unavailable_parameters in the response
The overall score focuses on available risk factors. Always review the recommendations field for specific actions.
Adjust weights based on your use case and risk tolerance. Weights are subject to your implementation requirements.Customize for specific scenarios:
  • High-security applications: Increase data_sensitivity weight (e.g., 0.4-0.5)
  • Production systems with dependencies: Increase blast_radius weight (e.g., 0.5)
  • Unclear prompts common: Increase input_clarity weight (e.g., 0.5)
  • Complex contexts: Increase context_complexity weight
  • Legal-sensitive domains: Increase legal_ip_risk weight
Ensure all weights sum to 1.0. If unavailable factors have weights, the API redistributes automatically:
  • 1 available: Gets 100%
  • 2 available: 65% and 35% (by original weight ranking)
  • 3 available: 65%, 25%, and 10% (by original weight ranking)
Always check the success field before processing results:
if result['success']:
    risk_score = result['overall_score']
    recommendations = result['recommendations']
else:
    error_message = result['error']
    # Handle error appropriately
Common errors include missing API keys, empty prompts, and invalid weight configurations.

​
Rate Limiting

This endpoint is subject to rate limiting. If you need to process high volumes of prompts, consider:
  • Batching requests during off-peak hours
  • Implementing exponential backoff for retries
  • Contacting support for higher rate limits
Rate limit: 100 requests per minute per API key. Exceeding this limit results in HTTP 429 responses.