# REST API

Read-only JSON over GET at /api/v1, described by an OpenAPI 3.1 document.

Canonical: https://interlinea.aeterna-institute.org/docs/api

```text
https://interlinea.aeterna-institute.org/api/v1
```

Free and read only: GET, no key, and CORS is open. Every answer is JSON, and every text carries its citation, canonical URL, CTS URN where the edition has one, and the edition's credit and licence.

## Endpoints

| Endpoint | Returns |
|---|---|
| [`GET /api/v1/text`](https://interlinea.aeterna-institute.org/docs/api/text.md) | Any text, by URL, CTS URN or citation |
| [`GET /api/v1/analysis`](https://interlinea.aeterna-institute.org/docs/api/analysis.md) | The stored word-by-word analysis |
| [`GET /api/v1/context`](https://interlinea.aeterna-institute.org/docs/api/context.md) | The stored context notes |
| [`GET /api/v1/words`](https://interlinea.aeterna-institute.org/docs/api/words.md) | Look a word up in the stored analyses |
| [`GET /api/v1/search`](https://interlinea.aeterna-institute.org/docs/api/search.md) | Search authors, works and topics |
| [`GET /api/v1/library/{lang}/{author}`](https://interlinea.aeterna-institute.org/docs/api/author.md) | An author and their works |
| [`GET /api/v1/library/{lang}/{author}/{work}`](https://interlinea.aeterna-institute.org/docs/api/work.md) | A work, its editions and its contents |
| [`GET /api/v1/library/{lang}/{author}/{work}/{ref}`](https://interlinea.aeterna-institute.org/docs/api/section.md) | A section's text with its citation and credit |
| [`GET /api/v1/passages`](https://interlinea.aeterna-institute.org/docs/api/passages.md) | The graded path |
| [`GET /api/v1/passages/{lang}/{slug}`](https://interlinea.aeterna-institute.org/docs/api/passage.md) | A graded passage's text |
| [`GET /api/v1`](https://interlinea.aeterna-institute.org/docs/api/index.md) | What the API offers |
| [`GET /api/v1/openapi.json`](https://interlinea.aeterna-institute.org/docs/api/openapi.md) | The OpenAPI 3.1 document for version 1 |

## Conventions

- GET only. No key, no account, no cookies.
- JSON in UTF-8 and plain text only, never HTML. Verse keeps its line breaks.
- CORS is open (`Access-Control-Allow-Origin: *`), so a page on any site can call the API.
- URLs in answers are absolute. `url` is the page on Interlinea, `api` the same resource as JSON and `markdown` the same as Markdown.
- Every library page has a JSON twin: put `/api/v1` in front of its path. `/library/latin/virgil/aeneid/1.46` becomes `/api/v1/library/latin/virgil/aeneid/1.46`.
- `{lang}` in a path is `latin` or `greek`. The `lang` query parameter also takes `la` and `grc`.

## Pagination

Lists take `limit` and `offset` and return `total` and a ready `next` URL, which is null on the last page. [`search`](https://interlinea.aeterna-institute.org/docs/api/search.md) returns 20 works by default and at most 100; [`work`](https://interlinea.aeterna-institute.org/docs/api/work.md) returns 200 sections of contents by default and at most 1,000; [`words`](https://interlinea.aeterna-institute.org/docs/api/words.md) returns 10 occurrences by default and at most 50.

## Versioning

This is version 1. New optional fields may appear in answers, but nothing is renamed or removed within v1. A breaking change would come as `/api/v2`. The [changelog](https://interlinea.aeterna-institute.org/docs/changelog.md) lists every change.

## OpenAPI

The [OpenAPI 3.1 document](https://interlinea.aeterna-institute.org/api/v1/openapi.json) is built from the same table the routes run on, and so is this reference, so neither can describe something the API doesn't do. Load it into Postman or Insomnia, or generate a client from it.

Errors, caching and rate limits are in [Caching, limits and errors](https://interlinea.aeterna-institute.org/docs/limits.md).

---

Previous: [Resources](https://interlinea.aeterna-institute.org/docs/mcp/resources.md)
Next: [Text](https://interlinea.aeterna-institute.org/docs/api/text.md)