Atlas

Appearance

anchors ​

57 endpoints at a glance
MethodPathSummary
GET/anchor-measurements/List Anchor Measurements
GET/anchor-measurements/{am_id}/Get Anchor Measurement
POST/anchor-measurements/admin/clear/Clear Collection
POST/anchor-measurements/admin/refresh/runRun Refresh
GET/anchor-measurements/admin/runs/List Admin Runs
GET/anchor-measurements/admin/stats/Get Admin Stats
GET/anchor-measurements/by-anchor/{anchor_id}/List For Anchor
GET/anchors-health/List Problem Anchors
GET/anchors-health/{anchor_id}/Get Anchor Health
GET/anchors-health/{anchor_id}/explain/{issue_key}Get Issue Explanation
POST/anchors-health/{anchor_id}/explain/{issue_key}Generate Issue Explanation
POST/anchors-health/{anchor_id}/fix-duplicate-measurements/Fix Duplicate Measurements
POST/anchors-health/{anchor_id}/reverify-capabilities/Reverify Capabilities
POST/anchors-health/admin/clear/Clear Collections
GET/anchors-health/admin/runs/List Admin Runs
GET/anchors-health/admin/stats/Get Admin Stats
GET/anchors-health/dns/List Anchors Dns
GET/anchors-health/dns/{anchor_id}/Get Anchor Dns
POST/anchors-health/dns/{anchor_id}/recheck/Recheck Anchor Dns
POST/anchors-health/dns/recheck-stale/runRecheck Stale Dns
GET/anchors-health/dns/stats/Get Anchors Dns Stats
GET/anchors-health/events/List Anchor Health Events
POST/anchors-health/snapshot/runRun Snapshot
GET/anchors-health/stats/Get Anchors Health Stats
GET/anchors-mesh-health/List Problem Anchors
GET/anchors-mesh-health/{anchor_id}/Get Anchor Mesh Health
POST/anchors-mesh-health/admin/clear/Clear Collections
GET/anchors-mesh-health/admin/runs/List Admin Runs
GET/anchors-mesh-health/admin/stats/Get Admin Stats
GET/anchors-mesh-health/events/List Anchor Mesh Health Events
GET/anchors-mesh-health/history/List Mesh Health History
GET/anchors-mesh-health/matrix/Get Mesh Coverage Matrix
GET/anchors-mesh-health/matrix/timestamps/List Mesh Matrix Timestamps
GET/anchors-mesh-health/quality/{anchor_id}/Get Anchor Mesh Quality
POST/anchors-mesh-health/quality/admin/clear/Clear Mesh Quality
GET/anchors-mesh-health/quality/admin/runs/List Mesh Quality Runs
POST/anchors-mesh-health/quality/derive/runRun Mesh Quality Derive
GET/anchors-mesh-health/quality/matrix/Get Mesh Quality Matrix
GET/anchors-mesh-health/quality/stats/Get Mesh Quality Stats
POST/anchors-mesh-health/snapshot/runRun Snapshot
GET/anchors-mesh-health/stats/Get Anchors Mesh Health Stats
GET/anchors-mesh-topology/{cc}/{af}/{date}Get Topology Snapshot
GET/anchors-mesh-topology/{cc}/{af}/{date}/cell/{src_id}/{dst_id}/tracerouteGet Topology Cell Traceroute
GET/anchors-mesh-topology/{cc}/{af}/datesList Topology Dates
GET/anchors-mesh-topology/{cc}/{af}/latestGet Topology Latest
GET/anchors-mesh-topology/countriesList Topology Countries
GET/anchors/{anchor_id}/changes/Get Anchor Changes
GET/anchors/v2/List Anchors Mongo
GET/anchors/v2/{anchor_id}/Get Anchor Mongo
GET/anchors/v2/by-probe/{probe_id}/Get Anchor By Probe
GET/anchors/v2/tags/List Anchor Tags
POST/atlas/anchor-measurements/refresh/Refresh Anchor Measurements
POST/atlas/anchors-dns/snapshot/Snapshot Anchors Dns
POST/atlas/anchors-health/snapshot/Snapshot Anchors Health
POST/atlas/anchors-mesh-health/snapshot/Snapshot Anchors Mesh Health
POST/atlas/anchors/refresh/Refresh Anchors
POST/atlas/mesh-quality/derive/Derive Mesh Quality

