For coding agents
The short version of the Rankfield docs for coding agents: base URL, auth, the endpoint to pick for each task, timeouts and gotchas.
Read this page first when you write code against Rankfield. Every link has a Markdown copy: add .md to the URL, or send Accept: text/markdown. The full index is llms.txt; everything in one file is llms-full.txt.
Basics
- Base URL:
https://rankfield.dev/v1/. JSON in, JSON out. - Auth:
Authorization: Bearer <key>on every request. One key works everywhere. Keys start withls_and do not expire. - No key yet:
POST https://rankfield.dev/v1/keyswith the headerOrigin: https://rankfield.devreturns one inkey. Never print it or commit it. - No SDK: use any HTTP client. No CORS: call from a server or script, not browser JavaScript.
Pick the endpoint
| Task | Request |
|---|---|
| How strong is a domain's link profile? | GET /v1/domains/{domain}/site-strength |
| How many domains link to it, and the strongest 20? | GET /v1/domains/{domain}/referring-domains |
| Every domain that links to it | GET /v1/domains/{domain}/referrers, follow nextCursor |
| Every domain it links to | GET /v1/domains/{domain}/outbound-domains |
| A huge list as a file | POST /v1/jobs {"kind":"referrers-export","domain":"…"} |
| The links on a live page | GET /v1/html/link-extraction?url=… |
| A page as Markdown with metadata, links and structured data | GET /v1/scrape?url=… |
| The language of a live page | GET /v1/scrape?url=…&include=language |
| Which crawlers and AI bots may read a page | GET /v1/bot-view?url=… |
| A company's logo, colours and fonts | GET /v1/brand?domain=… |
| Every URL of a site | GET /v1/map?domain=… |
| Bing autocomplete for a keyword | GET /v1/bing/suggest?query=… |
| DuckDuckGo autocomplete | GET /v1/ddg/suggest?query=… |
| Yahoo search predictions | GET /v1/yahoo/search-predictions?query=… |
For more than a handful of URLs or keywords, use the endpoint's /jobs path: see Batch jobs.
Timeouts
| Request | Typical time | Client timeout |
|---|---|---|
| Site Strength, referring domains, lists, profile | Under 1 second | 10 seconds |
| Export jobs | Seconds to minutes, by list size | Poll every 5 seconds |
| Link Extraction (one page) | A few seconds | 90 seconds (the request waits up to wait, 60 by default) |
| Suggest (one keyword) | Under 1 second | 15 seconds |
| Scrape, Bot View and Brand | A few seconds | timeout + 5 seconds (20 by default) |
| Map | Seconds; large sites longer | timeout + 5 seconds (30 by default) |
Gotchas
nullmeans unknown, never zero. Keep it as missing data."inGraph": false(with zeros) from the graph endpoints means the domain isn't in our link graph yet: not "site offline", and not a measured zero. The field is absent otherwise; a malformed domain gets400.- A website's own
404or500is not an error from us: it is in the answer'sstatusfield (or a422for the page endpoints). - Error bodies differ by family:
erroris an object withmessage(andcodeon newer endpoints), or a string on the suggest endpoints. Readtypeof body.error === "string" ? body.error : body.error.message. - Retry only
429,503,504(afterRetry-After) and502. See Errors. - Page endpoints read HTML without running JavaScript. Pages built by scripts show little content; that is the page, not a bug.
- Job results arrive in completion order. Use
positionorindexto match them to your input. - Cursors are opaque. Pass them back unchanged, with the same filters.