API reference
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.
POST
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 covers the base URL, authentication and the limits every endpoint shares. The SDKs call this endpoint from
fetch. See SDK methods.
How a call works
- Keenable reads the pages in parallel.
resultshas one entry per URL you sent, in the same order:results[i]is forurls[i]. - Each entry is either a page or
{"url": ..., "error": {...}}, whereurlis the URL as you sent it anderrorsays why that page failed. A page that fails doesn’t fail the call, and the call returns200. - Keenable checks every URL before it reads any page. A URL listed twice in one call, or one that isn’t a valid
httporhttpsURL or runs over 8,192 characters, fails the whole call with400andparamset tourls[i]. A URL that points to a private or internal address fails the whole call with403andprivate_url_not_allowed, as onGET /v1/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 same400,401,402or403error, such as acontent.schemathat Keenable can’t use. The call then returns that error. See Errors. - A call counts as one request toward your organization’s rate limit, 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/fetchof 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 returns402withinsufficient_creditsand reads nothing.
What each page returns
content sets what each page carries. Every field in it is optional.
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 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:
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:
fetchfor Keenable’s indexed copy,fetch.livefor a live read. - A page that fails is treated like a failed
GET /v1/fetchcall. See What isn’t billed. prompt,schema,linksandimagesdon’t change the price.- Each page carries its own
usageobject, the same as aGET /v1/fetchresponse. See Balance and usage.
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.
Limits
Request
Send a JSON object withContent-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.
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.What each page carries. See What each page returns.
Where each page is read from. See Where pages come from.
Response
A200 returns {"results": [...]}, with one entry per URL in urls, in the same order.
This response shows the shape of a call with two URLs: one page, with its text left out, and one URL that failed:
Example response · shape only
Errors
These statuses fail the whole call. Errors for single pages come back inresults. Every error has the same shape as on the other endpoints, with error, message, code, fix and retryable.