API · v1.0

CivicLens REST API

Complete reference for the CivicLens platform. All endpoints are JSON, authenticated via bearer tokens, and rate-limited at 600 req/min per organization.

Base URL

https://api.civiclens.app/v1

Authentication

Authorization: Bearer cl_live_••••••••••••••••

Entities

GET

/v1/entitiesList entities by state + ZIP

GET

/v1/entities/:idGet entity detail

GET

/v1/lookupGeographic lookup (state + zip → entities)

Findings

GET

/v1/findingsList findings (filters: category, severity, entity)

GET

/v1/findings/:idGet finding detail with counts

POST

/v1/findingsCreate finding (admin only)

PATCH

/v1/findings/:idUpdate finding status / fields

DELETE

/v1/findings/:idDelete finding (admin only)

Actions

POST

/v1/actionsLog a user engagement action (level 1–6)

GET

/v1/actions/meCurrent user's action history

GET

/v1/actions/templatesList active action templates

Users

GET

/v1/meCurrent user profile

PATCH

/v1/meUpdate profile (state, zip, interests)

GET

/v1/me/progressLevel, points, next threshold

Admin

GET

/v1/admin/usersList users (participants & observers)

POST

/v1/admin/templatesCreate action template

PATCH

/v1/admin/levels/:idUpdate engagement level threshold

GET

/v1/admin/schema/versionsList schema migrations

Example: log an action

POST /v1/actions
Authorization: Bearer cl_live_••••••••
Content-Type: application/json

{
  "finding_id": "fd_8e2b1c",
  "level": 3,
  "payload": { "comment": "I support reallocating funds..." }
}

200 OK
{
  "id": "act_71fa9c",
  "user_id": "usr_jr1001",
  "finding_id": "fd_8e2b1c",
  "level": 3,
  "points_awarded": 75,
  "total_points": 1315,
  "new_level": 3,
  "created_at": "2026-05-17T14:22:08Z"
}

Errors

401

Unauthorized — missing or invalid bearer token

403

Forbidden — admin scope required

404

Not Found — resource does not exist

409

Conflict — duplicate action for level

422

Unprocessable — validation failed

429

Rate limited — slow down