# Extract anchored chunks Split extracted content into chunks that retain page, sheet, or section locations. Documentation index: https://webcite.co/llms.txt Canonical page: https://webcite.co/api-docs/chunks API origin: https://api.webcite.co Authentication: x-api-key header. Keep keys on your server. ## When to use it Use these chunks for retrieval and citation display. Preserve the source anchors when you index the text. `token_estimate` is an estimate for context budgeting, not a provider billing count. ## Request POST /api/v1/extract/pages 1 credit for a billable extraction outcome. ### curl ```curl curl --fail-with-body -X POST 'https://api.webcite.co/api/v1/extract/pages' \ -H "x-api-key: $WEBCITE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "asset_id": "YOUR_ASSET_ID" }' ``` ### Node.js ```javascript const response = await fetch("https://api.webcite.co/api/v1/extract/pages", { method: "POST", headers: { "x-api-key": process.env.WEBCITE_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ "asset_id": "YOUR_ASSET_ID" }), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); console.log(await response.json()); ``` ### python ```python import os import json import requests payload = json.loads("{\n \"asset_id\": \"YOUR_ASSET_ID\"\n}") response = requests.post( "https://api.webcite.co/api/v1/extract/pages", headers={"x-api-key": os.environ["WEBCITE_API_KEY"]}, json=payload, timeout=(10, 300), ) response.raise_for_status() print(response.json()) ``` ## Response Returns chunks with contiguous zero-based ordinal, text, token_estimate, and available source anchors, plus extraction state. ## Errors For 400, check the request fields and source identifiers. For 401, check your API key. For 429, wait for the retry interval. See the errors guide before retrying a billable request. ## OpenAPI operation ```json { "path": "/api/v1/extract/pages", "method": "POST", "operation": { "description": "The same all-formats extraction as POST /extract, sliced into retrieval-sized **chunks** that keep the anchor a citation needs: `page` (PDF), `sheet` (workbook tab), `section` (nearest preceding markdown heading), plus a `token_estimate` for packing a context budget. `ordinal` is contiguous from 0 across the whole document.\n\nUse this instead of /extract when you intend to index the text and later point a reader at where a passage came from: flat pages cannot carry a citation.\n\n**An empty `chunks` says why it is empty.** `state`, `reason` and `code` are the extraction's own determination, carried through verbatim — the same three fields, the same vocabulary and the same values as `POST /extract` over the same asset. A refusal (`source_too_large`, `source_corrupt`, `source_encrypted`, `unsupported_format`) and a document that genuinely holds nothing (`empty_source`) both return no chunks, and `code` is what tells them apart. `code` is `null` on a complete read.\n\n**Cost: 1 credit.** Same work as /extract — the chunking is in-process and makes no model call.", "operationId": "ApiV1Controller_extractPages", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractRequestDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractPagesResponseDto" } } }, "description": "{ chunks[], state, reason, code }" }, "400": { "description": "Asset not found" }, "401": { "description": "Unauthorized - API key required" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Extract a document into anchored chunks ready to index and cite", "tags": [ "Public API" ] }, "schemas": { "ExtractRequestDto": { "properties": { "asset_id": { "description": "An uploaded asset id (from POST /upload). One of asset_id / asset_url is required.", "type": "string" }, "asset_url": { "description": "A direct URL to the file. One of asset_id / asset_url is required.", "type": "string" } }, "type": "object" }, "ExtractPagesResponseDto": { "properties": { "chunks": { "description": "Anchored chunks, in document order. Empty both when the document held no text and when the read was refused — `code` is what tells those apart.", "items": { "$ref": "#/components/schemas/AnchoredChunkDto" }, "type": "array" }, "code": { "description": "The stable classification of `reason`, safe to switch on. The same vocabulary and the same values as `POST /extract`. Null when nothing refused.\n\n| Code | What it means | What to do |\n|------|---------------|------------|\n| `source_too_large` | a size or expansion ceiling refused the read | `reason` carries the observed value and the limit; send a smaller file |\n| `source_encrypted` | the container is password-protected | send an unlocked copy |\n| `source_corrupt` | the container could not be opened as the format it declares | re-export the file |\n| `unsupported_format` | no reader is registered for this format | convert it |\n| `ocr_unavailable` | the page had no text layer and no vision provider is configured | configure a vision key, or send a text-layer file |\n| `partial_extraction` | some of the source was recovered and some was not | use what came back |\n| `empty_source` | the source was read and held nothing | a fact about the file, not a failure — nothing to retry |\n| `extraction_error` | our failure | retry |", "enum": [ "source_too_large", "source_encrypted", "source_corrupt", "unsupported_format", "ocr_unavailable", "partial_extraction", "empty_source", "extraction_error" ], "nullable": true, "type": "string" }, "reason": { "description": "Free text naming the cause, straight from whatever refused or failed — `spreadsheet_magic_mismatch:xlsx`, `spreadsheet_too_large:bytes:33554433>33554432`, `extraction_failed:File is password-protected`. Carries detail no enum can, and is NOT stable: it includes dependency error text. Display it; do not branch on it. Null when nothing refused.", "nullable": true, "type": "string" }, "state": { "description": "How much of the source the read recovered, in one word. `complete` on a healthy read, whatever the payload beside it turned out to contain.", "enum": [ "complete", "partial", "unsupported", "error" ], "type": "string" } }, "required": [ "state", "reason", "code", "chunks" ], "type": "object" }, "AnchoredChunkDto": { "properties": { "ordinal": { "description": "Position of this chunk in the document, from 0.", "type": "number" }, "page": { "description": "1-based page the chunk came from.", "type": "number" }, "section": { "description": "Nearest preceding markdown heading.", "type": "string" }, "sheet": { "description": "Workbook tab the chunk came from.", "type": "string" }, "text": { "description": "The chunk text.", "type": "string" }, "token_estimate": { "description": "Rough token count (~4 chars/token) for packing a retrieval budget.", "type": "number" } }, "required": [ "ordinal", "text", "token_estimate" ], "type": "object" } } } ```