# Poetry Foundation API

> Poetry Foundation returns poem texts and search results as a workflow and API.

Poetry Foundation (PF) Get poem returns public poem text and details; it needs a title and optionally a poet. Search poems returns matching poems with titles, poets, available opening lines, and themes or occasions; it needs a topic, occasion, or poet name.

- Page: https://fous.com/tools/poetry-foundation
- Handle: `@poetry-foundation`
- Category: [Education](https://fous.com/tools/category/education)
- Source website: https://poetryfoundation.org
- Last verified: Oct 7, 2026

## Methods

### Get poem

Operation `get_poem`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a poem’s complete public text, poet, source, publication year when shown, and subject tags by title. Optionally specify a poet to distinguish identical titles. Only poems with full text on a public Poetry Foundation page are returned; source and year may be unavailable.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `poet` | string | no | `"Robert Frost"` | The poet’s name to distinguish poems with the same title, for example Robert Frost. |
| `title` | string | yes | `"The Road Not Taken"` | The title of the poem, for example The Road Not Taken. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "poet": {
      "type": "string",
      "description": "The poet’s name to distinguish poems with the same title, for example Robert Frost.",
      "examples": [
        "Robert Frost",
        "Erika L. Sánchez",
        "Rudyard Kipling"
      ]
    },
    "title": {
      "type": "string",
      "description": "The title of the poem, for example The Road Not Taken.",
      "examples": [
        "The Road Not Taken",
        "Prodigal Daughter",
        "If—"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "poet": "Robert Frost",
      "title": "The Road Not Taken"
    },
    {
      "poet": "Erika L. Sánchez",
      "title": "Prodigal Daughter"
    },
    {
      "poet": "Rudyard Kipling",
      "title": "If—"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `poet` | string | `"Robert Frost"` |  |
| `tags` | array |  | Occasions, poetic terms, emotions, and other category labels listed for the poem. |
| `text` | string |  | Full poem text, with its line and stanza breaks. |
| `title` | string | `"The Road Not Taken"` |  |
| `source` | string or null | `"Poetry (June 2024)"` | Printed source citation, if shown on the poem page. |
| `themes` | array |  | Subject categories listed for the poem. |
| `poem_link` | string | `"https://www.poetryfoundation.org/poems/44272/the-road-not-taken"` |  |
| `poet_page_link` | string or null | `"https://www.poetryfoundation.org/poets/robert-frost"` |  |
| `publication_year` | integer or null | `2024` | Year appearing in the printed source, if shown. |

**Example input**

```json
{
  "poet": "Robert Frost",
  "title": "The Road Not Taken"
}
```

**Example output**

```json
{
  "poet": "Robert Frost",
  "tags": [
    "Graduation",
    "Stanza Forms > Rhymed Stanza"
  ],
  "text": "Two roads diverged in a yellow wood,\nAnd sorry I could not travel both\nAnd be one traveler, long I stood\nAnd looked down one as far as I could\nTo where it bent in the undergrowth;\n\nThen took the other…",
  "title": "The Road Not Taken",
  "source": null,
  "themes": [
    "Activities > Travels & Journeys"
  ],
  "poem_link": "https://www.poetryfoundation.org/poems/44272/the-road-not-taken",
  "poet_page_link": "https://www.poetryfoundation.org/poets/robert-frost",
  "publication_year": null
}
```

### Search poems

Operation `search_poems`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find poems matching a topic or occasion, or poems by a named poet, in Poetry Foundation search order. Older magazine poems without public text have no first two lines; untagged poems have no themes or occasions.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `query` | string | yes | `"wedding"` | Topic, occasion, or poet name, for example grief, wedding, or Mary Oliver. |
| `max_results` | integer | no | `35` | Maximum number of poems to return, for example 20 (up to 50). |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Topic, occasion, or poet name, for example grief, wedding, or Mary Oliver.",
      "examples": [
        "wedding",
        "grief",
        "zzzxxyyqqqnotapoem"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum number of poems to return, for example 20 (up to 50).",
      "x-fous-developer": true,
      "examples": [
        35,
        5
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "query": "wedding",
      "max_results": 35
    },
    {
      "query": "grief"
    },
    {
      "query": "zzzxxyyqqqnotapoem"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `poems` | array |  |  |
| `poems[].poet` | string or null | `"Ross Gay"` |  |
| `poems[].title` | string | `"Wedding Poem"` |  |
| `poems[].poem_link` | string | `"https://www.poetryfoundation.org/poems/58761/wedding-poem"` |  |
| `poems[].first_two_lines` | string or null | `"Friends I am here to modestly report\nseeing in an orchard"` | The first two available lines, separated by a newline; null if the poem text is not published. |
| `poems[].themes_or_occasions` | array |  |  |

**Example input**

```json
{
  "query": "wedding",
  "max_results": 35
}
```

**Example output**

```json
{
  "poems": [
    {
      "poet": "Ross Gay",
      "title": "Wedding Poem",
      "poem_link": "https://www.poetryfoundation.org/poems/58761/wedding-poem",
      "first_two_lines": "Friends I am here to modestly report\nseeing in an orchard",
      "themes_or_occasions": [
        "Love",
        "Nature",
        "Animals"
      ]
    },
    {
      "poet": "Denise Levertov",
      "title": "Wedding-Ring",
      "poem_link": "https://www.poetryfoundation.org/poems/53080/wedding-ring",
      "first_two_lines": "My wedding-ring lies in a basket\nas if at the bottom of a well.",
      "themes_or_occasions": [
        "Social Commentaries",
        "Relationships",
        "Breakups & Separation"
      ]
    },
    {
      "poet": "Sidney Lanier",
      "title": "Wedding Hymn",
      "poem_link": "https://www.poetryfoundation.org/poems/50297/wedding-hymn",
      "first_two_lines": "Thou God, whose high, eternal Love\nIs the only blue sky of our life,",
      "themes_or_occasions": [
        "Love",
        "Religion",
        "Living"
      ]
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@poetry-foundation",
  "visibility": "public",
  "operation": "get_poem",
  "version": 1,
  "input": {
    "poet": "Robert Frost",
    "title": "The Road Not Taken"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@poetry-foundation\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_poem\",\n  \"version\": 1,\n  \"input\": {\n    \"poet\": \"Robert Frost\",\n    \"title\": \"The Road Not Taken\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@poetry-foundation",
  "visibility": "public",
  "operation": "get_poem",
  "version": 1,
  "input": {
    "poet": "Robert Frost",
    "title": "The Road Not Taken"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/poetry-foundation`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_poem`: Get poem. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `search_poems`: Search poems. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-poetry-foundation https://api.fous.com/mcp/tools/poetry-foundation --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Find poems about a topic or occasion
- Browse poems by a named poet
- Retrieve a poem’s full public text
- Review poem themes and occasions
- Check a poem’s source and publication year when shown

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Poetry Foundation tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Poetry Foundation account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from poetryfoundation.org when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Oct 7, 2026.

### How can I find poems about a topic?

Search poems finds matching poems by topic or occasion.

### How can I find poems by a poet?

Search poems finds poems matching a poet’s name.

### How can I retrieve a poem’s full text?

Get poem returns the full public text when you provide its title; you can add a poet to distinguish identical titles.

## Related

- [BrainyQuote API](https://fous.com/tools/brainyquote.md): BrainyQuote returns topic-matched quotes in displayed order, a person’s description and up to 100 quotes with topic tags and links, or the quote shown for the chosen daily category and BrainyQuote’s current day.
- [Project Gutenberg API](https://fous.com/tools/project-gutenberg.md): Project Gutenberg offers free public-domain ebooks and reading materials, with searchable book details and plain text from the most-downloaded matching edition available.
- [Open Library API](https://fous.com/tools/open-library.md): Open Library returns book search results, catalog details, and author works; availability reflects listed editions, not current loan availability, and catalog details may be missing.
- [Wikipedia API](https://fous.com/tools/wikipedia.md): Wikipedia returns article summaries, images, facts, relevant search matches, readable text and daily historical events, plus human-view counts from July 2015 onward.
- [Goodreads API](https://fous.com/tools/goodreads.md): Goodreads returns public book searches, matched-book details with variable editions, popular or newest reviews, author books by popularity or date, and up to 100 quotes.
- [Quran.com API](https://fous.com/tools/quran-com.md): Quran.com provides Quran reading and search: up to 50 verses with Arabic and translations, optional transliteration, and only the first 50 verses of longer passages.
- [Bible Gateway API](https://fous.com/tools/bible-gateway.md): Bible Gateway provides passage readings up to one chapter, searches returning up to 100 related verses, and a daily verse that may differ by date or translation availability.
- [PubMed API](https://fous.com/tools/pubmed.md): PubMed searches medical and life-science articles by topic and retrieves one article’s abstract and publication details; abstracts and free full-text links may be unavailable.
- [All Education tools](https://fous.com/tools/category/education)