/ahrefs

name: ahrefs
description: |
  Ahrefs integration. Manage Projects. Use when the user wants to interact with Ahrefs data.
compatibility: Requires network access and a valid Membrane account (Free tier supported).
license: MIT
homepage: https://getmembrane.com
repository: https://github.com/membranedev/application-skills
metadata:
  author: membrane
  version: "1.0"
  categories: ""

Ahrefs

Ahrefs is a popular SEO tool suite used by marketers and SEO professionals. It helps users analyze website backlinks, keywords, and overall search engine performance.

Official docs: https://ahrefs.com/api/documentation/v3

Ahrefs Overview

• **Site Explorer**
• **Overview** — Provides a general overview of a website's SEO performance.
• **Referring domains** — Shows domains that link to the target website.
• **Referring pages** — Shows specific pages that link to the target website.
• **Organic keywords** — Lists keywords for which the target website ranks in organic search.
• **Top pages** — Identifies the pages on the target website with the most organic traffic.
• **Content gap** — Finds keywords that competitors rank for, but the target website doesn't.
• **Backlinks** — Displays the backlinks pointing to the target website.
• **Anchors** — Shows the anchor text used in backlinks.
• **Broken backlinks** — Identifies broken backlinks pointing to the target website.
• **Outgoing links** — Lists the links that the target website points to.
• **Paid keywords** — Lists keywords for which the target website advertises.
• **Ads positions** — Shows the ad positions for the target website.
• **Pages** — Lists the pages on the target website.
• **Traffic share** — Shows the distribution of traffic to the target website.
• **Keywords Explorer**
• **Overview** — Provides a general overview of a keyword's SEO performance.
• **Matching terms** — Shows keywords that are similar to the target keyword.
• **Search suggestions** — Provides suggestions for related keywords.
• **Questions** — Lists questions related to the target keyword.
• **Related keywords** — Shows keywords that are related to the target keyword.
• **Also rank for** — Lists keywords that the top-ranking pages for the target keyword also rank for.
• **Ranking history** — Shows the ranking history of the target keyword.
• **Batch Analysis** — Allows analyzing multiple websites at once.
• **Domain Comparison** — Allows comparing multiple websites side-by-side.
• **Content Explorer**
• **Overview** — Provides a general overview of a content topic's SEO performance.
• **Matching terms** — Shows content topics that are similar to the target content topic.
• **Referring domains** — Shows domains that link to content about the target content topic.
• **Top pages** — Identifies the pages about the target content topic with the most organic traffic.
• **SEO Toolbar**
• **Get SEO Metrics** — Retrieves SEO metrics for the current page.

Working with Ahrefs

This skill uses the Membrane CLI to interact with Ahrefs. Membrane handles authentication and credentials refresh automatically — so you can focus on the integration logic rather than auth plumbing.

Install the CLI

Install the Membrane CLI so you can run `membrane` from the terminal:

npm install -g @membranehq/cli@latest

Authentication

membrane login --tenant --clientName=<agentType>

This will either open a browser for authentication or print an authorization URL to the console, depending on whether interactive mode is available.

**Headless environments:** The command will print an authorization URL. Ask the user to open it in a browser. When they see a code after completing login, finish with:

membrane login complete <code>

Add `--json` to any command for machine-readable JSON output.

**Agent Types** : claude, openclaw, codex, warp, windsurf, etc. Those will be used to adjust tooling to be used best with your harness

Connecting to Ahrefs

Use `membrane connection ensure` to find or create a connection by app URL or domain:

membrane connection ensure "https://ahrefs.com" --json

The user completes authentication in the browser. The output contains the new connection id.

This is the fastest way to get a connection. The URL is normalized to a domain and matched against known apps. If no app is found, one is created and a connector is built automatically.

If the returned connection has `state: "READY"`, skip to **Step 2**.

1b. Wait for the connection to be ready

If the connection is in `BUILDING` state, poll until it's ready:

npx @membranehq/cli connection get <id> --wait --json

The `--wait` flag long-polls (up to `--timeout` seconds, default 30) until the state changes. Keep polling until `state` is no longer `BUILDING`.

The resulting state tells you what to do next:

• **`READY`** — connection is fully set up. Skip to **Step 2**.
• **`CLIENT_ACTION_REQUIRED`** — the user or agent needs to do something. The `clientAction` object describes the required action:
• `clientAction.type` — the kind of action needed:
• `"connect"` — user needs to authenticate (OAuth, API key, etc.). This covers initial authentication and re-authentication for disconnected connections.
• `"provide-input"` — more information is needed (e.g. which app to connect to).
• `clientAction.description` — human-readable explanation of what's needed.
• `clientAction.uiUrl` (optional) — URL to a pre-built UI where the user can complete the action. Show this to the user when present.
• `clientAction.agentInstructions` (optional) — instructions for the AI agent on how to proceed programmatically.

After the user completes the action (e.g. authenticates in the browser), poll again with `membrane connection get <id> --json` to check if the state moved to `READY`.

• **`CONFIGURATION_ERROR`** or **`SETUP_FAILED`** — something went wrong. Check the `error` field for details