# Poetry API
> A corpus of 2,500+ classic public-domain poems by 127 authors (Shakespeare, Keats, Dickinson, Whitman, Poe, Frost and many more), via the PoetryDB collection. Look up a poem by title or id and get its full text, line by line; browse every poem by an author (or list all authors); full-text search across titles, authors and lines; or fetch a random poem (optionally by author or capped to a number of lines, perfect for a poem-of-the-day). Ideal for literary apps, education, writing tools, daily-poem widgets and creative projects.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/poetry-api/..."
```

## Pricing
- **Free** (Free) — 6,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 65,000 calls/Mo, 8 req/s
- **Pro** ($14/Mo) — 320,000 calls/Mo, 20 req/s
- **Mega** ($34/Mo) — 1,500,000 calls/Mo, 50 req/s

## Endpoints

### Poetry

#### `GET /v1/author` — Poems by an author, or list all authors

**Parameters:**
- `name` (query, optional, string) — Author name, e.g. Shakespeare (omit to list all) Example: `Shakespeare`
- `limit` (query, optional, string) — Max poems (1-500, default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poetry-api/v1/author?name=Shakespeare&limit=50"
```

**Response:**
```json
{
    "data": {
        "count": 162,
        "poems": [
            {
                "id": 2286,
                "title": "A Lover's Complaint",
                "author": "William Shakespeare",
                "linecount": 331
            },
            {
                "id": 2287,
                "title": "Spring and Winter ii",
                "author": "William Shakespeare",
                "linecount": 18
            },
            {
                "id": 2288,
                "title": "Orpheus with his Lute Made Trees",
                "author": "William Shakespeare",
                "linecount": 12
            },
            {
                "id": 2289,
                "title": "Winter",
                "author": "William Shakespeare",
                "linecount": 18
            },
            {
                "id": 2290,
                "title": "Spring",
                "author": "William Shakespeare",
                "linecount": 18
            },
            {
                "id": 2291,
                "title": "Spring and Winter i",
                "author": "William Shakespeare",
                "linecount": 18
            },
            {
                "id": 2292,
                "title": "Blow, Blow, Thou Winter Wind",
                "author": "William Shakespeare",
                "linecount": 20
            },
            {
                "id": 2293,
                "title": "Under the Greenwood Tree",
                "author": "William Shakespeare",
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/poem` — A poem by title or id (full text)

**Parameters:**
- `title` (query, optional, string) — Poem title, e.g. To Hope Example: `To Hope`
- `id` (query, optional, string) — Poem id

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poetry-api/v1/poem?title=To+Hope"
```

**Response:**
```json
{
    "data": {
        "id": 1298,
        "lines": [
            "When by my solitary hearth I sit,",
            "      And hateful thoughts enwrap my soul in gloom;",
            "When no fair dreams before my \"mind's eye\" flit,",
            "      And the bare heath of life presents no bloom;",
            "            Sweet Hope, ethereal balm upon me shed,",
            "            And wave thy silver pinions o'er my head!",
            "",
            "Whene'er I wander, at the fall of night,",
            "      Where woven boughs shut out the moon's bright ray,",
            "Should sad Despondency my musings fright,",
            "      And frown, to drive fair Cheerfulness away,",
            "            Peep with the moonbeams through the leafy roof,",
            "            And keep that fiend Despondence far aloof!",
            "",
            "Should Disappointment, parent of Despair,",
            "      Strive for her son to seize my careless heart;",
            "When, like a cloud, he sits upon the air,",
            "      Preparing on his spell-bound prey to dart:",
            "            Chase him away, sweet Hope, with visage bright,",
            "            And fright him as the morning frightens night!",
            "",
            "Whene'er the fate of those I hold most dear",
            "      Tells to my fearful breast a tale of sorrow,",
            "O bright-eyed Hope, my morbidfancy cheer;",
            "      Let me awhile thy swe
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/random` — A random poem

**Parameters:**
- `author` (query, optional, string) — Restrict to an author
- `max_lines` (query, optional, string) — Only poems up to this many lines

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poetry-api/v1/random"
```

**Response:**
```json
{
    "data": {
        "id": 1448,
        "lines": [
            "On this thy natal day permit a friend -",
            "A brother - with thy joys his own to blend:",
            "In all gladness he would wish to share",
            "As willing in thy griefs a part to bear.",
            "",
            "Meekly attend the ways of higher heav'n!",
            "Is much deny'd? Yet much my dear is giv'n.",
            "Thy health, thy reason unimpaired remain",
            "And while as new fal'n snows thy spotless fame",
            "The partner of thy life, attentive - kind -",
            "And blending e'en the interests of the mind.",
            "",
            "What bliss is thine when fore thy glistring eye",
            "Thy lovely infant train pass jocund by!",
            "The ruddy cheek, the smiling morning face",
            "Denote a healthy undegenerate race:",
            "In them renew'd, you'll live and live again,",
            "And children's children's children lisp thy name.",
            "Bright be the skies where'er my sister goes",
            "Nor scowling tempests injure her repose -",
            "The field of life with roses thick be strow'd",
            "Nor one sharp thorn lie lurking in the road.",
            "Thy ev'ry path be still a path of peace",
            "And each revolving year thy joys increase;",
            "Till hours and years of time itself be o'er",
            "And one eternal day around thee pour."
        ],
        "title"
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search titles, authors and lines

**Parameters:**
- `q` (query, required, string) — Search term, e.g. love Example: `love`
- `author` (query, optional, string) — Restrict to an author
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poetry-api/v1/search?q=love&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "limit": 20,
        "query": "love",
        "total": 1165,
        "author": null,
        "offset": 0,
        "results": [
            {
                "id": 3,
                "title": "I Have A Rendezvous With Death",
                "author": "Alan Seeger",
                "linecount": 24
            },
            {
                "id": 4,
                "title": "Ode in Memory of the American Volunteers Fallen for France",
                "author": "Alan Seeger",
                "linecount": 104
            },
            {
                "id": 5,
                "title": "Juvenilia, An Ode to Natural Beauty",
                "author": "Alan Seeger",
                "linecount": 175
            },
            {
                "id": 6,
                "title": "The Deserted Garden",
                "author": "Alan Seeger",
                "linecount": 400
            },
            {
                "id": 7,
                "title": "Paris",
                "author": "Alan Seeger",
                "linecount": 174
            },
            {
                "id": 8,
                "title": "Fragments",
                "author": "Alan Seeger",
                "linecount": 83
            },
            {
                "id": 13,
                "title": "Autumn.",
                "author": "Alexander Pope",
                "linecount": 102
            },
            {
                "id": 14,
                "title":
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & source

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/poetry-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Classic public-domain poems. Use /v1/poem for full text, /v1/author to browse, /v1/random for a random poem.",
        "poems": 2526,
        "fields": [
            "id",
            "title",
            "author",
            "lines",
            "linecount"
        ],
        "source": "PoetryDB (public-domain classic poetry)",
        "authors": 127
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:00.696Z",
        "request_id": "8e1cc91c-170a-4105-91ca-f80415dba4d0"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/poetry-api
OpenAPI spec: https://www.oanor.com/api/poetry-api/openapi.json