anchors​

Retrieve information about RIPE Atlas anchors

List Anchors Mongo​

GET
/anchors/v2/

Mongo-backed anchor list, served from db.anchors. Same
wire shape as the legacy GET /anchors/ so callers can swap
one path for the other.

Server-side filters are scoped to what the existing UI sends —
hostname (substring), country (cca2 exact-match),
region (a slug from db.regions that expands into a
country IN [...] filter), and dnsmon (the "DNSMON only"
toggle — restricts to anchors currently in db.anchors_dnsmon;
this one can't be done client-side since DNSMON membership
isn't on the anchor doc). The rest of the filter set is offered
for third-party callers that want to narrow without round-
tripping the full set; the frontend's AnchorListView does the
remaining filtering client-side after one fetch.

Parameters​

Query Parameters

limit
Type
integer
Default
2500
hostname
country
region
decommissioned
status_
asn
tag
firmware
dnsmon

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Variables
Key
Value

Samples​

List Anchor Tags​

GET
/anchors/v2/tags/

Distinct {slug, name} pairs across the tags carried by
every anchor's underlying probe. Powers the tag dropdown in the
anchor-list view; declared before /v2/{anchor_id}/ so the
literal tags segment doesn't get matched as an int id.

Responses​

Successful Response

application/json
JSON
[
  
{
  
  
"additionalProperties": "string"
  
}
]

Playground​

Samples​

Get Anchor By Probe​

GET
/anchors/v2/by-probe/{probe_id}/

Reverse-lookup: the anchor whose underlying probe matches
probe_id. Powers the probe-lookup view's "Anchor" chip click-
through, where the probe id is what's in scope but the anchor
detail page is keyed by anchor id.

Declared before /v2/{anchor_id}/ so the literal
by-probe segment doesn't get matched as an int id. Returns
404 when no anchor exists for the probe (typical case for
non-anchored probes).

Parameters​

Path Parameters

probe_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Variables
Key
Value

Samples​

Get Anchor Mongo​

GET
/anchors/v2/{anchor_id}/

Single-anchor fetch by id, served from db.anchors.

Parameters​

Path Parameters

anchor_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Variables
Key
Value

Samples​

Get Anchor Changes​

GET
/anchors/{anchor_id}/changes/

Most-recent-first change events for an anchor from
db.anchors_history.

Logged-in only — matches GET /probes/{id}/changes/. Each row
is one refresh-tick where at least one tracked field of the
anchor envelope changed; the embedded probe sub-key is
deliberately excluded from the diff (probe changes live in
db.probes_history).

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Query Parameters

since_ts
until_ts
skip
Type
integer
Default
0
limit
Type
integer
Default
100

Responses​

Successful Response

application/json
JSON
[
  
{
  
  
"additionalProperties": "string"
  
}
]

Playground​

Headers
Variables
Key
Value

Samples​

Get Anchors Health Stats​

GET
/anchors-health/stats/

Top-of-page summary: counts + per-issue breakdown + last
snapshot timestamp. Drives the dashboard's summary tile row.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Anchor Health Events​

GET
/anchors-health/events/

Paginated event feed (newest first). All filters AND-compose.

Used by the dashboard's "Recent events" card and the per-anchor
timeline panel on the AnchorDetailView Health tab.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

since
until
anchor_id
issue_key
state

Filter on event state.

limit
Type
integer
Default
50
offset
Type
integer
Default
0

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Run Snapshot​

POST
/anchors-health/snapshot/run

Cookie-auth manual snapshot trigger.

Same operation as the api-key-gated
POST /atlas/anchors-health/snapshot/ in api/main.py —
duplicated here so the dashboard "Run snapshot now" button can
fire it via the operator's session cookie without needing an
API key. Wrapped in :func:run_and_record so the run lands in
db.task_history alongside the scheduled ones.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

Get Anchors Dns Stats​

GET
/anchors-health/dns/stats/

Summary blob for the admin DNS section: per-overall-verdict
counts (ok / mismatch / error), total, TTL + drain cap, and the
newest / oldest stored-check timestamps (drain freshness).

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Anchors Dns​

GET
/anchors-health/dns/

Paginated stored DNS results, newest-checked first. Optional
?overall=mismatch narrows to the failing anchors (backs the
admin "show mismatches" table).

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

overall

Filter on the overall DNS verdict.

limit
Type
integer
Default
50
offset
Type
integer
Default
0

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Recheck Stale Dns​

POST
/anchors-health/dns/recheck-stale/run

Cookie-auth bulk "re-check stale now" burst — re-resolves every
anchor whose stored result is missing/older than the TTL
(oldest-first), server-clamped to MANUAL_MAX. Same op as the
api-key POST /atlas/anchors-dns/snapshot/; duplicated here so
the admin button works on the session cookie. Wrapped in
:func:run_and_record so the run lands in db.task_history
alongside the scheduled drain (trigger="manual").

Parameters​

Header Parameters

authorization
x-api-key

Request Body​

application/json
JSON
{
  
"max_anchors": 0
}

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Body

Samples​

Get Anchor Dns​

GET
/anchors-health/dns/{anchor_id}/

Stored DNS-resolution result for one anchor. Powers the
AnchorDetailView Health-tab "DNS resolution" panel. 404 when the
anchor hasn't been DNS-checked yet (the UI then shows a "not
checked yet" placeholder + offers the re-lookup button).

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Recheck Anchor Dns​

POST
/anchors-health/dns/{anchor_id}/recheck/

Resolve + persist one anchor's FQDN right now (the per-anchor
"Re-lookup DNS now" button), returning the refreshed stored doc —
same shape as GET /dns/{anchor_id}/. 404 when there's no such
anchor in db.anchors (nothing to resolve). One live resolve
(A + AAAA); off-loaded to a worker thread so the slow network call
never blocks the event loop.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

