---
title: "API overview"
description: "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

```text
https://api.webfold.ai
```

For 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`.

```sh
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](mailto: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/scrape` returns 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-cache` response header is `hit`, `miss`, or `raw-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](/docs/reference/faces) if the data must stay on your machine. The self-hosted PII service has its own [API reference](/docs/pii-api).

## Endpoints

| Area | Endpoints | Page |
| --- | --- | --- |
| Web | `POST /v1/web/scrape` · `/crawl` · `/map` · `/search` | [Web](/docs/api-reference) |
| Research | `POST /v1/arxiv/search` · `/retrieve` · `/v1/youtube/transcript` | [Research](/docs/api-reference) |
| Documents | `POST /v1/documents/convert` | [Documents](/docs/api-reference) |
| OCR | `POST /v1/ocr` | [OCR](/docs/api-reference) |
| PII | `POST /v1/pii/redact` · `/v1/pii/scan` | [PII](/docs/api-reference) |
| Corpus | `POST /v1/corpus/redact` · `/v1/corpus/build` | [Corpus](/docs/api-reference) |
| Localisation | `POST /v1/localization/check` · `/v1/localization/extract` | [Localisation](/docs/api-reference) |
| Computers | `/v1/computers` and `/v1/computers/{id}/...` | [Computers](/docs/api-reference) |
| Library | `/v1/bookmarks` · `/v1/collections` | [Bookmarks](/docs/api-reference) |
| Account | `GET /health` · `GET /v1/usage` | [Account](/docs/api-reference) |

The SDKs are generated from and validated against an OpenAPI 3.1 description of these endpoints. Email [hello@webfold.ai](mailto:hello@webfold.ai) if you need a copy.