Public API Documentation — Civic Decision Engine

Civic Decision Engine

← Public record index Archive statistics

Public API Documentation

Machine-readable civic record access

Overview

The Civic Decision Engine exposes a public read API for accessing verified civic records. These endpoints allow journalists, researchers, advocacy organisations, and automated systems to retrieve, verify, and archive structured civic evidence programmatically.

All endpoints return JSON. All records exposed through this API are the same records accessible via the public verification pages — this is not a separate dataset.

Authentication

No authentication is required for read operations. These records are intentionally public — they are generated and published by consent at the point of export. Write operations (record creation, superseding) are not exposed through this API.

Base URL

https://civic-decision-engine-production.up.railway.app

Canonical Reference Format

Every public record carries a structured reference that encodes its origin. The format is:

Strike-LA-20260508-001

Strike

System prefix

—

Institution type

—

20260508

Export date (YYYYMMDD)

—

001

Sequence number

References are case-sensitive. Institution type codes are always two uppercase letters. Sequence numbers are zero-padded to three digits. The same reference may have multiple versions — the API always returns the latest unless version history is requested via ?full=true.

Endpoints

Retrieve a single record

GET /api/verify/{reference}

Returns the latest version of a public record by its structured reference. The minimal response includes the fields necessary to verify, cite, and archive the record.

Parameter	Type	Description
reference	path	Structured reference identifier, e.g. `Strike-LA-20260508-001`
full	query	Optional. Pass `?full=true` to include complete metadata and version history.

Minimal response (default):

{
  "reference": "Strike-LA-20260508-001",
  "finding": "The sequence has transitioned into escalation.\n\nEarlier delay has developed into escalation without response.",
  "trajectory": "Deteriorating",
  "conditions": [
    "Transfer of Burden",
    "Escalation Without Response"
  ],
  "system_state": "Transition to Escalation",
  "verification_hash": "935e0a79c9f9283e8a03cfa1d3e8e3d5ff4aea7bc01cef8b3ea64ec0d510b1ff",
  "version": 1
}

Full response (?full=true) additionally includes:

{
  "generated_at": "2026-05-08T12:58:54.870Z",
  "exported_at": "2026-05-08T12:59:04.562034+00:00",
  "language": "en",
  "supersedes": null,
  "generated_by": "Civic Decision Engine",
  "version_history": [
    {
      "version": 1,
      "exported_at": "2026-05-08T12:59:04.562034+00:00",
      "verification_hash": "935e0a79c9f9283e8a03cfa1d3e8e3d5ff4aea7bc01cef8b3ea64ec0d510b1ff"
    }
  ]
}

Example request

curl https://civic-decision-engine-production.up.railway.app/api/verify/Strike-LA-20260508-001

Retrieve archive statistics

GET /api/stats

Returns a summary of the public record archive — total records, superseded versions, and distributions by institution type, trajectory, and condition. Statistics reflect only the latest version of each record.

{
      "total_records": 22,
      "total_superseded": 18,
      "latest_export": "2026-05-09T17:24:27.559+00:00",
      "by_institution": {
        "OT": 3,
        "GV": 3,
        "PL": 3,
        "HO": 3,
        "ED": 3,
        "LG": 3,
        "LE": 3,
        "FS": 2,
        "HS": 2,
        "LA": 1
      },
      "by_trajectory": {
        "Deteriorating": 22
      },
      "by_condition": {
        "Transfer of Burden": 22,
        "Escalation Without Response": 22
      }
    }

Example request

curl https://civic-decision-engine-production.up.railway.app/api/stats

Retrieve the record index

GET /api/records

Returns a paginated list of the latest version of all public records, most recent first. Supports filtering by trajectory and institution type.

Parameter	Type	Description
trajectory	query	Filter by trajectory value, e.g. `Deteriorating`
institution	query	Filter by institution type code, e.g. `LA`, `HS`, `ED`
limit	query	Maximum records to return. Default 50, maximum 200.
offset	query	Pagination offset. Default 0.
full	query	Pass `?full=true` to include finding, language, and supersedes per record.

{
  "total": 12,
  "offset": 0,
  "limit": 50,
  "filters": {
    "trajectory": null,
    "institution": null
  },
  "records": [
    {
      "reference": "Strike-LA-20260508-001",
      "trajectory": "Deteriorating",
      "conditions": ["Transfer of Burden", "Escalation Without Response"],
      "system_state": "Transition to Escalation",
      "institution_type": "LA",
      "exported_at": "2026-05-08T12:59:04.562034+00:00",
      "version": 1,
      "verification_hash": "935e0a79..."
    }
  ]
}

