Skip to content
InterlineaDocs
REST APIOverviewDocs menu

REST API

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

Base URL: 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

EndpointReturns
GET /api/v1/textAny text, by URL, CTS URN or citation
GET /api/v1/analysisThe stored word-by-word analysis
GET /api/v1/contextThe stored context notes
GET /api/v1/wordsLook a word up in the stored analyses
GET /api/v1/searchSearch authors, works and topics
GET /api/v1/library/{lang}/{author}An author and their works
GET /api/v1/library/{lang}/{author}/{work}A work, its editions and its contents
GET /api/v1/library/{lang}/{author}/{work}/{ref}A section's text with its citation and credit
GET /api/v1/passagesThe graded path
GET /api/v1/passages/{lang}/{slug}A graded passage's text
GET /api/v1What the API offers
GET /api/v1/openapi.jsonThe 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 returns 20 works by default and at most 100; work returns 200 sections of contents by default and at most 1,000; words 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 lists every change.

OpenAPI

The OpenAPI 3.1 document 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.