API Reference
REST API for GovScope. Use these endpoints to manage alerts, search documents, and export results. Authentication uses your session cookie (web app) or a Bearer API key (Enterprise plan, server-to-server).
Programmatic API access requires the Enterprise plan. Sign up for an account to get started.
OpenAPI spec
Machine-readable OpenAPI 3.1 schema for this API. Import into Postman, generate SDKs, or explore interactively.
Base URL
https://govscope.appAll paths below are relative to this base URL. Requests must include a valid session cookie or Bearer token.
Authentication
Session cookie: Supplied automatically when you're signed in to the web app at govscope.app.
Bearer token: Enterprise accounts can generate an API key in Settings. Send it as Authorization: Bearer <token>.
Rate limits: 60 requests per minute per user across most endpoints. Bulk import endpoints are stricter (5/min). Exceeding the limit returns HTTP 429.
Endpoints
/api/alerts
List all active alerts for the authenticated user, ordered by creation date descending.
Response
Alert[]/api/alerts
Create a new alert. Respects tier limits — resident accounts are limited to 3 alerts and daily frequency only.
Parameters
stringHuman-readable label for this alert (max 100 chars).
"radius" | "polygon" | "municipality" | "parcel"How the alert area is defined.
numberLatitude of center point — required when geography_type is radius.
numberLongitude of center point — required when geography_type is radius.
numberRadius in miles around the center point.
string[] (UUIDs)Municipality UUIDs to watch. Required when geography_type is municipality.
string[]Parcel IDs to watch. Required when geography_type is parcel.
DocType[]Document types to match. Values: "agenda", "minutes", "permit", "ordinance", "resolution", "budget", "variance", "meeting_transcript", "agenda_packet", "report", "notice", "contract", "document".
string[]Semantic match terms. Empty array matches all documents in the geography.
"instant" | "daily" | "weekly"Delivery frequency. Defaults to "daily". Instant requires Professional tier.
number (1–10)Minimum impact score to trigger. Defaults to 1 (all documents).
Response
Alert — HTTP 201 on success, 403 with { error, upgrade: true } when tier limit reached./api/alerts/:id
Update an existing alert. Accepts any subset of the fields from POST. Returns the updated alert.
Parameters
string (UUID)Alert ID — passed as a path segment.
Response
Alert/api/alerts/:id
Delete an alert by ID. Only the owning user may delete their own alerts.
Parameters
string (UUID)Alert ID — passed as a path segment.
Response
HTTP 204 No Content/api/documents
Search and paginate processed government documents. All responses include only documents with processing_status = complete.
Parameters
stringTitle keyword search.
string (comma-separated UUIDs)Filter to specific municipalities.
string (comma-separated DocType values)Filter by document type.
string (YYYY-MM-DD)Start of meeting date range.
string (YYYY-MM-DD)End of meeting date range.
numberPage number, 1-indexed. Defaults to 1.
number (1–100)Records per page. Defaults to 25.
"meeting_date" | "ingested_at"Sort field. Defaults to meeting_date descending.
Response
{ documents: Document[], total_count: number, page: number, per_page: number }/api/export
Export documents to CSV or JSON. Requires Professional tier or above. Record limits apply per tier: Professional — 1,000, Enterprise — unlimited.
Parameters
"csv" | "json"Output format. CSV includes an FCRA disclaimer header.
string[]Filter exported documents by type.
string[]Filter to specific municipalities.
string (YYYY-MM-DD)Start of meeting date range.
string (YYYY-MM-DD)End of meeting date range.
stringFull-text search query applied to document text.
Response
CSV file download or JSON array — Content-Disposition attachment header set on both.