Example requests

curl https://civic-decision-engine-production.up.railway.app/api/records curl https://civic-decision-engine-production.up.railway.app/api/records?trajectory=Deteriorating curl https://civic-decision-engine-production.up.railway.app/api/records?institution=LA&limit=10

Retrieve the condition registry

GET /api/conditions

Returns the canonical condition registry — the civic observation taxonomy used to classify case sequences. Each entry includes the condition name, internal code, formal description, and detection indicators.

Example request

curl https://civic-decision-engine-production.up.railway.app/api/conditions

Download verification manifest

GET /verify/{reference}/manifest

Returns a downloadable JSON manifest for a public record. The manifest contains all canonical fields, the verification hash, and a recomputation instruction that allows independent offline verification of record integrity.

{
  "manifest_version": "1.0",
  "manifest_type": "civic_decision_engine_record",
  "reference": "Strike-LA-20260508-001",
  "version": 1,
  "supersedes": null,
  "generated_at": "2026-05-08T12:58:54.870Z",
  "exported_at": "2026-05-08T12:59:04.562034+00:00",
  "language": "en",
  "generated_by": "Civic Decision Engine",
  "finding": "The sequence has transitioned into escalation...",
  "trajectory": "Deteriorating",
  "conditions": ["Escalation Without Response", "Transfer of Burden"],
  "system_state": "Transition to Escalation",
  "verification_hash": "935e0a79...",
  "canonical_fields": {
    "conditions": ["Escalation Without Response", "Transfer of Burden"],
    "finding": "The sequence has transitioned into escalation...",
    "generated_at": "2026-05-08T12:58:54.870Z",
    "generated_by": "Civic Decision Engine",
    "reference": "Strike-LA-20260508-001",
    "system_state": "Transition to Escalation",
    "trajectory": "Deteriorating"
  },
  "recomputation_instruction": {
    "algorithm": "SHA-256",
    "method": "Serialize canonical_fields as JSON with keys in sorted order, no spaces, and conditions sorted alphabetically. Compute SHA-256 of the UTF-8 encoded string. The result must match verification_hash.",
    "canonical_serialization": "{"conditions":[...],"finding":"..."}",
    "verify_url": "https://civic-decision-engine-production.up.railway.app/verify/Strike-LA-20260508-001"
  }
}

Example request

curl -O https://civic-decision-engine-production.up.railway.app/verify/Strike-LA-20260508-001/manifest

Verification Integrity

Verification hashes are computed from canonical record fields at the time of export using SHA-256. The canonical fields are: reference, generated_at, finding, trajectory, conditions, system_state, and generated_by. Any alteration to those fields after export will produce a different hash. The hash displayed on the verification page and returned by this API can be independently recomputed to confirm the record has not been altered since publication.

Response Formats

All responses are application/json. All timestamps are ISO 8601. Conditions are returned as human-readable label arrays.

Status Codes

200	OK — record found and returned successfully.
404	Not Found — no record exists for the given reference. Returns a structured error body.
422	Unprocessable — query parameters are malformed or out of range.

404 error body:

{
  "error": "not_found",
  "message": "No public record found for reference: Strike-XX-00000000-000"
}

Versioning

All endpoints return the latest version of each record by default. When a record is superseded, the previous version is preserved and remains accessible via ?full=true. The version field indicates which version is currently returned. The supersedes field identifies the prior version reference when applicable.

Published record versions remain preserved once exported. Corrections or amendments result in a new version, with all prior versions retained in the version history.

API version: v1 — stable. No breaking changes will be made without a version increment.

Institution Type Codes

Code		Institution type
LA		Local Authority
HS		Health Service
ED		Education
HO		Housing
PL		Planning
GV		Government
FS		Financial Services
LE		Law Enforcement
LG		Legal
OT		Other

Notes on Public Records

Records accessible through this API are structured evidentiary documents generated by the Civic Decision Engine at the time of export. Published record versions remain preserved once exported. Corrections or amendments result in a new version, with the original preserved in the version history.

These records are designed for use in civic, administrative, and formal complaint proceedings. They are not legal advice and do not constitute official determinations by any public body. They are observation instruments — structured accounts of institutional behaviour as experienced and recorded by the person submitting the case.