Classify a document

POST/api/v1/classifyhttps://api.webcite.co

When to use it

Classification uses extracted content and spreadsheet sheet names. Check the read state before treating a category as established. It does not certify that the document meets a diligence requirement.

Request

1 credit for a billable classification outcome.

Examples run on your server. Set WEBCITE_API_KEY first. Python examples use the requests package.

curl

curl --fail-with-body -X POST 'https://api.webcite.co/api/v1/classify' \
  -H "x-api-key: $WEBCITE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "asset_id": "YOUR_ASSET_ID"
}'

Request body

asset_idstring

An uploaded asset id (from POST /upload). One of asset_id / asset_url is required.

asset_urlstring

A direct URL to the file (e.g. the consumer's own signed GCS URL). One of asset_id / asset_url is required.

taxonomystring

Taxonomy preset to classify against. Default "vc".

Values: "vc""ma"

Response

Returns category, covers, state, reason, and code. A bundled document can cover more than one type.

200 response

application/json

basisstringrequired

Values: "content""filename""fallback"

categorystringrequired

The coarse category, or unfiled when nothing matched. Unchanged by a refusal: check code to learn whether the document was read at all.

codestring | nullrequired

The stable classification of reason, safe to switch on. The same vocabulary and the same values as POST /extract. Null when nothing refused.

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
`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"

confidencenumberrequired

Heuristic signal score, not a calibrated probability.

minimum: 0maximum: 1

confidenceAssessmentobject

Show confidenceAssessment fields

basisstringrequired

Values: "heuristic"

calibratedbooleanrequired

Values: false

languagestring | nullrequired

Unknown; the vocabulary census is not a document language detector.

languageBasisstringrequired

Values: "unknown"

perLanguageCalibrationstringrequired

Values: "unavailable"

coversstring[]required

The fine multi-type covers the document holds. Empty when nothing matched.

reasonstring | nullrequired

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.

statestringrequired

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.

Values: "complete""partial""unsupported""error"

sufficiencyobject

Show sufficiency fields

reasonstringrequired

statusstringrequired

Values: "unavailable"

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.

400: Asset not found
401: Unauthorized - API key required
429: Rate limit exceeded

Error handling and retry guidance