API & Integration Reference

Typed operational boundaries for citizen reporting, workflow execution, ML inference, and supervisor review actions.

Civitas Envelope Specification

Every API endpoint wraps its payload in a standardized Civitas Envelope. Successful responses include a success boolean, data payload, and metadata. Error responses return structured error codes and human-actionable messages without leaking private secrets.

INTERACTIVE SPECIFICATION

Civitas REST API Endpoints

All endpoints return a typed Civitas Envelope structure. Model outputs, retrieved policy references, and human decisions are strictly isolated in schema responses.

POST/api/v1/reports

Submit Citizen Report▲

Accepts multimodal citizen report (text, media URLs, GPS coordinates) and initializes evidence validation.

{
  "description": "Water leaking heavily from main pipe near DAV school gate. Road is flooded.",
  "category": "water_leakage",
  "latitude": 20.29614,
  "longitude": 85.82451,
  "ward": "Ward 12",
  "media_urls": [
    "https://civitas.local/media/leak_photo_01.jpg"
  ]
}

GET/api/v1/incidents/{incident_id}

Get Incident Dossier▼

POST/api/v1/workflows/{workflow_id}/review

Submit Supervisor Review ActionAUTH REQUIRED▼

POST/api/v1/ml/analyze

Internal ML & Geospatial Analysis BridgeAUTH REQUIRED▼

GET/api/v1/public/incidents.geojson

Public GeoJSON Transparency Feed▼

GET/api/v1/public/incidents.csv

Public Open Data CSV Stream▼

GET/api/v1/analytics/contractors

Contractor Performance & SLA Analytics▼

GET/api/v1/work-orders/batches

Spatial Work Order Crew Batching▼

POST/api/v1/work-orders/boq-estimate

Schedule of Rates (SOR) BOQ Costing▼

GET/api/v1/resolutions/{incident_id}/certificate

Cryptographic Municipal Audit Certificate▼

GET/api/v1/resolutions/{incident_id}/dispute-status

72-Hour Citizen Dispute Window Status▼

POST/api/v1/resolutions/{incident_id}/dispute

Submit Citizen Dispute & Reopen Incident▼

POST/api/v1/intake/simulate

Omnichannel Intake Simulator▼

GET/api/v1/open311/v2/services.json

Open311 GeoReport v2 Service Discovery▼

{ "description": "Water leaking heavily from main pipe near DAV school gate. Road is flooded.", "category": "water_leakage", "latitude": 20.29614, "longitude": 85.82451, "ward": "Ward 12", "media_urls": [ "https://civitas.local/media/leak_photo_01.jpg" ] }