API Overview
CHAD provides a REST API for programmatic access to rules, alerts, and configuration. This API is used by the frontend and is available for external integrations.Base URL
Authentication
All API requests require authentication via one of:JWT Token (Browser Sessions)
Used by the web UI. Token in cookie after login.API Key (Programmatic Access)
Include inAuthorization header:
External vs Internal API
| Endpoint | Auth | Purpose |
|---|---|---|
/api/external/* | API Key | External integrations (read-only) |
/api/* | JWT | Full access (web UI) |
Request Format
Content Type
Request Body
JSON for POST/PUT/PATCH requests:Response Format
Success Response
List Response
Error Response
HTTP Status Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Created |
204 | No content (successful delete) |
400 | Bad request (invalid input) |
401 | Unauthorized (missing/invalid auth) |
403 | Forbidden (insufficient permissions) |
404 | Not found |
422 | Validation error |
429 | Rate limit exceeded |
500 | Server error |
Pagination
List endpoints support pagination:| Parameter | Default | Max |
|---|---|---|
page | 1 | - |
page_size | 20 | 100 |
Filtering
List endpoints support filters via query parameters:| Parameter | Description |
|---|---|
status | Filter by status |
severity | Filter by severity |
created_after | Filter by date |
created_before | Filter by date |
search | Full-text search |
Sorting
| Parameter | Options |
|---|---|
sort_by | Field name |
sort_order | asc or desc |
Rate Limiting
API keys are rate-limited:| Tier | Limit |
|---|---|
| Standard | 60 requests/minute |
| High | 300 requests/minute |
CSRF Protection
State-changing requests require CSRF token:- Get token from
/api/auth/csrf - Include in
X-CSRF-Tokenheader
Versioning
The API is currently unversioned. Breaking changes will be announced in advance.OpenAPI Specification
Download the full OpenAPI spec:Common Patterns
Create Resource
Update Resource
Delete Resource
Bulk Operations
SDK Libraries
Official SDKs coming soon. For now, use:- Python:
requestsorhttpx - JavaScript:
fetchoraxios - Go:
net/http