API Version: v1
Authentication
Secure your API requests with API keys.
API Keys
All API requests require authentication using an API key. You can create and manage your API keys in the API Console.
Keep your API keys secure
Never expose your API key in client-side code or commit it to version control.
Using API Keys
Include your API key in the Authorization header with the Bearer prefix:
curl -X POST "https://api.orchestraight.com/v1/generate" \
-H "Authorization: Bearer sk_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"content_type": "cold_email", "context": {...}}'Best Practices
Use Environment Variables
Store your API key in environment variables, not in your code.
# .env file
ORCHESTRAIGHT_API_KEY=sk_live_your_api_key_hereimport Orchestraight from "@orchestraightbd/orchestraight";
// The SDK automatically reads from ORCHESTRAIGHT_API_KEY
const client = new Orchestraight();
// Or pass it explicitly
const client = new Orchestraight({
apiKey: process.env.ORCHESTRAIGHT_API_KEY,
});Rotate Keys Regularly
Create new API keys periodically and revoke old ones. You can have multiple active keys to enable zero-downtime rotation.
Use Separate Keys for Environments
Use different API keys for development, staging, and production environments. This limits the blast radius if a key is compromised.
Never Commit Keys to Git
Add .env to your .gitignore file. Use secret management tools like HashiCorp Vault or AWS Secrets Manager for production.
Rate Limiting
API requests are rate limited based on your subscription plan. Rate limit headers are included in every response:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests per minute |
| X-RateLimit-Remaining | Requests remaining in current window |
| X-RateLimit-Reset | Unix timestamp when the limit resets |
Error Responses
Authentication errors return standard HTTP status codes:
400 Bad Request
The request body failed validation. Check the details array for specifics.
{
"error": "Validation Error",
"message": "Invalid input: expected object, received undefined",
"code": "validation_error",
"details": [
{ "path": "context", "message": "Invalid input: expected object, received undefined" }
]
}401 Unauthorized
The API key is missing or invalid.
{
"error": "Unauthorized",
"message": "Invalid or missing API key. Include a valid key in the Authorization header: Bearer <your-api-key>",
"code": "unauthorized"
}402 Payment Required
Your organization doesn't have enough credits for this request.
{
"error": "Insufficient API credits",
"message": "Your organization has 0 credits available. This request requires 85 credit(s).",
"code": "insufficient_credits",
"current_balance": 0,
"required_credits": 85,
"billing_url": "https://app.orchestraight.com/console/billing"
}429 Too Many Requests
You've exceeded the rate limit of 1,200 requests per minute. Wait before retrying.
{
"error": "Rate limit exceeded",
"message": "You have exceeded your rate limit of 1200 requests per minute. Please wait before retrying.",
"code": "rate_limit_exceeded",
"limit": 1200,
"period": 60,
"retry_after": 45
}