# Scout by Jakvab — full machine guide

Scout is an AI-powered business intelligence layer for Nordic companies. It collects
company data from public sources (official registers, company websites, news, job
postings, procurement), turns it into permanent "signals", and enriches everything with
AI: a one-line summary plus explainable buying / growth / risk scores. Everything is
exposed through one REST API. This file is written for AI agents — it is complete and
imperative. JSON in, JSON out, snake_case throughout.

## Connection

- Base URL: https://api.scout.jakvab.se/v1
- Auth: `Authorization: Bearer <api_key>` (all routes except /health and /version).
- Get a key: POST your work email + company org number at
  https://scout.jakvab.se/developers.html#get-key — the key is emailed. One key per org.
- Content-Type: application/json for POST bodies.
- Errors: HTTP 4xx/5xx with `{"error":{"code":"<stable_code>","message":"<human text>"}}`.
- Rate limit (free tier): 10 requests/day per key, max 100 objects per response.
  Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (epoch).
  Over limit → HTTP 429, code "rate_limited".

## Endpoints

### GET /health  (no auth)
→ 200 {"ok": true}

### GET /version  (no auth)
→ 200 {"version","deployed_at","model","backend"}

### GET /companies/{country}/{org_number}   (preferred lookup)
Path: country = ISO-2 (NO live; SE/DK/FI coming). org_number digits (dashes/spaces ok).
Example: GET /companies/NO/923609016
→ 200 {
  "id":"cmp_NO923609016","org_number":"923609016","country":"NO",
  "legal_name":"EQUINOR ASA","status":"active",
  "ai_summary":"…one-line description of what the company does…",
  "scores":{"buying":0.35,"growth":null,"risk":null,"scored_at":"…"},
  "signal_count": 3, "primary_domain":"equinor.com", …
}
404 {"error":{"code":"not_found","message":"Company not found"}} if unknown.

### GET /companies/{id}
id = internal Scout id, shape cmp_<COUNTRY><orgnr>, e.g. cmp_NO923609016. Same response.

### GET /companies/{country}/{org_number}/signals?limit=N   (also /companies/{id}/signals)
Newest first. → 200 {"data":[{"id","type","category","title","summary","occurred_at",
"strength","polarity","based_on_signal_ids?"}...],"next_cursor":null}
Signal types include: company_created, new_ceo, new_board_member, hiring, funding_round,
product_launch, office_expansion, technology_added, procurement_win, patent_filed,
press_release, new_website, bankruptcy.

### GET /companies  ?org_number=&domain=&limit=
List, or look up by external id. → {"data":[company…],"next_cursor":null}

### POST /search
Body: {"query":"<natural language or keywords>","mode":"keyword","limit":25}
(MVP supports mode=keyword; semantic/hybrid coming.)
→ {"data":[{"company":{…},"score":<0-1|null>,"why":"<reason for the match>"}...],"next_cursor":null}

## How to use the scores (important)

- buying / growth / risk are 0..1, explainable. Each company/insight response carries the
  reasoning. When a signals or insights payload includes `based_on_signal_ids`, those are
  the exact signals that drove the score — cite them; never invent a rationale.

## Worked example (look up + read signals)

1) GET /companies/NO/923609016
   → entity + ai_summary + scores.buying
2) GET /companies/NO/923609016/signals
   → the events behind the score (e.g. new_ceo, hiring).
Use the returned `id` for any follow-up calls.

## Pointers

- OpenAPI 3.1 (authoritative, generated): https://api.scout.jakvab.se/v1/openapi.json
- Swagger UI: https://api.scout.jakvab.se/v1/docs
- MCP + agent front door: https://scout.jakvab.se/agents.html
- Short version of this file: https://scout.jakvab.se/llms.txt