# Qillqay

> Qillqay is a REST API that generates SEO-optimized articles from a single keyword. Built on Cloudflare Workers, powered by Mistral Large with integrated SERP analysis via DataForSEO. Articles are returned as Markdown with meta title, meta description, and structured headings. Supports French, English, Spanish, and German.

Authenticate with an API key (format `qlly_...`) sent in the `X-Qillqay-Key` header. Pricing ranges from $0.50 to $1.50 per article depending on plan. Get a key at https://qillqay.app/#pricing.

## Quickstart

    curl -X POST https://qillqay.app/api/v1/generate -H "X-Qillqay-Key: qlly_..." -H "Content-Type: application/json" -d '{"keyword":"best running shoes","lang":"en","word_count":1200}'

## API documentation

- [Swagger UI](https://qillqay.app/docs): Interactive API explorer
- [OpenAPI 3.1 spec](https://qillqay.app/openapi.yaml): Machine-readable definition
- [Health check](https://qillqay.app/health): Service status (no auth required)

## Core endpoints

- `POST /api/v1/generate`: Generate an SEO article. Body `{ keyword, lang, tone?, word_count? }`. Returns Markdown plus tokens and cost metadata. Auth required.
- `GET /api/v1/articles`: Paginated list of past articles for the authenticated key. Query `page`, `per_page`.
- `GET /api/v1/articles/{id}`: Retrieve a single article by ID. Auth required.
- `GET /api/v1/usage`: Usage stats for the authenticated key (articles, tokens, cost). Query `days` (1-365, default 30).

## Billing endpoints

- `POST /api/v1/billing/checkout`: Create a Stripe checkout session. Body `{ plan, email }`. Public, no auth required.
- `GET /api/v1/billing/claim-key`: One-time retrieval of a fresh API key after a successful checkout. Query `session_id=cs_...`.
- `POST /api/v1/billing/rotate-key`: Deactivate the current key and return a new one. Auth required.

## Plans

- Starter: $1.50 per article, 10-article packs at $15, 10 requests per minute
- Pro: $39 per month for 30 articles, 30 requests per minute
- Agency: $99 per month for 100 articles, 60 requests per minute
- Volume: $0.50 per article, 1000+ pack, 100 requests per minute

## Article languages

`lang` parameter: `fr` (French, default), `en` (English), `es` (Spanish), `de` (German).

## Landing pages

- [Qillqay - English](https://qillqay.app/?lang=en)
- [Qillqay - French](https://qillqay.app/?lang=fr)
- [Qillqay - Spanish](https://qillqay.app/?lang=es)

## Optional

- Output format: Markdown body plus YAML frontmatter (meta_title, meta_description, word_count, headings).
- Article status flow: pending -> processing -> completed or failed.
- Rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, plus Retry-After on 429.
- Contact: support@qillqay.app