API Reference
The full OpenAPI specification is defined in /openapi.yaml. Use any Swagger UI instance (for example https://editor.swagger.io/) and import the file to explore interactive documentation during development.
Authentication
Most routes in app/api.py are decorated with @token_required. They accept either an interactive login session or an API token passed via an Authorization: Bearer <token> header. Query-string credentials are rejected. Endpoints marked with @permission_required additionally check that the authenticated user holds the named permission. The lightweight ticket lookup (@token_auth.login_required) only accepts an API token in the Authorization header.
Ticket lifecycle
| Method | Path | Auth | Description | Payload / Parameters |
|---|---|---|---|---|
GET | /api/v1/tickets | Session or token | List tickets filtered by region, status, start, end and optional JSON filter tree supplied as filter_json. | Query string parameters. |
POST | /api/v1/tickets | Session or token | Create a ticket using the same fields as the web form. | JSON body mirroring TicketForm; accepts channel or legacy channel_id. |
POST | /api/v1/tickets/quick_create | Session or token | Minimal ticket creation with just title and optional priority. | JSON body { "title": string, "priority": integer }. |
GET | /api/v1/tickets/{ticket_id} | Bearer token only | Retrieve a simplified ticket snapshot containing id, title, description, status, priority and timestamps. | Path parameter ticket_id. |
GET | /api/v1/tickets/{ticket_id}/evidence | Session or token | Retrieve the source-level evidence ledger, verification state, provenance references and hashes. | Path parameter ticket_id. |
GET | /api/v1/tickets/{ticket_id}/evidence-bundle | Session or token | Retrieve an AI/audit-ready incident bundle: facts, privacy-safe evidence graph and ledger, audit timeline, observed claim decomposition, linked disinformation signals and a privacy-safe AAR learning summary. | Path parameter ticket_id. |
PATCH | /api/v1/tickets/{ticket_id}/evidence/{source_id} | Requires EDIT_ANY_INCIDENT | Record an audited operator review for one external source. | JSON body { "state": "unreviewed|reviewed|corroborated|rejected", "evidence_role"?: "supporting|contradicting|contextual", "confidence"?: 0..100, "note"?: string }. |
POST | /api/v1/tickets/{ticket_id}/attachments | Requires EDIT_ANY_INCIDENT | Upload one or more files as attachments for the ticket. | multipart/form-data with one or more file fields. |
POST | /api/v1/tickets/{ticket_id}/playbook/execute_step/{step_id} | Requires EXECUTE_PLAYBOOK_STEP | Execute the referenced automated playbook step for the ticket. | Path parameters ticket_id, step_id; no body. |
Ticket insights and proximity
| Method | Path | Auth | Description | Payload / Parameters |
|---|---|---|---|---|
GET | /api/v1/tickets/{ticket_id}/nearby | Session or token | Tickets within radius kilometres of the specified ticket (default 1 km). | Path parameter ticket_id, optional radius query parameter. |
GET | /api/v1/incidents/{incident_id}/nearby | Session or token | Incident proximity search leveraging geographic clustering utilities. | Path parameter incident_id, optional radius query parameter. |
GET | /api/v1/tickets/{ticket_id}/context | Session or token | Weather, nearby incidents and available resources around a ticket. | Path parameter ticket_id. |
GET | /api/v1/tickets/{ticket_id}/communications | Session or token | Bounded recipient-safe delivery ledger with channel states, acknowledgement coverage and unresolved coverage. | Path parameter ticket_id; optional limit, maximum 50. |
GET | /api/v1/incidents/{incident_id}/context | Session or token | Same contextual data using an incident id alias. | Path parameter incident_id. |
GET | /api/v1/tickets/{ticket_id}/cluster | Session or token | Temporal cluster containing the ticket given window (hours) and threshold. | Path parameter ticket_id; optional window, threshold query parameters. |
GET | /api/v1/tickets/stats | Session or token | Rolling counts of tickets grouped by day for the past days (default 7). | Optional days query parameter. |
GET | /api/v1/tickets/clusters | Session or token | Detect clusters across all tickets with adjustable window and threshold. | Optional window, threshold query parameters. |
GET | /api/v1/tickets/coordinates | Session or token | Return [lat, lon] pairs for all geocoded tickets. | No body. |
GET | /api/v1/incidents/heatmap | Session or token | Heatmap-friendly coordinates for active incidents. | No body. |
Resources and geography
| Method | Path | Auth | Description | Payload / Parameters |
|---|---|---|---|---|
GET | /api/v1/resource_points | Session or token | Inventory of registered emergency resource points. | No body. |
GET | /api/v1/static_resources | Session or token | List of static resources with coordinates. | No body. |
GET | /api/v1/resources | Session or token | Aggregate emergency resources including contact info. | No body. |
GET | /api/v1/geozones | Session or token | Configured GeoZones including triggers and priority modifiers. | No body. |
GET | /api/v1/weather | Session or token | Current weather for provided lat and lon. | Query parameters lat, lon. |
Incident planning and communications
| Method | Path | Auth | Description | Payload / Parameters |
|---|---|---|---|---|
GET | /api/v1/incident-types/{type_id}/valid-responses | Session or token | Allowed response options for the specified incident type. | Path parameter type_id. |
GET | /api/v1/incidents/{incident_id}/information_plan | Session or token | The configured information response plan tied to the incident type. | Path parameter incident_id. |
GET | /api/v1/audiences/{audience_id}/cultural_checklist | Session or token | Cultural checklist entries for a target audience. | Path parameter audience_id. |
POST | /api/v1/info-plan/send-message | Session or token | Deliver a templated communication from an information plan. | JSON body { "info_plan_id": int, "template_id": int, "audience_id": int }. |
Analytics, dashboards and filters
| Method | Path | Auth | Description | Payload / Parameters |
|---|---|---|---|---|
GET | /api/v1/sla | Session or token | SLA summary statistics for all tickets. | No body. |
GET | /api/v1/analytics/advanced | Session or token | Aggregated analytics that power dashboard visualisations. | No body. |
GET | /api/v1/sources/health | Session or token | Registered source paths, persisted probe state and independent event-freshness context. | Optional limit query parameter, maximum 50. |
GET | /api/v1/sources/credibility | Session or token | Descriptive source review profiles based on observed ExternalSource states; no normative rating or false-positive rate is inferred. | Optional limit query parameter, maximum 50. |
GET | /api/v1/teams/activation | Session or token | Read-only team composition, active workload and explicit duty-handoff coverage; assignment rows alone never count as acknowledgement. | Optional limit query parameter, maximum 20. |
POST | /api/v1/teams/handoffs | Requires action:assign_incident | Create an explicit primary or secondary duty handoff with optional assignee and timezone-aware deadline. | JSON body { "ticket_id": int, "team_id": int, "coverage_role": "primary|secondary", "assignee_id": int?, "due_at": ISO-8601? }. |
PATCH | /api/v1/teams/handoffs/{handoff_id} | Assignee or action:assign_incident | Move an explicit duty handoff to accepted, rejected, expired or cancelled; rejected/expired coverage can return to pending; no account presence is treated as acknowledgement. | JSON body { "state": string }. |
GET | /api/v1/disinformation/narrative-velocity | Session or token | Observed case mentions and two-window velocity; review state is shown separately and no clustering or truth verdict is inferred. | Optional limit query parameter, maximum 20. |
GET | /api/v1/disinformation/narrative-clusters | Session or token | Explainable, non-persistent grouping suggestions with versioned membership, two-window velocity, source composition and separate reviewed/unreviewed claims; no truth or attribution verdict is inferred. | Optional limit query parameter, maximum 20. |
GET | /api/v1/forecasts/registry | Session or token | Bounded forecast registry with scenario bands, input cutoff, model/version, outcome state and explicit calibration/missing-outcome semantics. | Optional limit query parameter, maximum 50. |
POST | /api/v1/forecasts | Session or token | Store a forecast evidence record; it never creates an escalation or operational action. | JSON payload with target, horizon, spatial unit, input cutoff, model/version and low/expected/high values. |
PATCH | /api/v1/forecasts/{forecast_id}/outcome | Session or token | Record an observed or explicitly missing outcome for later calibration. | JSON { "outcome_state": "observed|missing", "outcome_value": number?, "observed_at": ISO-8601 }. |
GET | /api/v1/user/dashboard-config | Session or token | Retrieve the current user's saved dashboard layout. | No body. |
POST | /api/v1/user/dashboard-config | Session or token | Persist dashboard layout widgets; expects a list of {name, x, y, w, h} objects. | JSON array of widget descriptors. |
GET | /api/v1/filters | Session or token | List saved ticket filters for the current user. | No body. |
POST | /api/v1/filters | Session or token | Create a saved filter owned by the current user. | JSON body { "name": string, "filter_json": object }; the object uses nested { "op": "and|or", "filters": [...] } groups and field rules. |
DELETE | /api/v1/filters/{filter_id} | Session or token | Delete a saved filter belonging to the current user. | Path parameter filter_id. |
POST | /api/v1/release-notes | Requires ADMIN_MANAGE_USERS | Create a release note entry (version, ISO date and text). | JSON body { "version": string, "date": YYYY-MM-DD, "text": string }. |
Utilities and exports
| Method | Path | Auth | Description | Payload / Parameters |
|---|---|---|---|---|
GET | /api/v1/edxl/sitreps | Session or token | Export all tickets as an EDXL SituationReport XML document. | No body; response is application/xml. |
GET | /api/v1/cap/alerts | Session or token | Export tickets as CAP Alert XML fragments. | No body; response is application/xml. |
POST | /api/v1/translate | Session or token | Translate text through QazCompute with DeepSeek-compatible fallback. | JSON body { "text": string, "target_lang": string }; text is limited to 12,000 characters. |
GET | /api/v1/buffer/{buffer_id}/sentiment | Session or token | Return stored sentiment data for a Buffer link if present. | Path parameter buffer_id. |
GET | /api/v1/buffer/{entry_id}/sentiment | Session or token | On-demand VADER sentiment analysis of the Buffer entry title/description. | Path parameter entry_id. |
Documentation and integrations
| Method | Path | Auth | Description | Payload / Parameters |
|---|---|---|---|---|
GET | /api/v1/schema | Public | Download the OpenAPI schema YAML served from docs/openapi.yaml. | No body. |
GET | /api/v1/docs | Public | Rendered HTML documentation that embeds Swagger UI. | No body. |
POST | /api/v1/notify/ticket/{ticket_id} | X-API-Key header | Trigger a Telegram notification for a ticket using template formatting. Query-string credentials are rejected. | JSON body { "channel_id": string, "message_template"?: string }. |
POST | /api/v1/integrations/qazpipe/events | Bearer token | Idempotently create an operational ticket from a normalized QazPipe event with immutable QazLake evidence. | See integrations/QAZPIPE.md. |
POST | /api/v1/integrations/qazpipe/heartbeat | Bearer token | Record a bounded, idempotent QazPipe collection heartbeat and return payload-free continuity history without storing raw provider payloads. | See integrations/QAZPIPE.md. |
POST | /api/v1/disinformation/signals | Bearer token | Stage an untrusted disinformation observation for analyst review. | See integrations/DISARM.md. |
GET | /api/v1/disarm/status | Session or token | Return the active DISARM taxonomy snapshot and item counts. | No body. |
AI discovery and low-cost public access
These endpoints are intentionally public and small so AI systems can discover the site, pick the cheapest data source, and avoid scraping authenticated operator pages.
For production deployments, set PUBLIC_BASE_URL to the canonical HTTPS origin so /llms.txt, /ai.json and CAP-derived alert URLs always point to the correct external address behind a reverse proxy.
If the reverse proxy injects a global X-Robots-Tag: noindex, carve out these public discovery routes and override them with an indexable policy such as index, follow, max-image-preview:large, max-snippet:-1. Otherwise AI agents will find the manifests but still treat the public machine surface as blocked. The carve-out includes /methodology.json; operator HTML remains noindex.
| Method | Path | Auth | Description | Cache |
|---|---|---|---|---|
GET | /llms.txt | Public | LLM-oriented map of public data, API contracts, crawl rules and preferred access order. | public, max-age=3600 |
GET | /.well-known/llms.txt | Public | Alias redirect to the primary llms.txt document for crawlers that probe /.well-known/. | 302 |
GET | /ai.json | Public | Structured machine manifest with endpoint metadata, privacy notes and refresh guidance. | public, max-age=3600 |
GET | /.well-known/ai.json | Public | Alias redirect to the primary AI manifest for clients that probe /.well-known/. | 302 |
GET | /.well-known/ai-plugin.json | Public | Compatibility alias for agents that probe the older AI plugin manifest path; redirects to /ai.json. | 302 |
GET | /robots.txt | Public | Crawler policy, sitemap URL, LLMS pointer and AI manifest pointer. | public, max-age=3600 |
GET | /sitemap.xml | Public | Public machine-readable sitemap for discovery endpoints and public CAP feeds. | public, max-age=3600 |
GET | /api/cap/summary | Public | Lowest-cost current-state JSON aggregate. Use this before fetching feeds or HTML. | public, max-age=120 |
GET | /api/cap/feed | Public | Atom feed for recent public CAP alerts. | public, max-age=300 |
GET | /api/cap/rss | Public | RSS feed for recent public CAP alerts. | public, max-age=300 |
/ai.json also exposes platform_integrations so automated consumers can see the ecosystem boundary without scraping internal docs:
- QazStack: shared operational primitives and compatibility contracts.
- QazPipe: normalized event intake before the Crisis relevance gate.
- QazLake: immutable evidence references; restricted raw evidence stays private.
- QazCompute: NLP, embeddings, translation and model provenance.
- QazGeo: GIS catalog, geocoding and operational layers.
- AV DS 4: compact operator interface design system.
Recommended AI flow:
- Fetch
/llms.txt. - Fetch
/ai.json. - Fetch
/api/cap/summary?limit=12. - Fetch
/api/cap/feedor/api/cap/rssonly when item-level alert data is needed. - Use authenticated
/api/v1/*endpoints only with an explicit token and a clear purpose.
All primary AI discovery responses also emit Link headers that point to the manifest, llms.txt, OpenAPI schema, robots policy and sitemap, so machine clients can pivot without crawling authenticated HTML routes.