What the agent does
There is no repository. The agent reads Ahrefs through the connection, then reads the site itself to pick a redirect. The catalog entry for Ahrefs says it queries your Ahrefs SEO data, uses your monthly Ahrefs API units, and needs a Lite plan or higher. The remote is https://api.ahrefs.com/mcp/mcp and the catalog marks it oauth. Connect it with POST /me/connections, type mcp, name ahrefs, that url, and auth mode oauth, then open authorize_url while signed in to the console as the key's creator. The run names that connection. Units spent are units on your Ahrefs plan, and the file should say that a large domain can spend a lot of them.
The query is backlinks whose target URL returns 404. The agent asks the connection for those backlinks and keeps, for each broken URL, the number of referring domains. It does not pull every backlink on the domain and then guess which are broken. A URL that redirects already, or that returns 200, is not a row. The prompt's subject is the broken target. Referring domains are the sort key, because a 404 with one link is not the same job as a 404 with many.
The redirect target is not an Ahrefs field. The agent reads the site, with the browser in the sandbox, and chooses the best existing page on the same domain: the closest live parent, or the page that now covers the same topic. It does not invent a URL that the site does not serve. When no page is a fair target, the CSV leaves the target blank and the summary says why. The agent does not log into a host, edit DNS, or add the redirect. The file is a map for someone who can.
Two files come back. broken-links.csv has the broken URL, the number of referring domains, and the proposed target. broken-links.md summarizes the top 20 by referring domains, with a sentence on why that target was chosen. Both cite what the connection returned. A row with no referring-domain count is omitted rather than filled with zero, because zero and unknown are different.
Start it with one API call
POST https://api.prix.dev/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Use the Ahrefs connection to read backlinks whose target page returns 404, for the domain named in this task. Write broken-links.csv with the broken URL, the number of referring domains, and the best existing page on the same domain to redirect it to. Find that page by reading the site. Write broken-links.md summarizing the top 20 by referring domains, with a sentence on each target. Leave the target blank when no live page fits, and say so. Do not add the redirects. Do not invent referring-domain counts. Remind the reader that these calls spend Ahrefs API units."
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.prix.dev/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is two artifacts, broken-links.csv and broken-links.md. Each has a name, a mime type and a url that downloads with no key until url_expires_at. GET /o/{org}/sessions/{id}/artifacts/broken-links.csv with the key returns the CSV after that. The transcript shows the Ahrefs calls and the pages the agent opened on the site while choosing targets.
The CSV is the map: one broken URL per row, referring domains, and a target that exists on the domain or an empty target. The markdown file is the top 20 of that CSV, not a second opinion with different numbers. No redirect is configured anywhere. There is no pull request, because resources names no repository.
A reviewer opens the first five targets and checks that each URL responds and that the topic is the one the summary describes. A target that 404s, or a referring-domain number that the transcript does not support, is a follow-up on the same session. POST /o/{org}/sessions/{id}/messages once the turn is finished. The agent rewrites the two files. It does not publish a redirect.
Run it on every weekly crawl
Once a week your server POSTs this body to https://api.prix.dev/o/{org}/sessions, with the domain written into input and connections set to the Ahrefs connection's name or id. Do not send resources. An Idempotency-Key of the domain plus the week keeps a retry from spending the units twice. A connection that is not connected yet is 422 CONNECTION_NOT_READY.
The webhook run.completed carries session_url. Download both artifacts and hand the CSV to whoever adds redirects. max_concurrent is 4 by default. A weekly pass over many domains should be a queue, both because of that limit and because each domain spends Ahrefs API units.
The use case this job follows, with its automation and trigger: Produce a report or file, no repo.
Why run it on Rush?
Finding a 404 that still has backlinks means an Ahrefs query and then a look at the live site for a page that should inherit the link. Those are two tools and a spreadsheet in between. The agent does both in one sandbox: the Ahrefs connection for the broken URLs and the referring domains, the browser for the target page, and the CSV as the result.
The transcript keeps the queries and the pages, so a redirect map is checkable before anyone edits the server. The units spent are on your Ahrefs plan, which is why the file says so and why the weekly job is one domain per session rather than an unbounded crawl. A follow-up can fix five bad targets without running the query again.
Frequently asked questions
Does this spend Ahrefs API units?
Yes. The catalog says the connection uses your monthly Ahrefs API units and needs a Lite plan or higher. The prompt tells the agent to say that in the summary. A weekly run on a large domain can use a meaningful share of the month. The Idempotency-Key is what stops a retried webhook from spending them again.
Where do I put the connection and the domain?
Add connections with the name or id from GET /me/connections. The remote you connected is https://api.ahrefs.com/mcp/mcp with auth mode oauth. Write the domain into input. The JSON on this page has the task and not the connection, because a key run only receives connections it names. A missing name means the agent cannot read Ahrefs.
Will it add the redirects on my site?
No. The CSV is a map. The agent reads the site to choose a live URL and does not change DNS, the CDN or the app. Adding the redirect is a later change in the repository that serves the domain, if you want that as its own session with resources set to that repository.
What if the best target is unclear?
The target cell is left blank and broken-links.md says why. The agent does not point the row at the homepage to fill the column. A blank target is a row a person decides. Referring domains are still filled from Ahrefs, so the blank rows sort with the rest.
Can it include backlinks that already redirect?
No. The query is targets that return 404. A URL that already 301s is not broken in the sense this file means. If you want chains that end at a 404, say that in the prompt. The default file would mix two jobs and the top 20 would be harder to act on.