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

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Fetch (POST) API reference

> Read up to 20 web pages in one call with POST /v1/fetch: markdown, an answer to a prompt, typed JSON, links and images for each URL.

Read up to 20 pages in one call and get one result for each URL, in the order you sent them. Each result is the page as markdown, or what you asked for instead: an answer to a prompt, a JSON object that matches your schema, the page's links and its images.

The [API reference](https://docs.keenable.ai/api-reference.md) covers the base URL, authentication and the limits every endpoint shares. The SDKs call this endpoint from `fetch`. See [SDK methods](https://docs.keenable.ai/sdks.md#methods).

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable } from "keenable";

async function main() {
  // reads KEENABLE_API_KEY from the environment
  const client = new Keenable();
  const response = await client.fetch(
    [
      "https://www.postgresql.org/support/versioning/",
      "https://nodejs.org/en/about/previous-releases",
    ],
    {
      prompt: "List the supported major versions and when each one stops getting updates, one per line.",
      maxAgeHours: 24, // a stored copy younger than a day, or a live read
    },
  );
  // results[i] is for urls[i]
  for (const page of response.results) {
    if (page.error) {
      console.log("failed:", page.url, page.error.code);
      continue;
    }
    console.log(page.title, page.url);
    console.log(page.content);
  }
}

main();
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
from keenable import Keenable

# reads KEENABLE_API_KEY from the environment
client = Keenable()
response = client.fetch(
    [
        "https://www.postgresql.org/support/versioning/",
        "https://nodejs.org/en/about/previous-releases",
    ],
    prompt="List the supported major versions and when each one stops getting updates, one per line.",
    max_age_hours=24,  # a stored copy younger than a day, or a live read
)
# results[i] is for urls[i]
for page in response.results:
    if page.error:
        print("failed:", page.url, page.error.code)
        continue
    print(page.title, page.url)
    print(page.content)
```

```go Go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/keenableai/keenable-sdk/go"
)

func main() {
	// reads KEENABLE_API_KEY from the environment
	client, err := keenable.New(nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	maxAge := 24.0 // a stored copy younger than a day, or a live read
	resp, err := client.FetchWithOptions(context.Background(),
		[]string{
			"https://www.postgresql.org/support/versioning/",
			"https://nodejs.org/en/about/previous-releases",
		},
		&keenable.FetchOptions{
			Prompt:      "List the supported major versions and when each one stops getting updates, one per line.",
			MaxAgeHours: &maxAge,
		})
	if err != nil {
		log.Fatal(err)
	}
	// Results[i] is for urls[i]
	for _, page := range resp.Results {
		if page.Error != nil {
			fmt.Println("failed:", page.URL, page.Error.Code)
			continue
		}
		fmt.Println(page.Title, page.URL)
		fmt.Println(page.Content)
	}
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, FetchOptions};

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    let client = Client::new()?; // reads KEENABLE_API_KEY from the environment
    let opts = FetchOptions {
        prompt: Some(
            "List the supported major versions and when each one stops getting updates, one per line."
                .into(),
        ),
        max_age_hours: Some(24.0), // a stored copy younger than a day, or a live read
        ..Default::default()
    };
    let response = client
        .fetch_with(
            [
                "https://www.postgresql.org/support/versioning/",
                "https://nodejs.org/en/about/previous-releases",
            ],
            &opts,
        )
        .await?;
    // results[i] is for urls[i]
    for page in &response.results {
        if let Some(error) = &page.error {
            println!("failed: {} {}", page.url, error.code.as_deref().unwrap_or_default());
            continue;
        }
        println!("{} {}", page.title, page.url);
        println!("{}", page.content);
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl https://api.keenable.ai/v1/fetch \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.postgresql.org/support/versioning/",
      "https://nodejs.org/en/about/previous-releases"
    ],
    "content": {
      "prompt": "List the supported major versions and when each one stops getting updates, one per line."
    },
    "retrieval": {"max_age_hours": 24}
  }'
