Poetry Foundation API: Search poems
Finds 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.
Unofficial. Not affiliated with or endorsed by Poetry Foundation.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Query, required
query Topic, occasion, or poet name, for example grief, wedding, or Mary Oliver.
wedding
- Max Results optional
max_results Maximum number of poems to return, for example 20 (up to 50).
50
Whole number from 1 to 50. Default
20.
Input as JSON
{ "query": "wedding", "max_results": 50}Output
{ "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" ] } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"poetryfoundation.org/search_poems","input":{"query":"wedding","max_results":50}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "poetryfoundation.org/search_poems" , "input": { "query": "wedding", "max_results": 50 }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "poetryfoundation.org/search_poems" , "input": { "query": "wedding", "max_results": 50 } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run poetryfoundation.org/search_poems# with {"query":"wedding","max_results":50}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "description": "Topic, occasion, or poet name, for example grief, wedding, or Mary Oliver." }, "max_results": { "type": "integer", "default": 20, "maximum": 50, "minimum": 1, "description": "Maximum number of poems to return, for example 20 (up to 50)." } }}Output schema
{ "type": "object", "required": [ "poems" ], "properties": { "poems": { "type": "array", "items": { "type": "object", "required": [ "title", "poet", "first_two_lines", "themes_or_occasions", "poem_link" ], "properties": { "poet": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "poem_link": { "type": "string" }, "first_two_lines": { "type": [ "string", "null" ], "description": "The first two available lines, separated by a newline; null if the poem text is not published." }, "themes_or_occasions": { "type": "array", "items": { "type": "string" } } } } } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
poetryfoundation.org/search_poems- Returns
- title, poet, first two lines, themes or occasions, poem link
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method poetryfoundation.org/search_poems with the inputs above.
Ask your agent
- Find me about 10 poems about grief I could read at a memorial service
- What poems by Langston Hughes are on poetryfoundation.org? Give me titles and links.
- I need wedding poems for a toast — show me the first couple of lines of each so I can pick one
- Search Poetry Foundation for poems about the ocean, up to 50 results
- List poems by Emily Dickinson along with their themes
See more
All Poetry Foundation methodsFinds a poem on Poetry Foundation by title (optionally by poet) and returns its full public text, poet, printed source, publication year and subject tags.
poetryfoundation.org/get_poemFinds Quran.com verses matching a word or topic, with Arabic text and a translation in the selected language, in Quran.com search order.
quran.com/search_quranSearches Britannica for encyclopedia articles and returns their titles, short descriptions, article links and images when shown. Excludes other search formats such as videos, questions and stories.
britannica.com/search_articlesFinds free public-domain Project Gutenberg books by title, author or topic, with authors, languages, subjects, recent downloads, and reading and download links. Public-domain status is based on the United States.
gutenberg.org/search_free_booksFinds Bible verses on Bible Gateway that contain the search words or relate to a topic. Returns the verse text and links in Bible order.
biblegateway.com/search_bibleFinds Open Library books by search words, optionally narrowed by author and subject, sorted by relevance or publication age. Returns work-level results; free_online means at least one edition is marked public or borrowable, not that a loan is available now.
openlibrary.org/search_booksSearches Library of Congress digital collections by keywords, material format and date range, in Library search relevance order. Rights notes may be unavailable for some records.
loc.gov/search_collectionsFinds public Substack newsletters matching a topic, in Substack's search order. Subscriber counts are null when Substack does not display one.
substack.com/search_newsletters