> ## Documentation Index
> Fetch the complete documentation index at: https://trilletai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Best Practices

> Guidelines for integrating with Trillet AI API

## Authentication

### API Keys

* Keep your API keys secure and never expose them in client-side code
* Use different API keys for development and production
* Rotate your API keys periodically
* Monitor your API key usage for suspicious activity

```bash theme={null}
# API Key format
xxxxxxxxxxxxxxxxxxx
```

## Error Handling

Implement proper error handling for API responses:

```bash theme={null}
curl -X POST https://api.trillet.ai/api/v1/calls/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123",
    "toNumber": "+1234567890"
  }'
```

Common error responses:

```json theme={null}
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has insufficient credits"
  }
}
```

```json theme={null}
{
  "error": {
    "code": "invalid_number",
    "message": "The provided phone number is invalid"
  }
}
```

## Rate Limits

* Production API keys are limited to 60 requests per minute
* Implement backoff when you hit rate limits
* Monitor your API usage in the dashboard

Rate limit response:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again in 60 seconds.",
    "reset_at": "2024-01-22T15:30:00Z"
  }
}
```

## Webhooks \[Coming Soon!]

### Configuring Webhooks

1. Add your webhook URL in the dashboard
2. Configure the events you want to receive
3. Store your webhook secret securely

### Verifying Webhooks

Always verify webhook signatures using the `X-Trillet-Signature` header:

```bash theme={null}
# Your webhook secret from the dashboard
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# Verify the signature before processing webhooks
echo -n "$PAYLOAD" | openssl sha256 -hmac "$WEBHOOK_SECRET"
```

### Webhook Events

* `call.started` - When a call begins
* `call.completed` - When a call ends
* `call.failed` - When a call fails
* `sms.sent` - When an SMS is sent
* `sms.delivered` - When an SMS is delivered

Example webhook payload:

```json theme={null}
{
  "event": "call.completed",
  "data": {
    "callId": "call_xyz789",
    "agentId": "agent_123abc",
    "duration": 125,
    "status": "completed"
  }
}
```

## Production Checklist

1. **Authentication**
   * Use production API keys
   * Implement key rotation
   * Secure key storage

2. **Error Handling**
   * Handle all error codes
   * Implement retry logic
   * Log errors appropriately

3. **Monitoring**
   * Track API response times
   * Monitor error rates
   * Set up alerts

4. **Webhooks**
   * Use HTTPS endpoints
   * Verify signatures
   * Implement retry logic
   * Handle duplicate events

## Need Help?

<CardGroup cols={2}>
  <Card title="API Status [Coming Soon!]" icon="signal">
    Check our API status and uptime
  </Card>

  <Card title="Support" icon="headset" href="mailto:support@trillet.ai">
    Get technical support
  </Card>
</CardGroup>