Docs
Quickstart

Quickstart

Make your first authenticated request, read the situational picture of a lens and pin it to a date and a revision.

This guide takes you from credentials to a reproducible read in five requests. The samples use curl and the fetch built into Node.js, Deno, Bun and browsers; any HTTP client works the same way.

Before you start

Set two variables in your shell:

VariableValue
PRAXIS_URLThe origin of the API your access was issued for, without a trailing slash
PRAXIS_TOKENAn access token from your deployment's identity provider, as Authentication describes

Every operation lives under /api/v1/intelligence. Access tokens are short-lived, so request a fresh one when a call answers 401.

1. Check that the API is ready

Shell
curl -i "$PRAXIS_URL/api/v1/intelligence/health"

The readiness probe is the one operation that needs no credentials. It answers 200 when the database answers, and 503 otherwise.

2. Discover what the deployment holds

Shell
curl "$PRAXIS_URL/api/v1/intelligence/meta" \
  -H "Authorization: Bearer $PRAXIS_TOKEN"
TypeScript
const response = await fetch(
  `${process.env.PRAXIS_URL}/api/v1/intelligence/meta`,
  { headers: { Authorization: `Bearer ${process.env.PRAXIS_TOKEN}` } },
);
const meta = await response.json();

GET /meta returns everything a client needs to render and filter: the controlled vocabularies, the object and link types, the lens defaults, the current data revision as revision, the as-of dates reads accept as limits.asOf, and each source's currency. Read the theme, region and actor IDs your filters use from it.

3. Read the situational picture

Shell
curl "$PRAXIS_URL/api/v1/intelligence/view?theme=energy-resources&region=mena&window=90" \
  -H "Authorization: Bearer $PRAXIS_TOKEN"
TypeScript
const query = new URLSearchParams({
  theme: "energy-resources",
  region: "mena",
  window: "90",
});
const response = await fetch(
  `${process.env.PRAXIS_URL}/api/v1/intelligence/view?${query}`,
  { headers: { Authorization: `Bearer ${process.env.PRAXIS_TOKEN}` } },
);
const view = await response.json();

GET /view is the read model behind every situational surface: the risk register, countries, chokepoints, ports, conflicts, developments, sanctions regimes, indicators and recent alerts. The theme and region filters decide what is visible; they never change a number. The lens, its parameters and their limits are described in The lens.

Every lens-scoped response states what produced it:

FieldContent
revisionThe data revision the response was computed from
lensThe lens after defaults, with asOf always present
methodology.versionThe methodology release that computed it
methodology.fingerprintThe fingerprint that identifies that release's definition

4. Pin the read to a date and a revision

Without asOf and revision, a read uses the latest data as of today, so the same request can answer differently tomorrow. Pass both, and it returns the same numbers for as long as the same methodology release is deployed.

Shell
REVISION=$(curl -s "$PRAXIS_URL/api/v1/intelligence/meta" \
  -H "Authorization: Bearer $PRAXIS_TOKEN" | jq .revision)

curl "$PRAXIS_URL/api/v1/intelligence/view?asOf=2026-06-30&revision=$REVISION&theme=energy-resources&region=mena&window=90" \
  -H "Authorization: Bearer $PRAXIS_TOKEN"
TypeScript
const query = new URLSearchParams({
  asOf: "2026-06-30",
  revision: String(meta.revision),
  theme: "energy-resources",
  region: "mena",
  window: "90",
});
const pinned = await fetch(
  `${process.env.PRAXIS_URL}/api/v1/intelligence/view?${query}`,
  { headers: { Authorization: `Bearer ${process.env.PRAXIS_TOKEN}` } },
);

Store the revision, lens and methodology of every response you keep. They are what Reproducibility needs to compute the same result again.

5. Read a brief as Markdown

Shell
curl "$PRAXIS_URL/api/v1/intelligence/brief?asOf=2026-06-30&revision=$REVISION&format=markdown" \
  -H "Authorization: Bearer $PRAXIS_TOKEN"

GET /brief composes the cited brief of a lens: key judgments in the expressions of likelihood of intelligence estimates, then changes, developments, exposure, armed conflicts, sanctions and the market outlook, each item citing the record it summarizes. With format=markdown it returns Markdown instead of JSON, as GET /dossiers/{id} does for an actor's dossier.

Next steps