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.
3
Test your key
Verify your key works by calling the health check endpoint:
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.Step 3: Understanding the Response
The API returns several key fields:overall_score (0.0-1.0)
overall_score (0.0-1.0)
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.
overall_risk_level
overall_risk_level
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)
recommendations
recommendations
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"
scores
scores
Individual scores for each risk factor (all 0.0-1.0 decimal values):
data_sensitivity- Presence of PII, credentials, or sensitive datainput_clarity- Completeness and clarity of the promptblast_radius- Impact scope (only when context provided)
Only successfully computed risk factors appear in scores. Unavailable factors are omitted.
weights
weights
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.computations
computations
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:Step 5: Implement Decision Logic
Use the risk scores to make automated decisions:- Simple Threshold
- Multi-factor Decision
- Environment-based
Common Use Cases
Pre-commit Validation
Check code changes before commits
CI/CD Gating
Automated deployment risk checks
Prompt Screening
Validate AI prompts before execution
Code Review Assist
Prioritize high-risk pull requests
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
Troubleshooting
401 Unauthorized Error
401 Unauthorized Error
Repository Not Found
Repository Not Found
For the context endpoint, ensure:
- The repository name is in
owner/repoformat - The repository’s dependency graph has been loaded
- You have access to the repository
Rate Limit Exceeded
Rate Limit Exceeded
If you hit rate limits:
- Implement exponential backoff in your retry logic
- Batch requests during off-peak hours
- Contact support for higher rate limits
Unexpected Risk Scores
Unexpected Risk Scores
If scores seem off:
- Verify you’re providing complete context for code assessments
- Check that custom weights sum to 1.0
- Review the
computationsobject for detailed scoring rationale - Ensure prompts are clear and complete