# Passages

The graded path.

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

`GET /api/v1/passages`

The curated passages for learners, levels 1 to 5, in reading order.

## Parameters

| Field | Type | Description |
|---|---|---|
| `lang` | string, in query | Optional. Only this language. One of `la`, `grc`, `latin`, `greek`. |
| `level` | integer, in query | Optional. Only this level. From 1 to 5. |

## Response

`200 OK` with a `PassageList` object.

| Field | Type | Description |
|---|---|---|
| `note` | string |  |
| `passages` | array of PassageSummary | The graded path, easiest first within each language. |
| `passages[].slug` | string |  |
| `passages[].lang` | string | Language code: la (Latin) or grc (Ancient Greek). One of `la`, `grc`. |
| `passages[].level` | integer | 1 (easiest) to 5. |
| `passages[].title` | string |  |
| `passages[].citation` | string |  |
| `passages[].verse` | boolean |  |
| `passages[].words` | integer |  |
| `passages[].blurb` | string |  |
| `passages[].urn` | string or null | CTS URN, e.g. urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.1-1.11. Null when the edition has none (The Latin Library's own numbering). |
| `passages[].url` | string | Absolute URL. |
| `passages[].api` | string | Absolute URL. |

## Errors

| Status | When |
|---|---|
| `400 Bad Request` | A parameter is missing or invalid, or the reference isn't a text. |
| `429 Too Many Requests` | Too many requests from one address. Wait a minute. |
| `500 Internal Server Error` | Something went wrong on our side. |

Error bodies are described in [Caching, limits and errors](https://interlinea.aeterna-institute.org/docs/limits.md#errors).

## Example request

curl:

```sh
curl "https://interlinea.aeterna-institute.org/api/v1/passages"
```

JavaScript:

```js
const res = await fetch("https://interlinea.aeterna-institute.org/api/v1/passages")
const data = await res.json()
console.log(data)
```

Python:

```python
import json
from urllib.request import urlopen

with urlopen("https://interlinea.aeterna-institute.org/api/v1/passages") as res:
    data = json.load(res)

print(data)
```

## Example response

Response (200 OK):

```json
{
  "note": "The graded path: short passages chosen and ordered for learners, each analysed ahead of time. Read them in order within a language.",
  "passages": [
    {
      "slug": "genesis-creation",
      "lang": "la",
      "level": 1,
      "title": "Let There Be Light",
      "citation": "Vulgate (Jerome), Genesis 1.1–5",
      "verse": false,
      "words": 58,
      "blurb": "Creation’s first day in plain, rhythmic Church Latin.",
      "urn": null,
      "url": "https://interlinea.aeterna-institute.org/read/latin/genesis-creation",
      "api": "https://interlinea.aeterna-institute.org/api/v1/passages/latin/genesis-creation"
    },
    {
      "slug": "ritchie-perseus-ark",
      "lang": "la",
      "level": 1,
      "title": "The Ark on the Sea",
      "citation": "Francis Ritchie, Fabulae Faciles, Perseus 1",
      "verse": false,
      "words": 62,
      "blurb": "A baby hero, a fearful grandfather, a chest cast adrift.",
      "urn": null,
      "url": "https://interlinea.aeterna-institute.org/read/latin/ritchie-perseus-ark",
      "api": "https://interlinea.aeterna-institute.org/api/v1/passages/latin/ritchie-perseus-ark"
    },
    {
      "slug": "phaedrus-wolf-lamb",
      "lang": "la",
      "level": 2,
      "title": "The Wolf and the Lamb",
      "citation": "Phaedrus, Fabulae 1.1",
      "verse": true,
      "words": 91,
      "blurb": "Aesop’s grimmest fable. The strong always find an excuse.",
      "urn": "urn:cts:latinLit:phi0975.phi001.perseus-lat2:1.1",
      "url": "https://interlinea.aeterna-institute.org/read/latin/phaedrus-wolf-lamb",
      "api": "https://interlinea.aeterna-institute.org/api/v1/passages/latin/phaedrus-wolf-lamb"
    },
    // 23 more
  ]
}
```

## Try it

Send a real GET from your browser and see the answer, its status and how long it took.

---

Previous: [Section](https://interlinea.aeterna-institute.org/docs/api/section.md)
Next: [Passage](https://interlinea.aeterna-institute.org/docs/api/passage.md)