> ## Documentation index
> Fetch the complete documentation index at: https://rankfield.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/llms.txt); everything in one file is [llms-full.txt](/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 with `ls_` and do not expire.
- No key yet: `POST https://rankfield.dev/v1/keys` with the header `Origin: https://rankfield.dev` returns one in `key`. 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](/docs/get-started/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

- `null` means 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 gets `400`.
- A website's own `404` or `500` is not an error from us: it is in the answer's `status` field (or a `422` for the page endpoints).
- Error bodies differ by family: `error` is an object with `message` (and `code` on newer endpoints), or a string on the suggest endpoints. Read `typeof body.error === "string" ? body.error : body.error.message`.
- Retry only `429`, `503`, `504` (after `Retry-After`) and `502`. See [Errors](/docs/get-started/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 `position` or `index` to match them to your input.
- Cursors are opaque. Pass them back unchanged, with the same filters.