List Problem Anchors​

GET
/anchors-health/

Paginated list of active anchors currently carrying issues.

Optional ?issue=<key> narrows to anchors with that specific
issue. Joined hostname / country / probe description is inlined
on each result row so the dashboard table doesn't need a
per-row fetch.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

issue
limit
Type
integer
Default
50
offset
Type
integer
Default
0
sort

recent = most-recently-changed first; oldest = longest-stable first

Type
string
Valid values
"recent""oldest"
Default
"recent"

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Get Issue Explanation​

GET
/anchors-health/{anchor_id}/explain/{issue_key}

Cached guidance for this anchor's issue, or explanation: null.

A pure read — it never generates, so a dashboard render can't trigger
an upstream call. A miss simply means the UI offers Generate.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required
issue_key*
Type
string
Required

Query Parameters

model

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Generate Issue Explanation​

POST
/anchors-health/{anchor_id}/explain/{issue_key}

Generate guidance for this issue class (fire-and-forget).

Backgrounded; poll the GET. Because the cache key is the context
shape, this usually benefits every other anchor in the same state
too — and is a no-op cache hit if one of them already paid for it.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required
issue_key*
Type
string
Required

Request Body​

application/json
JSON
{
  
"model": "string",
  
"force": false
}

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value
Body

Samples​

Get Admin Stats​

GET
/anchors-health/admin/stats/

Combined run-stats + collection-size blob for the admin panel.

One call returns everything the top-of-page tiles need: task_history
aggregations (totals, last run, success rate, durations) plus the
current sizes of both health collections. Lets the admin view
render in one round-trip.

Both sub-queries run in parallel worker threads via
:func:asyncio.to_thread so the FastAPI event loop stays
responsive and a slow task_history aggregation can't stall
the smaller collection-stats counts behind it. Without the
threading wrap the route would block on a string of synchronous
PyMongo round-trips and could overrun the 15 s client timeout
on cold/large databases.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Admin Runs​

