# Suggest slugs with AI

`POST https://app.clik.so/api/links/ai-slug`

> **In short:** Suggests up to three short, readable slugs for a destination URL, from the URL and the title and description you send. Each call uses one of your workspace's daily AI slug credits.

## You need

* **API key permission:** `write`
* **Workspace role:** editor or higher
* **Plan:** any plan, including Free

## Example

```bash
curl -X POST "https://app.clik.so/api/links/ai-slug" \
  -H "Authorization: Bearer $CLIKSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/summer-sale",
    "title": "Summer sale — 30% off everything"
  }'
```

Response 200:

```json
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "slugs": [
      "summer-sale",
      "sale-30-off",
      "summer-deals"
    ]
  }
}
```

## Request body

| Field         | Type            | Required | Description                                                                          |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------ |
| `url`         | string · uri    | yes      | The destination page. Must be http(s).                                               |
| `title`       | string          | no       | The page title, if you have it. The AI does not fetch the page, so this helps a lot. |
| `description` | string          | no       | A page description, if you have it.                                                  |
| `exclude`     | array of string | no       | Codes you do not want suggested again. Only the first 50 are used. Up to 50 items    |

## Common errors

| Status | Code                  | When                                                                               |
| ------ | --------------------- | ---------------------------------------------------------------------------------- |
| 401    | `UNAUTHORIZED`        | The API key is missing, malformed or unknown.                                      |
| 403    | `FORBIDDEN`           | The key only has Read permission, or its creator is a viewer in this workspace.    |
| 422    | `VALIDATION_ERROR`    | `url` is missing or is not an http(s) URL.                                         |
| 429    | `USAGE_LIMIT_REACHED` | The workspace used today's AI slug credits. They reset at midnight UTC.            |
| 429    | `RATE_LIMITED`        | More than 15 calls in a minute from this workspace, or the key's per-minute limit. |
| 500    | `INTERNAL_ERROR`      | The AI service failed or returned nothing usable. Try again, or use a random slug. |

## Good to know

* Rate limit: 15 calls per minute per workspace, plus the plan's daily AI slug quota: Free 10, Starter 30, Pro 200, Business unlimited (per UTC day).
* Suggestions are lower-case letters, digits and hyphens, 4 to 20 characters. You get at most 3, sometimes fewer.
* They are **not** checked for availability. Check one with [Check a slug](https://clik.so/docs/api/links/check-slug), or just create the link and handle `409`.
* Every successful call uses one credit, even if you use none of the suggestions. See what is left with [Get AI slug usage](https://clik.so/docs/api/links/get-ai-slug-usage).
* The AI does not open the page. It works from the URL and any `title` and `description` you send — get those from [Preview a page's social card](https://clik.so/docs/api/links/preview-link) first for better ideas.
* Send `exclude` with codes you already rejected to get new ideas. The first 50 are kept; put the ones you most want to avoid first.
* If the AI service is down you get `500 INTERNAL_ERROR`. Fall back to [Generate a random slug](https://clik.so/docs/api/links/generate-slug).

---

Source: https://clik.so/docs/api/links/suggest-slugs