API Reference

Pestle provides a comprehensive REST API for integrating with your existing tools and automating workflows.

Authentication

API Tokens

Generate API tokens for programmatic access:

Go to Settings → API Tokens
Click Generate Token
Name the token (e.g., "CI/CD Integration")
Set expiration (optional)
Copy and securely store the token

Using Tokens

Include the token in the Authorization header:

curl -H "Authorization: Token your-api-token-here" \
     https://your-pestle-instance.com/api/v1/risks/

Base URL

https://your-pestle-instance.com/api/v1/

Common Endpoints

Risks

Method	Endpoint	Description
GET	/risks/	List all risks
POST	/risks/	Create a risk
GET	/risks/{id}/	Get risk details
PUT	/risks/{id}/	Update a risk
DELETE	/risks/{id}/	Delete a risk

Controls

Method	Endpoint	Description
GET	/applied-controls/	List controls
POST	/applied-controls/	Create a control
GET	/applied-controls/{id}/	Get control details
PUT	/applied-controls/{id}/	Update a control

Assessments

Method	Endpoint	Description
GET	/compliance-assessments/	List assessments
POST	/compliance-assessments/	Create assessment
GET	/compliance-assessments/{id}/	Get assessment

Filtering & Pagination

Query Parameters

# Pagination
GET /api/v1/risks/?page=1&page_size=25

# Filtering
GET /api/v1/risks/?status=open&severity=high

# Ordering
GET /api/v1/risks/?ordering=-created_at

# Search
GET /api/v1/risks/?search=data%20breach

Response Format

{
  "count": 150,
  "next": "https://pestle.com/api/v1/risks/?page=2",
  "previous": null,
  "results": [
    {
      "id": "uuid-here",
      "name": "Data Breach Risk",
      "description": "...",
      "status": "open",
      "likelihood": 3,
      "impact": 4,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Creating Resources

Example: Create a Risk

curl -X POST https://pestle.com/api/v1/risks/ \
  -H "Authorization: Token your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Third-Party Data Breach",
    "description": "Risk of data exposure through vendor systems",
    "folder": "folder-uuid",
    "likelihood": 3,
    "impact": 4,
    "treatment": "mitigate"
  }'

Webhooks

Receive notifications when events occur:

Configuring Webhooks

Go to Settings → Webhooks
Click Add Webhook
Enter your endpoint URL
Select events to subscribe to
Save and test

Available Events

risk.created, risk.updated, risk.deleted
control.created, control.updated
assessment.completed
task.overdue

Rate Limits

Standard: 1000 requests per hour
Burst: 100 requests per minute

Rate limit headers included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705320000

Error Handling

# 400 Bad Request
{"error": "validation_error", "details": {"name": ["This field is required."]}}

# 401 Unauthorized
{"error": "authentication_failed", "message": "Invalid or expired token"}

# 403 Forbidden
{"error": "permission_denied", "message": "You do not have access to this resource"}

# 404 Not Found
{"error": "not_found", "message": "Resource not found"}

# 429 Rate Limited
{"error": "rate_limited", "message": "Too many requests", "retry_after": 60}

SDKs & Libraries

Official client libraries coming soon. For now, use standard HTTP clients:

Python: requests or httpx
JavaScript: fetch or axios
Go: net/http