Extract document text
Read an uploaded document as text with extraction status and source coverage.
/api/v1/extracthttps://api.webcite.coWhen to use it
Use the returned asset ID from upload. Text-layer extraction is attempted before OCR when supported. Scanned documents can require OCR.
Check state before using markdown. Branch on the stable code; display reason as diagnostic text. See document workflows.
Request
1 credit for a billable extraction outcome.
Examples run on your server. Set WEBCITE_API_KEY first. Python examples use the requests package.
curl --fail-with-body -X POST 'https://api.webcite.co/api/v1/extract' \
-H "x-api-key: $WEBCITE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"asset_id": "YOUR_ASSET_ID"
}'Request body
asset_idstringAn uploaded asset id (from POST /upload). One of asset_id / asset_url is required.
asset_urlstringA direct URL to the file. One of asset_id / asset_url is required.
Response
Read state, code, reason, extraction_method, markdown, and any lost parts. complete: false means the whole source was not recovered. Do not convert an error or partial read into an empty successful document.
200 response
application/json
codestring | nullrequiredThe stable classification of reason, safe to switch on. Null on a complete read.
| Code | What it means | What to do |
|---|---|---|
source_too_large | a size or expansion ceiling refused the read | reason carries the observed value and the limit; send a smaller file |
source_encrypted | the container is password-protected | send an unlocked copy |
source_corrupt | the container could not be opened as the format it declares | re-export the file |
unsupported_format | no reader is registered for this format | convert it |
ocr_unavailable | the page had no text layer and no vision provider is configured | configure a vision key, or send a text-layer file |
partial_extraction | some of the source was recovered and some was not | use what came back; lost[] names the rest |
empty_source | the source was read and held nothing | a fact about the file, not a failure , nothing to retry |
extraction_error | our failure | retry |
Values: "source_too_large""source_encrypted""source_corrupt""unsupported_format""ocr_unavailable""partial_extraction""empty_source""extraction_error"
completebooleanPresent, and only ever false, when the read did not recover the whole source. Absent on a complete read, so seeing it is a determination rather than a default.
extraction_methodstringrequiredThe path that produced most of this document's text.
Values: "text_layer""ocr""spreadsheet_cells""none"
formatstringrequiredThe format the bytes were read as.
lostobject[]The parts that were not recovered. Absent on a complete read.
Show lost fields
codestring | nullrequiredThe stable classification of this part's reason. Same vocabulary as the document-level code; the two can differ, because a document that recovered most of itself is partial_extraction while the one part it lost names its own cause.
Values: "source_too_large""source_encrypted""source_corrupt""unsupported_format""ocr_unavailable""partial_extraction""empty_source""extraction_error"
indexnumberrequired1-based page / sheet index, as on the unit that failed.
kindstringrequiredWhich kind of unit was lost.
Values: "page""sheet"
reasonstring | nullrequiredFree text: what the reader said about this part.
sheetstringSheet units only: the tab the workbook declared.
statestringrequiredWhat happened to this part specifically.
Values: "partial""unreadable""error"
markdownstringrequiredThe whole document as markdown. Empty when nothing was read.
reasonstring | nullrequiredFree text naming the cause, straight from whatever refused or failed , extraction_failed:File is password-protected, spreadsheet_too_large:bytes:33554433>33554432. Carries detail no enum can (the observed value and the limit are both in it) and is NOT stable: it includes dependency error text. Display it; do not branch on it. Null on a complete read.
statestringrequiredHow much of the source the read recovered, in one word.
Values: "complete""partial""unsupported""error"
Errors
The contract lists 400, 401, 404, 413, 429, 500, 502, 503, and 504 outcomes. Inspect the response: missing assets, oversized files, storage failures, and timeouts need different remedies. Never treat a failed download as an empty document.
400- asset_url is not an allowed public web address, or neither asset_id nor asset_url was given
401- Unauthorized - API key required
404- The asset does not exist, or the store has no bytes for it
413- The asset is over the 50 MB download ceiling. The body carries `bytes` (null when the reader refused mid-stream) and `max_bytes`
429- Rate limit exceeded
502- The asset store returned a failure. Ours, not the request — retry
503- Private evidence storage is not configured, so an evidence:// asset cannot be read
504- The asset download timed out. Retry