# TRD Events — developer documentation

> TRD Events is a public events calendar for a local community in Norway. Its events are
> available through a public, read-only GraphQL API at https://trdevents.no/graphQL. No key is required
> to read; a free key identifies your application so you are told before a change affects it.

## Pages (markdown)

- https://trdevents.no/utviklere/overview.md — what the API is, the three rules, a first call, why a key
- https://trdevents.no/utviklere/api.md — endpoint, headers, the events query and its filter, pagination, dates, identifiers, price and capacity, errors
- https://trdevents.no/utviklere/reference.md — every type and field, generated from the schema
- https://trdevents.no/utviklere/widget.md — embedding the calendar on another site (JavaScript widget, iframe)
- https://trdevents.no/utviklere/changelog.md — every change to the API or to the data, per licence
- https://trdevents.no/utviklere/schema.graphql — the schema (SDL)

Every page is also served as HTML at the same path without `.md`, and as markdown when the
request sends `Accept: text/markdown`. The pages exist in Norwegian (bokmål) too: replace `.md`
with `.nb.md`, for example https://trdevents.no/utviklere/api.nb.md.

## The three rules

1. IDs are the contract. Filter and match on ids; names and slugs are presentation. Read category
   labels from the `categories` query on every run. Category ids differ per licence and a retired
   id is never reused.
2. `startDate` / `endDate` carry the UTC offset in force on the event's date (`+01:00` in winter,
   `+02:00` in summer), separated from the date by a space. Render in `Europe/Oslo` or use
   `startTime` (Norwegian wall clock). `startDate` is the next upcoming occurrence; `repetitions`
   lists only future ones.
3. Nothing that comes from a form is guaranteed numeric. `Price.price` may be `null`; treat every
   numeric field defensively.

## Keys

- Get one: https://trdevents.no/utviklere/keys (an account on TRD Events with a verified e-mail address)
- Send it: `X-Api-Key: hsk_…` on every request, or `?key=hsk_…` where headers are impossible
- Programmatic creation for a signed-in account: POST https://europe-west1-trdevents-224613.cloudfunctions.net/createApiKey with
  `Authorization: Bearer <Firebase ID token>` and body `{"data":{"name":"my app"}}`

## About

- Site: https://trdevents.no
- Site-wide index: https://trdevents.no/llms.txt
- Contact: post@midtbyen.no