# The data API, v1: what stays stable

For the sites and agents that read data.promptugal.news as a source (the other PrompTugal sites among them). The catalogue is [index.json](index.json); the OpenAPI 3.1 description is [openapi.json](openapi.json); try it in [the API explorer](https://data.promptugal.news/api/swagger/).

## The promise

- **Addresses stay.** `api/v1/index.json`, `api/v1/openapi.json` and every `api/v1/<source>/{latest,reads,card,openapi}.json` listed in the catalogue keep their address for the life of v1. `api/v1/storm-charles-archive/manifest.json` and `api/v1/by-place/now/<place>.json` likewise. A file may be added; a listed file is not removed or renamed in v1.
- **Fields stay.** In `index.json`: `about`, `api`, `contract`, `version`, `built_at`, `site`, `sources[]` (`id`, `title`, `publisher`, `cadence`, `read_at`, `latest`, `reads`, `card`, `openapi`, `page`, `vault_id`, `terms_summary`) and `by_place`. Fields may be added; none is removed, renamed or changes type in v1. The same holds for the top-level fields of each data file once it is listed.
- **Every value** carries its source and the UTC time it was read (`provenance` in each latest.json). Times are as the source gives them; where a field says UTC it is UTC.
- **`version`** is the site's release (one per push); it changes many times a day and is not the API's version. The API's version is `api` ("v1") and the path.
- **A source's own terms** travel with its data (`terms_summary` here, `terms` in the card). They are not ours to relax: read them before you reuse a value.
- **A breaking change** goes to `api/v2/`, with v1 kept alongside, and a dated line below before it ships.
- **Refreshed** hourly for the hourly sources (see `cadence`). A source that failed to read keeps its last good file; `reads.json` shows the failure.
- **Not a warning service:** follow IPMA and ANEPC.

## Changelog

- 2026-11-18, evening: added `api/v1/cams/` (latest, reads, card, openapi) and `api/v1/cameras/index.json` with `api/v1/cameras/<id>/status.json` (the same cameras in the shape live.promptugal.news reads): public cameras' metadata and status, never a frame or stream.
- 2026-11-18, evening: added `api/v1/base-gov-pt/places/index.json` and `api/v1/base-gov-pt/places/<place>.json`: the same shape as latest.json with one place only (civic.promptugal.news asked: a council page no longer needs the whole 1.8 MB).
- 2026-11-18, evening: added `api/v1/sources/attribution.json` (the attribution ledger per source, for the SIMULATED payouts: no money moves).
- 2026-11-18, evening: added `api/v1/social/latest.json` (as `api/v1/<source>/`) and `api/v1/social/by-place/<place>.json`: links to organisations' public posts with metadata, never the text.
- 2026-11-18, later: added and promised stable for v1 (events.promptugal.news reads them): `api/v1/events/by-place/index.json` and `<place>.json` (`events[]`, each a schema.org Event with `source`, `read_at`, `place`, `license`), `api/v1/events/claims/by-place/index.json` and `<place>.json` (`claims[]`: Event plus `status` confirmed | to confirm at a readable source | details withheld, `evidence[]` {url, host, readable, register}, `details_from`, `license`), `api/v1/events/past/<place>.json`, `api/v1/sources/index.json`, `api/v1/sources/<id>.json` and `api/v1/sources/gaps.json` (the register), `api/v1/discovery/index.json` and `api/v1/discovery/by-place/<place>/<date>.json`. Every JSON file has a top-level `license` {name, url, holder}.
- 2026-11-18: added (no breaking change): `api/v1/<source>/raw/<file>` (the publisher's own files of the latest read), `api/v1/storm/charles/` (the Storm Charles data, moved here, with its index and `api/v1/storm/openapi.json`).
- 2026-11-17: this contract written; v1 starts with the sources in the catalogue. No breaking change in v1 so far.