GET
/anchors-health/admin/runs/

Recent runs of the snapshot task with their full counters blob.

Drives the admin panel's "Recent runs" table. Limit capped server-
side at 200 — bigger pulls should go through AdminTaskHistoryView
which paginates properly.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

limit
Type
integer
Default
50

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Clear Collections​

POST
/anchors-health/admin/clear/

Wipe db.anchors_health + db.anchors_health_events.

Destructive — the next snapshot tick repopulates the state
collection from scratch (and emits a fresh opened event for
every currently-firing issue, since the diff path sees no prior
state). db.task_history is intentionally untouched; the
audit trail of past runs survives a clear.

Requires confirm: true in the body so a stale fetch or a
misclick doesn't take out the snapshot history.

Parameters​

Header Parameters

authorization
x-api-key

Request Body​

application/json
JSON
{
  
"confirm": false
}

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Body

Samples​

Get Anchor Health​

GET
/anchors-health/{anchor_id}/

Current state + recent events for one anchor.

Powers the AnchorDetailView "Health" tab. Returns 404 when the
anchor has no health record yet (never been snapshotted — e.g.
a brand-new anchor before the first cron tick after its
creation).

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Query Parameters

events_limit
Type
integer
Default
50

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Reverify Capabilities​

POST
/anchors-health/{anchor_id}/reverify-capabilities/

Recompute + persist the missing_required_system_tags
capability verification for one anchor (both directions), so an
operator needn't wait for the next scheduled snapshot. Returns
the refreshed Health-tab payload (same shape as
GET /{anchor_id}/).

404 when the anchor has no health record, no such open issue, no
verifiable works tag in missing, or its anchor doc is gone —
in every one of those cases there is nothing to verify. DB-only;
no RIPE.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Fix Duplicate Measurements​

POST
/anchors-health/{anchor_id}/fix-duplicate-measurements/

Stop the redundant measurements behind an anchor's
duplicate_anchor_measurement issue.

