# Getting started

A five-minute walkthrough for a developer integrating a VS Engine
client from zero.

## 1. Confirm your API key

Your API key was delivered out-of-band by Insideformation. The key
determines your client identity, your language, and your league
bulkhead — see [auth](../concepts/auth.md).

```bash
export VS_KEY="your-key-here"
export VS_BASE="https://api.insideformation.com/dataengine"
```

## 2. Hit `/status` — no key needed

```bash
curl "$VS_BASE/status"
```

You should get a JSON payload with `matchCount`, `articleCount`,
pipeline timestamps, and cost status. If this fails, the server is
down — escalate to Insideformation.

## 3. Fetch your lobby feed

```bash
curl -H "X-API-Key: $VS_KEY" "$VS_BASE/feed/hemmaklubben" | jq .
```

(Replace `hemmaklubben` with your client id — `junibet`, etc.)

The response is the full front-page feed: an array of
`{ slot, template, articles, widgets }` blocks ready to render.

## 4. Use conditional requests

All feed endpoints return an `ETag` header. Save it and send it back
as `If-None-Match` on the next poll:

```bash
curl -H "X-API-Key: $VS_KEY" \
     -H 'If-None-Match: "abc123…"' \
     -i "$VS_BASE/feed/hemmaklubben"
```

If the feed has not changed, you get `304 Not Modified` with an
empty body. Bandwidth saved.

For even cheaper polling, use `/feed/:clientId/poll` — it returns
only metadata (no article bodies, no widget data) and its `feedVersion`
tells you whether the real feed has changed.

## 5. Drill into a single match

```bash
curl -H "X-API-Key: $VS_KEY" \
  "$VS_BASE/feed/hemmaklubben/match/1026050832" | jq .
```

The response contains the full article, all widgets for that match,
and a `match` envelope with team badges, form, and kickoff.

## 6. Hide blocked widgets

Some widgets return `{ "blocked": true, "reason": "..." }` instead
of a body. Frontends MUST hide these entirely — see
[data policy](../concepts/data-policy.md). Rendering a placeholder
defeats the whole point of the never-invent-data contract.

## 7. Junibet-only features

If you hold the Junibet key, you also have access to:

- `GET /junibet/accumulators` — three pre-built betting slips (safe /
  balanced / long-shot) combining ValueStats confidence with Kambi
  most-backed outcomes.
- `GET /junibet/market-spotlight` — top headline insight per match
  with an optional odds hint.
- `GET /junibet/ticker` — flattened top insights across all matches,
  weighted by betting volume.

All three respect the never-invent-data contract: if the Kambi
betting-patterns index isn't loaded for your market, the endpoint
returns `503 upstream_unavailable` rather than a synthesized payload.

## 8. Explore the full reference

The interactive OpenAPI reference (Scalar) is served alongside this
guide at `/docs/index.html` in the repo. For LLM consumption, use
`docs/llms.txt` (short index) or `docs/llms-full.txt` (expanded
endpoint catalogue).