Skip to content

Latest commit

 

History

History
153 lines (105 loc) · 3.19 KB

API_V1.md

File metadata and controls

153 lines (105 loc) · 3.19 KB

OpenComments Public API v1

This document defines the OpenComments v1 API contract for open data access and export jobs.

Base URL

  • Supabase Edge Function base: /functions/v1/public-api
  • Version prefix: /v1

Example full path:

/functions/v1/public-api/v1/dockets

Content Type

  • Requests: application/json
  • Responses: application/json

Pagination

List endpoints support:

  • page (default 1)
  • per_page (default 20, max 100)

List responses include:

  • meta.page
  • meta.per_page
  • meta.total_count (null or unknown when exact count is unavailable)
  • Headers: X-Request-Id, X-Page, X-Per-Page, X-Total-Count

Rate Limiting

  • Public API routes are rate limited per-IP and per-route in a 60-second window.
  • Default limit: 120 requests/minute (configurable via PUBLIC_API_RATE_LIMIT_PER_MINUTE).
  • Exceeded requests return 429 RATE_LIMIT_EXCEEDED.

Public Read Endpoints

GET /v1/dockets

Query params:

  • q (optional search text)
  • status (open default, draft, closed, archived, all)
  • tags (comma-separated list)
  • page, per_page

GET /v1/dockets/{slug}

Returns public docket detail with agency context, attachments, and public comments.

GET /v1/comments

Query params:

  • status (comma-separated list; default compatibility set: published,approved)
  • docket_slug
  • q (content search)
  • page, per_page

GET /v1/comments/{id}

Returns one public comment detail record.

GET /v1/agencies

Query params:

  • q (name/jurisdiction search)
  • page, per_page

GET /v1/agencies/{slug}

Returns one agency profile.

Export Endpoints (Authenticated)

Authentication uses Supabase JWT bearer token:

Authorization: Bearer <access_token>

POST /v1/exports

Request body:

{
  "agency_id": "uuid",
  "docket_id": "uuid-optional",
  "export_type": "csv",
  "filters": {
    "comment_statuses": ["published"],
    "date_from": "2026-01-01T00:00:00Z",
    "date_to": "2026-01-31T23:59:59Z",
    "include_pii": false
  }
}

Notes:

  • export_type: csv | zip | combined
  • Creates job and triggers background generation function.
  • PII behavior:
    • include_pii defaults to false.
    • Email fields are masked unless include_pii=true and caller has authorized platform role.
    • When requesting unmasked PII, include pii_reason in filters.

GET /v1/exports/{id}

Returns export job status and metadata for authorized agency users.

GET /v1/exports/{id}/download

Returns a one-hour signed download URL for completed exports.

Error Shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "agency_id is required",
    "details": null
  }
}

Rate limit error example:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many API requests. Please retry shortly.",
    "details": {
      "limit": 120,
      "remaining": 0,
      "reset_at": "2026-02-11T12:00:00Z"
    }
  }
}

Current Status Notes

  • v1 route handlers are implemented in:
    • supabase/functions/public-api/index.ts
  • Export processing function:
    • supabase/functions/generate-export/index.ts
  • Rate limiting and formal OpenAPI generation are planned hardening tasks.