Admin-gated — it presents a privileged DELETE key to RIPE — and
audited via :func:run_and_record so the run lands in
db.task_history alongside the scheduled jobs. The stop list
is re-derived server-side from the persisted health state
(the client can't pick which measurements get stopped); for every
duplicated cell the lowest measurement_id is kept and the rest
stopped, best-effort per id. The next snapshot tick re-evaluates
and closes the issue. Returns the
:meth:AnchoringMutations.fix_duplicate_anchor_measurements
summary.

400 when there is no state doc or no open duplicate issue —
nothing to fix.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Get Mesh Coverage Matrix​

GET
/anchors-mesh-health/matrix/

N×N coverage matrix for the operator-facing mesh-matrix view.

Without ?at=: returns the most recent snapshot.
With ?at=<unix-seconds>: returns the snapshot with the
highest snapshot_ts that's <= at. Operator-friendly
"show me state at this point in time" semantics — daily-cadence
snapshots always resolve to something visible even when the
requested instant doesn't match a snapshot exactly.

Returns 404 when no snapshot has produced a matrix yet, or
when at is before the first available snapshot.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

at

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

List Mesh Matrix Timestamps​

GET
/anchors-mesh-health/matrix/timestamps/

List every available matrix-snapshot timestamp, newest-first.

Drives the time picker on the matrix view. Bounded by the
server-side retention window (~90 entries at daily cadence).

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Mesh Health History​

GET
/anchors-mesh-health/history/

Per-snapshot aggregate metrics — drives the coverage-trend
chart on the mesh-health dashboard.

Each row carries headline counts (active / connected / eligible
/ with-issues / open-issues) plus coverage roll-ups
(cells_expected / cells_covered / fully_covered_pairs /
partial_pairs / missing_pairs / coverage_pct). since /
until clamp the window; limit caps response size.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

since
until
limit
Type
integer
Default
90

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Get Anchors Mesh Health Stats​

GET
/anchors-mesh-health/stats/

Top-of-page summary: counts + per-issue breakdown.

Drives the mesh-health dashboard's summary tile row. The shape
mirrors the regular anchor-health stats endpoint, with two
per_issue_counts keys (mesh_inbound_coverage_gap and
mesh_outbound_coverage_gap) zero-filled when no anchors
carry the respective issue.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Anchor Mesh Health Events​

GET
/anchors-mesh-health/events/

Paginated event feed (newest first). All filters AND-compose.

Used by the dashboard's "Recent events" card and the per-anchor
mesh timeline on AnchorDetailView. issue_key is validated
against :data:MESH_ISSUE_RULES so a typo returns 400 instead
of an empty list.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

since
until
anchor_id
issue_key
state

Filter on event state.

limit
Type
integer
Default
50
offset
Type
integer
Default
0

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Run Snapshot​

POST
/anchors-mesh-health/snapshot/run

Cookie-auth manual snapshot trigger.

Same operation as the api-key-gated
POST /atlas/anchors-mesh-health/snapshot/ in api/main.py
— duplicated here so the dashboard "Run snapshot now" button
can fire it via the operator's session cookie without needing
an API key. Wrapped in :func:run_and_record so the run lands
in db.task_history alongside the scheduled ones, tagged
with trigger="manual".

Synchronous from the HTTP perspective — the pipeline is pure
set-math against pre-loaded Mongo data (no upstream RIPE
calls), completes in seconds, no need for fire-and-forget.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Problem Anchors​

GET
/anchors-mesh-health/

Paginated list of active anchors currently carrying mesh
issues.

Optional ?issue=<key> narrows to anchors carrying that
specific issue (one of the two mesh rules).

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

issue
limit
Type
integer
Default
50
offset
Type
integer
Default
0
sort

recent = most-recently-changed first; oldest = longest-stable first

Type
string
Valid values
"recent""oldest"
Default
"recent"

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Get Admin Stats​

GET
/anchors-mesh-health/admin/stats/

Combined run-stats + collection-size blob for the admin panel.

One call returns everything the top-of-page tiles need:
task_history aggregations (totals, last run, success rate,
durations) plus the current sizes of both mesh-health
collections. Same response shape as the regular anchors-health
admin endpoint so the frontend can share a component.

Both sub-queries run in parallel worker threads via
:func:asyncio.to_thread so the FastAPI event loop stays
responsive and a slow task_history aggregation can't stall
the smaller collection-stats counts behind it. Without the
threading wrap the route would block on a string of synchronous
PyMongo round-trips and routinely overrun the 15 s client
timeout on cold/large databases.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Admin Runs​

GET
/anchors-mesh-health/admin/runs/

Recent runs of the mesh-health snapshot task with their full
counters blob. Drives the admin panel's "Recent runs" table.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

limit
Type
integer
Default
50

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Clear Collections​

POST
/anchors-mesh-health/admin/clear/

Wipe db.anchors_mesh_health +
db.anchors_mesh_health_events.

Destructive — the next snapshot tick repopulates the state
collection from scratch (and emits a fresh opened event for
every currently-firing issue, since the diff path sees no prior
state). db.task_history is intentionally untouched.

Requires confirm: true in the body so a stale fetch or a
misclick doesn't take out the mesh-snapshot history.

Parameters​

Header Parameters

authorization
x-api-key

Request Body​

application/json
JSON
{
  
"confirm": false
}

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Body

Samples​

Get Mesh Quality Stats​

GET
/anchors-mesh-health/quality/stats/

Summary blob: per-signal counts + freshness for the mesh-quality
section (link-unreachable / v6-broken / geo-impossible / NAT /
regressions, plus link & watchlist totals).

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

Get Mesh Quality Matrix​

GET
/anchors-mesh-health/quality/matrix/

Directed link facts (RTT / loss / reachability per
src→dst,af) for the quality heatmap layer on the mesh-matrix
view. Server-capped.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

af

Restrict to one address family.

limit
Type
integer
Default
5000

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Run Mesh Quality Derive​

POST
/anchors-mesh-health/quality/derive/run

Cookie-auth manual re-derive. Same op as the api-key
POST /atlas/mesh-quality/derive/ — duplicated so the dashboard
button works on the session cookie. Pure DB; idempotent.
run_and_record-wrapped so it lands in db.task_history.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Mesh Quality Runs​

GET
/anchors-mesh-health/quality/admin/runs/

Recent derive_mesh_quality runs from db.task_history.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

Clear Mesh Quality​

POST
/anchors-mesh-health/quality/admin/clear/

Wipe the five mesh_* derived collections. Destructive — the
next derive rebuilds the snapshot from scratch; per-anchor +
watchlist history is lost. task_history untouched. Requires
confirm: true.

Parameters​

Header Parameters

authorization
x-api-key

Request Body​

application/json
JSON
{
  
"confirm": false
}

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Body

Samples​

Get Anchor Mesh Quality​

GET
/anchors-mesh-health/quality/{anchor_id}/

Per-anchor mesh-quality rollup (inbound/outbound reach+latency
per AF, v4/v6 parity, asymmetry, NAT/geo/staleness flags,
regression/path/flap verdicts). Powers the AnchorDetailView
"Mesh quality" panel. 404 when the anchor hasn't been derived yet
(e.g. before the first derive, or no mesh links).

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Get Anchor Mesh Health​

GET
/anchors-mesh-health/{anchor_id}/

Current mesh-health state + recent events for one anchor.

Powers the AnchorDetailView "Mesh health" card. Returns 404
when the anchor has no mesh-health record yet (never been
snapshotted — e.g. a brand-new anchor before the first cron
tick after its creation).

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

anchor_id*
Type
integer
Required

Query Parameters

events_limit
Type
integer
Default
50

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

List Topology Countries​

GET
/anchors-mesh-topology/countries

Countries that carry at least one snapshot, with their
newest-date + a summary cell-tally per country+AF. Drives the
country picker on the public topology view.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

Get Topology Latest​

GET
/anchors-mesh-topology/{cc}/{af}/latest

Newest snapshot for cc/af. 404 when no snapshot has
ever been built for this country+AF (typically: below the
MIN_CONNECTED_ANCHORS threshold, or first build still
pending the next cron tick).

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

cc*
Type
string
Required
af*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

List Topology Dates​

GET
/anchors-mesh-topology/{cc}/{af}/dates

Newest-first list of dates with a snapshot — drives the date
picker on the public topology view.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

cc*
Type
string
Required
af*
Type
integer
Required

Query Parameters

limit
Type
integer
Default
365

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Get Topology Snapshot​

GET
/anchors-mesh-topology/{cc}/{af}/{date}

Specific historical snapshot by natural key. 404 when the
requested date has no snapshot.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

cc*
Type
string
Required
af*
Type
integer
Required
date*
Type
string
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Get Topology Cell Traceroute​

GET
/anchors-mesh-topology/{cc}/{af}/{date}/cell/{src_id}/{dst_id}/traceroute

Raw RIPE traceroute envelope for one matrix cell — the source
of truth behind the derived per-cell metrics. Drives the public
UI's click-to-pin :component:TracerouteResult panel under the
matrix.

The body shape::

{
  "envelope":   <verbatim RIPE /latest/ row — RipeLatestResult>,
  "src_msm":    <int>,
  "src_anchor": {id, fqdn, city, asn, ...} | null,
  "dst_anchor": {id, fqdn, city, asn, ...} | null,
  "cell":       <topology-cell sub-doc with reached / hops /
                 in_country / as_path / ixp_hops / ...>
}

404 when the snapshot doesn't exist, either anchor isn't on the
matrix, or the cell row is null (diagonal / no envelope). The
envelope itself can also have aged out of
measurements_probes between snapshot and click — same 404
outcome since there's nothing to render.

Parameters​

Header Parameters

authorization
x-api-key

Path Parameters

cc*
Type
string
Required
af*
Type
integer
Required
date*
Type
string
Required
src_id*
Type
integer
Required
dst_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

List Anchor Measurements​

GET
/anchor-measurements/

Paginated catalog list. All filters AND-compose. Hides
tombstoned rows by default (admin can see them via the admin
listing if needed).

Parameters​

Query Parameters

anchor_id
measurement_id
type
is_mesh
search
limit
Type
integer
Default
100
offset
Type
integer
Default
0

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Variables
Key
Value

Samples​

List For Anchor​

GET
/anchor-measurements/by-anchor/{anchor_id}/

All measurements pinned to a specific anchor — typically 5–10
rows. Drives the AnchorDetailView "Measurements" tab. Each row
carries measurement_status_id / measurement_status_name /
measurement_last_result_time from a $lookup against
db.measurements_meta so the rendered list shows live status
without a second round-trip.

Parameters​

Path Parameters

anchor_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Variables
Key
Value

Samples​

Get Admin Stats​

GET
/anchor-measurements/admin/stats/

Combined run-stats + collection-stats blob for the admin panel.

Both sub-queries run in parallel worker threads via
:func:asyncio.to_thread so the FastAPI event loop stays
responsive — without it the sequential synchronous PyMongo
round-trips could overrun the 15 s client timeout on a slow
Mongo. See the matching anchors-mesh-health/admin/stats/
endpoint for the full rationale.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

List Admin Runs​

GET
/anchor-measurements/admin/runs/

Last N task_history rows for the refresh task.

Parameters​

Header Parameters

authorization
x-api-key

Query Parameters

limit
Type
integer
Default
50

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Variables
Key
Value

Samples​

Run Refresh​

POST
/anchor-measurements/admin/refresh/run

Cookie-auth manual refresh trigger. Same operation as the
api-key-gated POST /atlas/anchor-measurements/refresh/ in
api/main.py — duplicated here so the admin panel's
"Run refresh now" button can fire it via the operator's
session cookie without needing an API key. Wrapped in
:func:run_and_record so the run lands in db.task_history
alongside the scheduled ones.

Parameters​

Header Parameters

authorization
x-api-key

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers

Samples​

Clear Collection​

POST
/anchor-measurements/admin/clear/

Wipe db.anchor_measurements.

Destructive — the next refresh tick repopulates from RIPE.
db.task_history is not touched. Requires confirm: true
in the body.

Parameters​

Header Parameters

authorization
x-api-key

Request Body​

application/json
JSON
{
  
"confirm": false
}

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Headers
Body

Samples​

Get Anchor Measurement​

GET
/anchor-measurements/{am_id}/

Parameters​

Path Parameters

am_id*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Variables
Key
Value

Samples​

Refresh Anchors​

POST
/atlas/anchors/refresh/

Pull every anchor from RIPE Atlas and upsert into db.anchors.

Synchronous from the caller's perspective — the request blocks
for the duration of the refresh (~10 s for ~1700 anchors). Used
as a bootstrap on a fresh deploy and as a manual recovery handle
when the hourly job fails. Returns the summary dict from
:meth:Anchors.refresh_all.

Routed through :func:run_and_record so this manual run lands
in db.task_history next to the scheduled ones, distinguishable
by the trigger="manual" field.

Authorizations​

APIKeyQuery
Type
API Key (query: api-key)
or
APIKeyHeader
Type
API Key (header: x-api-key)

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Authorization

Samples​

Refresh Anchor Measurements​

POST
/atlas/anchor-measurements/refresh/

Pull RIPE's anchor-measurement catalog and reconcile
db.anchor_measurements now.

Synchronous from the caller's perspective (~10 s for ~10k rows).
Used as a bootstrap on a fresh deploy + as the manual recovery
handle when the 6-hourly job fails. Returns the summary dict
from :meth:AnchorMeasurements.refresh_all.

Routed through :func:run_and_record so this manual run lands
in db.task_history alongside the scheduled ones,
distinguishable by the trigger="manual" field.

Authorizations​

APIKeyQuery
Type
API Key (query: api-key)
or
APIKeyHeader
Type
API Key (header: x-api-key)

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Authorization

Samples​

Snapshot Anchors Health​

POST
/atlas/anchors-health/snapshot/

Run the anchor-health snapshot pass now.

Evaluates every active anchor against the issue-rule registry
(see :mod:api.atlas.anchors_health), upserts current state into
db.anchors_health, and appends state-transition events to
db.anchors_health_events. Manual companion to the hourly
snapshot_anchors_health cron — bootstrap on a fresh deploy
(the next cron tick can be up to an hour away) or recover after
an outage.

Routed through :func:run_and_record so the run lands in
db.task_history next to the scheduled ones, distinguishable
by the trigger="manual" field.

Authorizations​

APIKeyQuery
Type
API Key (query: api-key)
or
APIKeyHeader
Type
API Key (header: x-api-key)

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Authorization

Samples​

Snapshot Anchors Mesh Health​

POST
/atlas/anchors-mesh-health/snapshot/

Run the mesh-health snapshot pass now.

Evaluates every active anchor against the mesh-coverage rules
(see :mod:api.atlas.anchors_mesh_health), upserts current
state into db.anchors_mesh_health, and appends state-
transition events to db.anchors_mesh_health_events. Manual
companion to the daily snapshot_anchors_mesh_health cron —
bootstrap on a fresh deploy or recover after an outage.

The pipeline is pure set-math against pre-loaded Mongo data
(no upstream RIPE calls), so it completes in seconds even
across ~700 anchors and a few thousand mesh measurements; a
synchronous response is fine here, no fire-and-forget needed.

Routed through :func:run_and_record so the run lands in
db.task_history next to the scheduled ones, distinguishable
by the trigger="manual" field.

Authorizations​

APIKeyQuery
Type
API Key (query: api-key)
or
APIKeyHeader
Type
API Key (header: x-api-key)

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Authorization

Samples​

Derive Mesh Quality​

POST
/atlas/mesh-quality/derive/

Run the mesh-quality derivation now.

Mines db.measurements_probes into directed link facts +
per-anchor quality rollups (see :mod:api.atlas.mesh_quality),
rebuilds db.mesh_links, upserts db.mesh_anchor_quality,
appends the daily history points, and maintains the degraded-link
watchlist. Manual companion to the daily derive_mesh_quality
cron — bootstrap a fresh deploy or re-derive after a
measurements_probes refresh. Pure DB (no RIPE); idempotent +
safe to spam (history rows are keyed by day).

Routed through :func:run_and_record so the run lands in
db.task_history next to the scheduled ones,
trigger="manual".

Authorizations​

APIKeyQuery
Type
API Key (query: api-key)
or
APIKeyHeader
Type
API Key (header: x-api-key)

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Authorization

Samples​

Snapshot Anchors Dns​

POST
/atlas/anchors-dns/snapshot/

Run the anchor-FQDN DNS-resolution drain now (bulk burst).

Re-resolves every anchor whose stored db.anchors_dns result is
missing or older than the TTL (oldest-first), up to the
server-side AnchorsDnsSettings.MANUAL_MAX ceiling, and compares
each FQDN's A/AAAA against the anchor / embedded-probe addresses.
Manual companion to the ~20-min snapshot_anchors_dns cron —
bootstrap a fresh deploy or force convergence right after a
deliberate anchor-address change instead of waiting for the drain
to grind through. Idempotent + safe to spam (bounded; a fresh
anchor is a no-op re-resolve).

Routed through :func:run_and_record so the run lands in
db.task_history next to the scheduled ones, distinguishable
by the trigger="manual" field.

Authorizations​

APIKeyQuery
Type
API Key (query: api-key)
or
APIKeyHeader
Type
API Key (header: x-api-key)

Responses​

Successful Response

application/json
JSON
[
]

Playground​

Authorization

Samples​

Atlas — built on RIPE Atlas data.

Blue Sapphire Software