# EbooksDepository API reference

One public endpoint, anonymous and read-only. The machine contract is
https://ebooksdepository.com/api/openapi.yaml (OpenAPI 3.1; JSON at
https://ebooksdepository.com/api/openapi.json, conventional alias https://ebooksdepository.com/openapi.json); this
page is the human/agent twin.

## Search

```
GET https://ebooksdepository.com/api/v1/search?q={query}&lang={code}&limit={n}
```

- `q` (required): what to search — title, author, publisher.
- `lang` (optional): two-letter book language filter, e.g. `es`, `en`, `pt`.
- `limit` (optional): 1-50, default 10.

Returns `{"results": [...], "total": n}`. Each result carries `slug`,
`title`, `authors_detail`, `publisher_detail`, `genres` and the `stores`
that sell the book. The canonical page for a result is
`https://ebooksdepository.com/es/publications/{slug}` and its Markdown twin adds `.md`.

No prices are returned anywhere, by design: pricing belongs to the
bookshops. `is_free` is the only price-shaped fact we publish.

## Rate limits

60 requests/min per client on the search API, enforced at the origin and
ahead of it at the edge (120/min per IP on `/api/`). Every API response
carries the standard `RateLimit-Policy`, `RateLimit`, `RateLimit-Limit` and
`RateLimit-Remaining` headers; a `429` adds `Retry-After`. Self-throttle on
those headers instead of retrying blind.

## Errors

Errors are RFC 9457 `application/problem+json` documents:

```json
{"type": "https://ebooksdepository.com/api.md#errors-not_found", "title": "Not found",
 "status": 404, "detail": "...", "code": "not_found"}
```

Codes: `not_found` (unknown API path or resource), `validation_failed`
(422, carries an `errors` map), `rate_limit_exceeded` (429), `server_error`
(500 — nothing about the failure leaks), and `unauthenticated` (401, only
from the private publishing endpoints, which are not part of the public
surface). Branch on `code`, not on prose.

## Idempotency

Every public endpoint is a `GET` and therefore idempotent by definition —
retry any request safely. There are no write operations, so no
`Idempotency-Key` header exists or is needed.

## Pagination

The search endpoint is bounded (`limit` <= 50) and unpaginated: it answers
"find this book", not "walk the catalog". To walk the catalog, use
https://ebooksdepository.com/sitemap.xml or the structured feed https://ebooksdepository.com/feeds/books.jsonl.

## Versioning and deprecation

The API is versioned in the path (`/api/v1/`). A breaking change ships as
`/api/v2/` with `v1` kept alive for at least 6 months; removals are
announced in https://ebooksdepository.com/llms.txt and marked `deprecated: true` in the OpenAPI
document before they happen.