# AI features

Source: https://developers.leonai.io/docs/guides/ai/

:::danger[Not available yet]
These endpoints are **not deployed**. Every path on this page returns 404 against the
production API today. They were built for the previous API stack and have not been
ported to the Cloudflare Workers API that now serves `api.short.leonai.io`.

This page is kept as the design of the intended contract. Do not write integrations
against it yet — check the [API Reference](https://developers.leonai.io/docs/api-reference/), which is generated from
the running API, for what actually exists.
:::

LeonAI exposes AI-assisted endpoints for slug suggestions, link insights, and anomaly
detection. All AI endpoints require a **JWT** and are under `/api/v1/ai`.

:::note[Provider & determinism]
The AI layer is provider-agnostic. It defaults to a deterministic **heuristic** provider
(no API key needed). When `ANTHROPIC_API_KEY` is configured on the server it uses
**Anthropic Claude** to phrase text — but all analytics, trend, and anomaly math is
computed deterministically regardless of provider, and any LLM failure falls back to the
heuristic. Check the active provider with `GET /api/v1/ai/status`.
:::

## Suggest a slug — all tiers

```bash
curl -X POST https://api.short.leonai.io/api/v1/ai/suggest-slug \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "longUrl": "https://example.com/spring-sale-2026", "keywords": ["spring", "sale"], "count": 5 }'
```

`REST: POST /api/v1/ai/suggest-slug`. Body: `longUrl` (required), `keywords` (optional,
up to 10), `count` (optional, 3–5). Suggestions exclude reserved words and short codes
already taken:

```json
{
  "success": true,
  "data": {
    "provider": "heuristic",
    "suggestions": ["spring-sale", "spring-sale-26", "sale-spring"]
  }
}
```

## Link insights — Business+

```bash
curl -X POST https://api.short.leonai.io/api/v1/ai/insights \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "linkId": "link_...", "refresh": false }'
```

`REST: POST /api/v1/ai/insights` (requires the `aiInsights` feature — Business+). Body:
`linkId` (required), `refresh` (optional; results are cached one hour per link). Returns
a 14-day rollup with top referrer/device/country, best hour (UTC), a trend
(`up`/`down`/`flat` + `changePct`), and human-readable `recommendations`:

```json
{
  "success": true,
  "data": {
    "linkId": "link_...",
    "windowDays": 14,
    "totalClicks": 1280,
    "uniqueVisitors": 940,
    "topReferrer": { "referrer": "twitter.com", "count": 410 },
    "topDevice": { "device": "mobile", "count": 780 },
    "topCountry": { "country": "US", "count": 610 },
    "bestHourUtc": { "hour": 15, "clicks": 120 },
    "trend": {
      "currentPeriodClicks": 700,
      "previousPeriodClicks": 580,
      "changePct": 20.7,
      "direction": "up"
    },
    "provider": "anthropic",
    "recommendations": ["Post around 15:00 UTC to hit your peak hour."],
    "cached": false,
    "generatedAt": "2026-07-10T12:00:00.000Z"
  }
}
```

## Anomaly detection — all tiers

```bash
curl -X POST https://api.short.leonai.io/api/v1/ai/anomalies \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "linkId": "link_...", "days": 30, "recentDays": 1 }'
```

`REST: POST /api/v1/ai/anomalies` (pure heuristic — no LLM). Body: `linkId` (required),
`days` (7–90, default 30), `recentDays` (1–7, default 1). It compares recent clicks to a
trailing baseline using a z-score (threshold ±2, with a ratio fallback):

```json
{
  "success": true,
  "data": {
    "linkId": "link_...",
    "hasAnomaly": true,
    "kind": "spike",
    "magnitude": 3.1,
    "zScore": 2.6,
    "message": "Clicks are unusually high today.",
    "baseline": { "meanDailyClicks": 40, "stdDev": 8, "days": 30 },
    "recent": { "clicks": 165, "days": 1 }
  }
}
```

## Status

```bash
curl https://api.short.leonai.io/api/v1/ai/status -H "Authorization: Bearer <jwt>"
```

`REST: GET /api/v1/ai/status` → `{ success, data: { provider: "heuristic" | "anthropic", features: ["suggest-slug", "insights", "anomalies"] } }`.