Beacon

API Documentation

Beacon exposes two APIs: a public incidents API (no key required for read) and a Press API for organizations that need higher limits, filtering, and optional media access.

Getting an API key

Press API keys are for organizations (newsrooms, researchers, partners) that need programmatic access to incident data with higher quotas and optional media downloads.

  1. Request access. Contact us at api@beacon.example with your organization name, contact email, and intended use. We will create an organization and send you an API key.
  2. Save your key securely. The API key is only returned once when the organization is created. Store it in a secure secret manager or environment variable; we cannot retrieve or resend it.
  3. Use the key in requests. Send it in the X-API-Key header for all Press API requests (see Authentication below).

API key format

pk_live_<random> or pk_test_<random>

Live keys are for production; test keys are for development and may have different limits.

Authentication (Press API)

Include your API key on every Press API request using the X-API-Key header.

X-API-Key: pk_live_your_api_key_here

Do not expose your API key in client-side code or public repos. Use server-side only or secure environment variables.

Public API (no key required)

These endpoints are used by the Beacon app and can be called without an API key for read access to public incidents.

  • GET /health

    Health check. Returns { "status": "ok" }.

  • GET /incidents

    List public incidents. Query params: id, cellIds, category, since, limit (max 200, default 100). Response: { incidents: [...] }.

The mobile app also uses POST /session (with X-Device-Id) and POST /incidents, POST /incidents/:id/complete for submitting reports; those require an anonymous session token and are intended for the app, not third-party integrations.

Press API (API key required)

Base path: /press. All requests require the X-API-Key header. Responses include normalized incident data and optional usage/quotas.

  • GET /press/incidents

    List incidents with normalized location (~1 km precision). Query: category, since, until, region_lat, region_lng, limit, offset. Response includes incidents, pagination, quotas.

  • GET /press/incidents/:id

    Get a single incident by ID. Returns normalized incident with location and media metadata.

  • GET /press/incidents/:id/media

    List media items for an incident (metadata only). Use the download endpoint to obtain actual file URLs (paid tiers).

  • POST /press/incidents/:id/media/:mediaId/download

    Request a time-limited download URL for a media item. Requires a paid subscription and download permission. Response includes download_url, expires_at, quotas.

  • GET /press/categories

    List available incident categories with counts. Useful for filtering.

  • GET /press/account

    Get current organization info, API key permissions, and usage quotas (api_calls, downloads).

Rate limits and quotas

Press API usage is tier-based. Typical limits (subject to change):

  • Trial: 1,000 API calls/month, 0 downloads, ~10 requests/min.
  • Basic: 10,000 API calls, 100 downloads, ~60/min.
  • Professional: 100,000 API calls, 1,000 downloads, ~200/min.
  • Enterprise: Higher limits; contact us.

Exceeding rate limits returns 429. Exceeding monthly quotas returns 429 with upgrade information. Use GET /press/account to check current usage.

Base URL

Use your deployment base URL. Example:

https://api.beacon.example

All API requests use HTTPS. Replace with your actual API host when integrating.