NAV Navbar
shell
  • Introduction
  • Misc. Services
  • Errors

    • Introduction

    Welcome to the Poemist API! You can use our API to access Poemist API endpoints, which can get information on various poets and poems in our database.

    Misc. Services

    Get Random Poems

    curl "https://www.poemist.com/api/v1/randompoems"

    The above command returns JSON structured like this:

    [
  {
    "title": "Go Back To The Tainted Lap, Leah",
    "content": "Go back to the tainted lap, Leah,\nWhence you came,\nBecau... rest of the poem will be here",
    "url": "https://www.poemist.com/osip-emilevic-mandelstam/go-back-to-the-tainted-lap-leah",
    "poet": {
      "name": "Osip Emilevic Mandelstam",
      "url": "https://www.poemist.com/osip-emilevic-mandelstam"
    }
  },
  {
    "title": "Since Then",
    "content": "I found myself among the trees\nWhat time the reapers ceased to reap;\nAnd in the ... rest of the poem will be here",
    "url": "https://www.poemist.com/madison-julius-cawein/since-then",
    "poet": {
      "name": "Madison Julius Cawein",
      "url": "https://www.poemist.com/madison-julius-cawein"
    }
  },
]

    This endpoint retrieves random poems.

    HTTP Request

    GET https://www.poemist.com/api/v1/randompoems

    Query Parameters

    There is no parameters for this service.

    Errors

    The Poemist API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The resource requested is hidden for administrators only.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- You tried to access a resource with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    410 Gone -- The resource requested has been removed from our servers.
    429 Too Many Requests -- You're making too many requests! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
    shell