# Qafiyah API

> Qafiyah is an open-source project dedicated to the Arabic language, making its poetic heritage freely accessible to researchers, developers, and poetry lovers alike. This is its public, read-only API: structured, reliable data over JSON/HTTPS. No key is needed; anonymous callers share a per-address hourly limit, and a free key from https://qafiyah.com/developers raises it (send it as the x-api-key header).

Base URL: https://api.qafiyah.com/v1

## Documentation

- [OpenAPI spec](https://api.qafiyah.com/v1/openapi.json): Machine-readable OpenAPI 3 specification
- [Interactive reference](https://api.qafiyah.com/v1/docs): Rendered API docs

## Endpoints

- [GET /v1/poems](https://api.qafiyah.com/v1/poems): List and filter poems. Query params: page, poet, era, theme, meter, rhyme, collection (slug filters repeatable)
- [GET /v1/poems/{slug}](https://api.qafiyah.com/v1/poems): Full poem by slug
- [GET /v1/poems/slugs](https://api.qafiyah.com/v1/poems/slugs): Poem slugs, paginated (for sitemaps)
- [GET /v1/poems/count](https://api.qafiyah.com/v1/poems/count): Total number of poems
- [GET /v1/poems/random](https://api.qafiyah.com/v1/poems/random): Random poem as text/plain (append ?option=lines for verse content)
- [GET /v1/poets](https://api.qafiyah.com/v1/poets): List poets. Query params: page, era
- [GET /v1/poets/{slug}](https://api.qafiyah.com/v1/poets): Poet by slug
- [GET /v1/poets/slugs](https://api.qafiyah.com/v1/poets/slugs): Slugs of poets with at least one poem, paginated (for sitemaps)
- [GET /v1/eras](https://api.qafiyah.com/v1/eras): List historical eras with counts
- [GET /v1/eras/{slug}](https://api.qafiyah.com/v1/eras): Era by slug
- [GET /v1/meters](https://api.qafiyah.com/v1/meters): List classical Arabic meters with counts
- [GET /v1/meters/{slug}](https://api.qafiyah.com/v1/meters): Meter by slug
- [GET /v1/rhymes](https://api.qafiyah.com/v1/rhymes): List rhyme letters with counts
- [GET /v1/rhymes/{slug}](https://api.qafiyah.com/v1/rhymes): Rhyme by slug
- [GET /v1/themes](https://api.qafiyah.com/v1/themes): List themes with counts
- [GET /v1/themes/{slug}](https://api.qafiyah.com/v1/themes): Theme by slug
- [GET /v1/collections](https://api.qafiyah.com/v1/collections): List curated collections with counts
- [GET /v1/collections/{slug}](https://api.qafiyah.com/v1/collections): Collection by slug
- [GET /v1/search](https://api.qafiyah.com/v1/search): Full-text search across poems and poets. Query params: q, types, poemsPage, poetsPage, and slug filters

## Links

- [Website](https://qafiyah.com)