API overview
Base URL, authentication, conventions, errors and metering for the hosted Webfold API.
The hosted API exposes Webfold’s web, research and bookmark capabilities over HTTP. Same engine, no infrastructure to run.
Base URL
https://api.webfold.aiFor local development against your own server, use http://localhost:8080.
Authentication
Send your API key as a bearer token on every request except GET /health.
curl -s https://api.webfold.ai/v1/usage \
-H "Authorization: Bearer $WEBFOLD_API_KEY"Keys are issued per account. To get access, email hello@webfold.ai. Keep keys server-side; never ship one in browser code.
Requests and responses
- Request bodies are JSON with
Content-Type: application/json. - Most responses are JSON.
POST /v1/web/scrapereturns the page as plain-text Markdown. - Errors have a plain-text body, not JSON. Read the status code first.
- Fetched content is cached. The
x-cacheresponse header ishit,miss, orraw-hit(a cached raw document was prepared on demand).
Status codes
| Status | Meaning |
|---|---|
200, 201, 204 |
Success. 201 on create, 204 on delete. |
400 |
The request body or parameters are invalid. |
401 |
The bearer token is missing or invalid. |
403 |
Your plan or billing entitlement does not allow this operation. |
404 |
The bookmark or collection does not exist for your account. |
429, 5xx |
Retry with exponential backoff. The official SDKs retry up to 3 times. |
502 |
The upstream (arXiv, YouTube or the target web page) failed. |
Metering
Each operation is metered against a feature key. When billing is enabled the server checks your plan entitlement and credit balance before running the operation, then records a usage event with an idempotency key.
| Feature key | Operation |
|---|---|
arxiv.search, arxiv.retrieve |
arXiv search and paper retrieval |
youtube.transcript |
YouTube transcript |
web.scrape |
Web scrape |
bookmark.create, .read, .update, .delete |
Bookmark operations |
collection.create, .read, .delete |
Collection operations |
usage.report |
Usage report |
documents.convert, ocr.pdf |
Document conversion and OCR, one per file |
pii.redact, pii.scan |
PII redaction and scan, one per request |
corpus.redact, corpus.build |
Corpus operations, one per record |
localization.check, localization.extract |
Translation checks (one per item) and string extraction |
computer.create, computer.access |
Creating a computer, and access to the other computer endpoints |
What the hosted API covers
The hosted API covers web, research and bookmark endpoints, and also documents, OCR, PII, corpus building, translation checks and sandboxed computers. Files and text for those endpoints are sent in the request, so run the tool locally if the data must stay on your machine. The self-hosted PII service has its own API reference.
Endpoints
| Area | Endpoints | Page |
|---|---|---|
| Web | POST /v1/web/scrape · /crawl · /map · /search |
Web |
| Research | POST /v1/arxiv/search · /retrieve · /v1/youtube/transcript |
Research |
| Documents | POST /v1/documents/convert |
Documents |
| OCR | POST /v1/ocr |
OCR |
| PII | POST /v1/pii/redact · /v1/pii/scan |
PII |
| Corpus | POST /v1/corpus/redact · /v1/corpus/build |
Corpus |
| Localisation | POST /v1/localization/check · /v1/localization/extract |
Localisation |
| Computers | /v1/computers and /v1/computers/{id}/... |
Computers |
| Library | /v1/bookmarks · /v1/collections |
Bookmarks |
| Account | GET /health · GET /v1/usage |
Account |
The SDKs are generated from and validated against an OpenAPI 3.1 description of these endpoints. Email hello@webfold.ai if you need a copy.