```

## How a call works

* Keenable reads the pages in parallel. `results` has one entry per URL you sent, in the same order: `results[i]` is for `urls[i]`.
* Each entry is either a page or `{"url": ..., "error": {...}}`, where `url` is the URL as you sent it and `error` says why that page failed. A page that fails doesn't fail the call, and the call returns `200`.
* Keenable checks every URL before it reads any page. A URL listed twice in one call, or one that isn't a valid `http` or `https` URL or runs over 8,192 characters, fails the whole call with `400` and `param` set to `urls[i]`. A URL that points to a private or internal address fails the whole call with `403` and `private_url_not_allowed`, as on [`GET /v1/fetch`](https://docs.keenable.ai/api-reference/fetch). Nothing is read or billed. A repeated URL is refused so that no page is read and billed twice in one call.
* The whole call fails, with no `results`, when the request itself can't run: an invalid body or URL, a missing or wrong API key, a balance that can't cover the call or the rate limit. It also fails when every URL fails with the same `400`, `401`, `402` or `403` error, such as a `content.schema` that Keenable can't use. The call then returns that error. See [Errors](#errors).
* A call counts as one request toward your organization's [rate limit](https://docs.keenable.ai/rate-limits.md), however many URLs it has.
* Each page read is billed at the fetch price, so a call that reads 20 pages costs 20 times one page. Each page is billed as a `GET /v1/fetch` of that URL would be, failed pages included. Before any page is read, your free allowance and balance must cover every URL in the call. If they don't, the call returns `402` with `insufficient_credits` and reads nothing.

## What each page returns

`content` sets what each page carries. Every field in it is optional.

| Send in `content` | Each page in `results` |
| - | - |
| Nothing | `content` holds the page as markdown, up to 50,000 characters. |
| `{"max_chars": 20000}` | `content` is cut to 20,000 characters, and `truncated` is `true` when the page was longer. |
| `{"prompt": "..."}` | A model reads the page, and `content` holds only its answer to the prompt. |
| `{"schema": {...}}` | `content` keeps the page, and `structured` holds a JSON object that matches your schema. |
| `{"links": 50}` | `links` holds up to 50 of the page's links, each as `{url, text}`. |
| `{"images": 10}` | `images` holds up to 10 of the page's images, each as `{url, alt}`. |

Every page also carries `image`, its main image, and `favicon`, the site's icon. You don't need to ask for them. Either is `null` when the page has none.

`prompt` works the same way as the `prompt` parameter of `GET /v1/fetch`. Write it as an instruction or a question about the page, such as `List the pricing tiers with their monthly prices`.

`schema` takes a [JSON Schema](https://json-schema.org/) whose root has `"type": "object"`. If the page is read but the answer can't be made, the page still comes back with `answer_error` in place of `structured`. `answer_error.code` is one of `summary_input_too_long`, `summary_no_content`, `summary_truncated`, `summary_schema_mismatch` and `summary_failed`.

## Where pages come from

By default, Keenable returns its indexed copy of a page if it has one, whatever its age, and reads the page live from its source otherwise. `retrieval.max_age_hours` changes that:

| Send in `retrieval` | What each page is read from |
| - | - |
| Nothing | The indexed copy, or a live read when there is none. |
| `{"max_age_hours": 24}` | The indexed copy if it's younger than 24 hours. An older copy is read again live. |
| `{"max_age_hours": 0}` | A live read, the same as `live=true` on `GET /v1/fetch`. |

`max_age_hours` takes a number of hours from `0` to `720` (30 days). Fractions work: `0.25` is 15 minutes.

When you send `max_age_hours`, each page has `stale`. It's `true` when the page you got is an indexed copy older than `max_age_hours`, because the live read failed or Keenable couldn't use what it read. Otherwise it's `false`.

## Billing

* Each page that comes back without an error is billed as one fetch at the [standard fetch prices](https://docs.keenable.ai/pricing.md#what-each-call-costs): `fetch` for Keenable's indexed copy, `fetch.live` for a live read.
* A page that fails is treated like a failed `GET /v1/fetch` call. See [What isn't billed](https://docs.keenable.ai/pricing.md#what-isnt-billed).
* `prompt`, `schema`, `links` and `images` don't change the price.
* Each page carries its own `usage` object, the same as a `GET /v1/fetch` response. See [Balance and usage](https://docs.keenable.ai/credits.md).

## API key

`POST /v1/fetch` needs an API key. There is no keyless version: a call without a key returns `401` with `missing_api_key`. Send the key in `X-API-Key` or as `Authorization: Bearer`. See [Authentication](https://docs.keenable.ai/api-reference.md#authentication).

## Limits

| Limit | Value |
| - | - |
| URLs per call | 1 to 20 |
| Each URL | up to 8,192 characters, sent once per call |
| How a call counts against the rate limit | 1 request, however many URLs |
| `content.max_chars` | 1 or more, default 50,000 |
| `content.prompt` | up to 2,000 characters |
| `content.schema` | up to 20,000 characters as compact JSON |
| `content.links` | 1 to 1,000 |
| `content.images` | 0 to 25 |
| `retrieval.max_age_hours` | 0 to 720, fractions allowed |

## Request

Send a JSON object with `Content-Type: application/json`. Only `urls` is required. A field that isn't listed here, at the top level or inside `content` or `retrieval`, returns `400` with `unknown_parameter`, and the message lists the supported fields. To group the calls of one agent task, send the `X-Keenable-Session-Id` header.

**urls** `string[]` *required*

The pages to read: 1 to 20 absolute `http` or `https` URLs, each up to 8,192 characters and each listed once. Send `urls` even for one page. If `urls` is missing, the API returns `400` with `missing_parameter`. If it isn't an array of 1 to 20 non-empty strings, the API returns `400` with `invalid_parameter`. If one URL is listed twice, isn't a valid URL or is too long, the API returns `400` with `invalid_parameter` and `param` set to that entry, such as `urls[2]`, and reads no page. If one points to a private or internal address, the API returns `403` with `private_url_not_allowed` and `param` set to that entry, and reads no page.

**content** `object`

What each page carries. See [What each page returns](#what-each-page-returns).

**properties**

**max\_chars** `integer` (default: 50000)

The most characters of `content` per page, 1 or more. Longer content is cut to fit and ends with `...`, and the page then has `truncated` set to `true`.

**prompt** `string`

What you want from each page, up to 2,000 characters. A model reads each page, and its `content` holds only the answer. An empty prompt returns `400` with `invalid_parameter`.

**schema** `object`

A JSON Schema whose root has `"type": "object"`. Each page gets `structured`, an object that matches it, or `answer_error`. A schema that isn't an object with that root, is over 20,000 characters as compact JSON or has a `$ref` outside itself returns `400` with `invalid_parameter` on `content.schema`.

**links** `integer`

The most links to return per page, 1 to 1,000. Leave it out for none.

**images** `integer`

The most images to return per page, 0 to 25. Leave it out, or send `0`, for none.

**retrieval** `object`

Where each page is read from. See [Where pages come from](#where-pages-come-from).

**properties**

**max\_age\_hours** `number`

Use Keenable's indexed copy only if it's younger than this many hours, 0 to 720. `0` always reads the page live. Fractions work. Leave it out for an indexed copy of any age.

## Response

A `200` returns `{"results": [...]}`, with one entry per URL in `urls`, in the same order.

**results** `object[]` *required*

Each entry is a page, or an error for that URL.

**a page: properties**

**url** `string` *required*

The page's final address after redirects. It can differ from the URL you sent. Cite this one.

**content** `string` *required*

The page's main text as markdown, capped by `max_chars`. With `prompt`, the model's answer instead.

**truncated** `boolean`

`true` when `content` was cut to `max_chars`.

**total\_chars** `integer`

The length of the full content in characters, before `max_chars` was applied.

**title** `string`

The page title. Left out when the page has none.

**author** `string`

The author as the page names them. Left out when the page names none.

**published\_at** `string`

When the page was published, as an ISO 8601 timestamp in UTC. Left out when it's unknown.

**image** `string | null` *required*

The page's main image, or `null`. Always present: you don't need to ask for it.

**favicon** `string | null` *required*

The site's icon, or `null`. Always present: you don't need to ask for it.

**images** `object[]`

`{url, alt}` for each image, when you sent `content.images`. `alt` is `null` when the page gives none.

**links** `object[]`

`{url, text}` for each link, when you sent `content.links`. `text` is `null` when the link has none.

**structured** `object`

The answer that matches `content.schema`.

**answer\_error** `object`

`{code, message}` when you sent `content.schema` and the answer couldn't be made.

**stale** `boolean`

Present when you sent `retrieval.max_age_hours`. `true` when the page is an indexed copy older than you asked for. See [Where pages come from](#where-pages-come-from).

**description** `string` *deprecated*

Always an empty string; read `content`.

**usage** `object`

What this page was billed, with `sku`, `amount`, `credits`, `paid` and `credits_remaining`, as on [`GET /v1/fetch`](https://docs.keenable.ai/api-reference/fetch#response).

**an error: properties**

**url** `string` *required*

The URL as you sent it.

**error** `object` *required*

Why the page failed: `status`, the HTTP status of that page's error, plus the fields of an error response, such as `error`, `message`, `code`, `type`, `fix` and `retryable`. A retryable error has `retry_after_seconds`. Branch on `code`. Every code is on [Errors](https://docs.keenable.ai/errors.md#error-codes).

This response shows the shape of a call with two URLs: one page, with its text left out, and one URL that failed:

```json Example response · shape only theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "results": [
    {
      "url": "https://www.postgresql.org/support/versioning/",
      "title": "...",
      "content": "...",
      "truncated": false,
      "total_chars": 0,
      "description": "",
      "image": null,
      "favicon": null,
      "stale": false,
      "usage": { "sku": "fetch", "amount": 1, "credits": 1, "paid": false }
    },
    {
      "url": "https://example.com/missing-page",
      "error": {
        "status": 404,
        "error": "Not found",
        "message": "The page does not exist at this URL. Check that the URL is correct.",
        "code": "page_not_found",
        "type": "target_error",
        "retryable": false
      }
    }
  ]
}
```

## Errors

These statuses fail the whole call. Errors for single pages come back in `results`. Every error has the same shape as on the other endpoints, with `error`, `message`, `code`, `fix` and `retryable`.

| Status | When | Fix |
| - | - | - |
| `400` | The body isn't a JSON object, a field is unknown (`unknown_parameter`), `urls` is missing (`missing_parameter`) or a value is out of range (`invalid_parameter`). Also when a URL is listed twice, is invalid or is over 8,192 characters (`param` is `urls[i]`). | Correct the field named in `param` and `message`. Don't retry unchanged. |
| `401` | No API key (`missing_api_key`), or the key isn't valid (`invalid_api_key`). | Send a valid key in `X-API-Key`. |
| `402` | Your allowance and balance can't cover every URL in the call (`insufficient_credits`). | Top up in the console, or send fewer URLs. |
| `403` | The key is revoked, a URL points to a private or internal address (`private_url_not_allowed`, `param` is `urls[i]`), or every URL failed with the same `403`. | Read `message`. For a revoked key, use another key. For a private address, remove that URL or replace it with a public one. |
| `429` | The call would go over your organization's requests per second (`rate_limit_per_second`). | Wait for `Retry-After`, then retry. |

## Move from GET /v1/fetch

| `GET /v1/fetch` | `POST /v1/fetch` |
| - | - |
| `url=...` | `"urls": ["..."]`, up to 20 |
| `max_chars` | `content.max_chars` |
| `prompt` | `content.prompt` |
| `live=true` | `"retrieval": {"max_age_hours": 0}` |
| The page as the response body | The page as `results[0]` |
| An error status for the call | `results[i].error` for that URL, and the call returns `200` |
| Keyless on `GET /v1/fetch/public` | Not available: `POST /v1/fetch` needs an API key |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.