Skip to main content

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

https://your-chad-instance.com/api

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 in Authorization header:
curl -H "Authorization: Bearer chad_ak_xxxxx..." \
  https://chad.example.com/api/external/alerts
See API Keys for creating and managing keys.

External vs Internal API

EndpointAuthPurpose
/api/external/*API KeyExternal integrations (read-only)
/api/*JWTFull access (web UI)
External endpoints are rate-limited and read-only by default.

Request Format

Content Type

Content-Type: application/json

Request Body

JSON for POST/PUT/PATCH requests:
{
  "title": "My Rule",
  "yaml_content": "title: Example..."
}

Response Format

Success Response

{
  "id": "abc-123",
  "title": "My Rule",
  "status": "deployed",
  "created_at": "2024-01-15T14:32:17Z"
}

List Response

{
  "items": [...],
  "total": 100,
  "page": 1,
  "page_size": 20
}

Error Response

{
  "detail": "Rule not found",
  "status_code": 404
}

HTTP Status Codes

CodeMeaning
200Success
201Created
204No content (successful delete)
400Bad request (invalid input)
401Unauthorized (missing/invalid auth)
403Forbidden (insufficient permissions)
404Not found
422Validation error
429Rate limit exceeded
500Server error

Pagination

List endpoints support pagination:
GET /api/rules?page=1&page_size=20
Parameters:
ParameterDefaultMax
page1-
page_size20100
Response includes:
{
  "items": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "pages": 8
}

Filtering

List endpoints support filters via query parameters:
GET /api/alerts?status=new&severity=high
Common filters:
ParameterDescription
statusFilter by status
severityFilter by severity
created_afterFilter by date
created_beforeFilter by date
searchFull-text search

Sorting

GET /api/alerts?sort_by=created_at&sort_order=desc
ParameterOptions
sort_byField name
sort_orderasc or desc

Rate Limiting

API keys are rate-limited:
TierLimit
Standard60 requests/minute
High300 requests/minute
When exceeded:
HTTP/1.1 429 Too Many Requests
Retry-After: 30

CSRF Protection

State-changing requests require CSRF token:
  1. Get token from /api/auth/csrf
  2. Include in X-CSRF-Token header
API keys bypass CSRF (they’re already scoped).

Versioning

The API is currently unversioned. Breaking changes will be announced in advance.

OpenAPI Specification

Download the full OpenAPI spec:
GET /api/openapi.json
Use with Swagger UI, Postman, or code generators.

Common Patterns

Create Resource

POST /api/rules
Content-Type: application/json

{
  "title": "My Rule",
  "yaml_content": "..."
}

Update Resource

PUT /api/rules/{id}
Content-Type: application/json

{
  "title": "Updated Title"
}

Delete Resource

DELETE /api/rules/{id}

Bulk Operations

POST /api/rules/bulk/deploy
Content-Type: application/json

{
  "ids": ["abc-123", "def-456"]
}

SDK Libraries

Official SDKs coming soon. For now, use:
  • Python: requests or httpx
  • JavaScript: fetch or axios
  • Go: net/http

Next Steps