docs/docs.md

# `SERPent`

## SERP results scrapping

SERPent exposes an unified API to query SERP (Search Engine Result Pages) for a few common search engines, namely:

- DuckDuckGo
- Brave
- Bing
- Google Patents
- arXiv
- Google

The application uses the `playwright` library to control a headless web browser, to simulate normal user activity, to fool the anti-bot measures often present on those sites. See the `/serp/` endpoints for search results scrapping.


## Website sources scrapping

SERPent also exposes a few endpoints to scrap the contents of certain sources (patents, scholar). See the `/scrap/` endpoints for supported website sources scrapping.


## EPO OPS (official patent API)

SERPent integrates the European Patent Office's Open Patent Services (OPS) v3.2 REST API — a legitimate source for patents that are missing from, or unscrapable via, Google Patents. See the `/ops/` endpoints for keyword search and by-number retrieval (bibliographic data, abstract, claims, description, CPC classifications).

OPS requires OAuth2 client credentials. Set them via the `OPS_CONSUMER_KEY` and `OPS_CONSUMER_SECRET` environment variables (register a free app at the EPO Developer Portal). When configured, the Google Patents endpoints (`/serp/search_patents` and `/scrap/scrap_patent/{id}`) automatically fall back to OPS when they return nothing.


## Access control

By default every endpoint is open (no authentication), matching how this API
has always run. To restrict access, set the `SERPENT_API_KEY` environment
variable — every request (REST and MCP alike) then needs a matching
`X-API-Key` or `Authorization: Bearer <key>` header, except this docs page and
`/openapi.json`. This is recommended once the deployment is public, since it
otherwise doubles as an anonymous, unauthenticated scraping proxy for anyone
who finds the URL.