Ahrefs integration
What it is
The keyword and SERP data source that feeds the mesh. GoToMesh talks to the
Ahrefs API directly (not via an MCP) through one CLI surface:
pull. Its demand channel fills the
bag the deterministic loop reads; its serp and
top-pages channels feed the operator skill’s discovery work.
The adapter spec (docs/spec/gtmesh-ahrefs-integration.md) has the full detail
if you are extending it.
Why it matters
Routing every networked provider pull through the gtmesh CLI keeps two things
honest. First, the data lands as immutable, timestamped exports on committed
disk, so plan reads a frozen bag and never re-fetches — a plan is reproducible
from the repo. Second, skills stay provider-agnostic: they ask the CLI for data
rather than reaching out to a provider themselves.
How it works
A pull demand on a root topic runs the two-pull pattern — matching-terms
(the broad keyword expansion) and questions — and writes the result under
data/raw/keywords/ahrefs/. pull demand --keyword, pull serp, and
pull top-pages are the discovery-time pulls that explore a keyword universe, a
SERP, or a competitor’s top pages.
The query shape is config, not code. Under adapters.ahrefs in
gtmesh.config.yaml you set volume_floor, the select columns, the pulls,
and exclude_substrings to strip auth and brand-asset junk. The pull country
is derived from taxonomy.markets — never set it on the adapter. WHICH terms to
pull is graph state, not config: each root topic carries its own seed_terms
(always qualified — a bare crm pulls noise). See
The refresh loop.
One volume_floor can’t serve both pulls: matching-terms needs a floor high
enough to gate head-term noise, but questions are long-tail by nature and a
high floor returns almost nothing on a niche domain. Set a per-pull override so
each pull gets the right floor:
# matching-terms — the head-noise gate
gtmesh config set adapters.ahrefs.volume_floor 100
# questions are long-tail; curate the result with `gtmesh stage admit`
gtmesh config set adapters.ahrefs.pull_overrides.questions.volume_floor 10A pull with no override falls back to the top-level volume_floor.
AHREFS_API_TOKEN comes from the environment, never the config file. No budget?
gtmesh pull demand --source csv --input export.csv imports a CSV instead.
Key files & flags
| Where | What it controls |
|---|---|
gtmesh.config.yaml adapters.ahrefs | volume_floor, pull_overrides (per-pull floors), select, pulls, exclude_substrings |
Root topics in graph/nodes.jsonl | seed_terms (the pull heads) + per-topic exclusions — authored with gtmesh topic add --root |
gtmesh.config.yaml taxonomy.markets | The single source for the pull country |
AHREFS_API_TOKEN (env) | API auth — never committed |
data/raw/keywords/ahrefs/ | The immutable, timestamped exports |
Related
pull— every external pull: demand, SERP, top-pages, and the observation channels- Installation — installing the CLI and setting the token