Documentation for a production-facing civic intelligence API.

Introduction

The Civic Sentinel API is a predictable, versioned REST interface. Every request is made over HTTPS, every response is JSON, and every resource is namespaced under a version prefix so your integration never breaks unexpectedly.

Quick start

Go from zero to your first authenticated request in four steps.

# Exchange key credentials for a bearer token
curl https://api.civicsentinel.io/v1/developer-token/ \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"api_key":"csk_…","api_secret":"css_…"}'

# Use response.data.access on API calls
curl https://api.civicsentinel.io/v1/profile/ \
  -H "Authorization: Bearer $CIVIC_SENTINEL_TOKEN"

Authentication

Integrations exchange a public key + secret pair for a signed, short-lived JWT bearer token. The public key (csk_…) identifies the application; the secret (css_…) proves ownership. API calls then use only the bearer token until it expires.

# 1. Exchange credentials
curl https://api.civicsentinel.io/v1/developer-token/ \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"api_key":"csk_…","api_secret":"css_…"}'

# 2. Call the API with the returned access token
curl https://api.civicsentinel.io/v1/alert-destinations/ \
  -H "Authorization: Bearer $CIVIC_SENTINEL_TOKEN" \
  -H "Content-Type: application/json"

The dashboard also authenticates with JWT bearer tokens (Authorization: Bearer …). Developer tokens carry the application id and scopes so most API requests do not need to re-check the API key secret.

Python SDK

# Install the SDK
pip install civicsentinel

# Install with MCP server support
pip install "civicsentinel[mcp]"

from civicsentinel import CivicSentinelClient

client = CivicSentinelClient(
    api_key="csk_…",
    api_secret="css_…",
)

countries = client.list_supported_countries()
usage = client.get_usage()
destinations = client.list_alert_destinations()

# Run the MCP server
export CIVIC_SENTINEL_API_KEY="csk_…"
export CIVIC_SENTINEL_API_SECRET="css_…"
civicsentinel-mcp

API keys & scopes

Each key is scoped to the minimum access it needs. Keys can be revoked and rotated at any time without downtime — issue a new key, deploy it, then revoke the old one. Keys belong to applications; per-day API quota is enforced per application, so spreading traffic across more apps does not give you more headroom unless your plan also raises the per-app limit.

Endpoints

Core endpoints grouped by resource. Every endpoint requires the scope listed alongside it — a key without that scope receives a 403. Public endpoints (/v1/usage/, /v1/pricing-plans/) accept developer bearer tokens; the token-exchange endpoint accepts the API key pair.

Requests & responses

Send JSON request bodies with a Content-Type: application/json header. Every response is wrapped in a consistent envelope so clients can branch on erc before reading the payload:

POST /v1/alert-destinations/

{
  "label": "Ops channel",
  "channel": "email",
  "identifier": "ops@example.org"
}

{
  "erc": 1,
  "msg": "success",
  "total": 1,
  "next": null,
  "data": {
    "id": "d_8fa2",
    "label": "Ops channel",
    "status": "pending"
  },
  "meta": { "usage": { … } }
}

Pagination

List endpoints are paginated. Pass page and page_size as query parameters. The envelope's top-level total and next fields give you the page count + cursor; the array of rows lives in data.

GET /v1/alert-dispatches/?page=2&page_size=50

{
  "erc": 1,
  "msg": "success",
  "total": 142,
  "next": "…/v1/alert-dispatches/?page=3",
  "data": [ … ]
}

Quotas & usage

Civic Sentinel meters two things per plan: per-app API requests (counted from 00:00 UTC) and alerts delivered per day. Plans also cap how many applications and WhatsApp destinations you can register.

There are three ways to read your live quota — pick whichever fits your integration. All three return the same numbers.

{
  "erc": 1,
  "msg": "success",
  "data": { … },
  "meta": {
    "usage": {
      "plan": "signal",
      "plan_name": "Signal",
      "application_id": "a22c247a-…",
      "application_name": "Election Insights",
      "limit_per_day": 30,
      "used_today": 8,
      "remaining_today": 22,
      "resets_at": "2026-05-17T00:00:00+00:00"
    }
  }
}

curl https://api.civicsentinel.io/v1/usage/ \
  -H "Authorization: Bearer $CIVIC_SENTINEL_TOKEN"

# response.data
{
  "plan": { "slug": "signal", "name": "Signal", "price_coins": 10 },
  "limits": { "max_apps": 5, "max_api_requests_per_app_per_day": 30, … },
  "today": { "alerts_used": 3, "resets_at": "2026-05-17T00:00:00+00:00"},
  "applications": [ { … } ]
}

HTTP/1.1 429 Too Many Requests
Retry-After: 27432

{ "erc": 0, "msg": "Daily API quota for application … has been reached. Upgrade your plan or wait until tomorrow (UTC)." }

Errors

Standard HTTP status codes. Error bodies use the same envelope with erc: 0 and a human-readable msg — either a string or, on validation errors, a { field: "…" } map.

{ "erc": 0, "msg": "Invalid API credentials." }

Versioning

The API is versioned in the URL path. Additive changes — new fields, new endpoints, new envelope keys like meta.usage — ship without a version bump, so always code defensively against unknown fields. Breaking changes ship as a new version (for example /v2) and the previous version stays supported during a documented migration window.