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:
| Variable | Value |
|---|---|
PRAXIS_URL | The origin of the API your access was issued for, without a trailing slash |
PRAXIS_TOKEN | An 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
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
curl "$PRAXIS_URL/api/v1/intelligence/meta" \
-H "Authorization: Bearer $PRAXIS_TOKEN"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
curl "$PRAXIS_URL/api/v1/intelligence/view?theme=energy-resources®ion=mena&window=90" \
-H "Authorization: Bearer $PRAXIS_TOKEN"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:
| Field | Content |
|---|---|
revision | The data revision the response was computed from |
lens | The lens after defaults, with asOf always present |
methodology.version | The methodology release that computed it |
methodology.fingerprint | The 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.
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®ion=mena&window=90" \
-H "Authorization: Bearer $PRAXIS_TOKEN"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
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
- Authentication: tokens, capabilities and browser sessions.
- Conventions: caching, pagination and limits.
- Errors: every problem code and how to handle it.
- Model Context Protocol: the same reads as tools for AI agents.