# AI slug suggestions Clikso's AI suggests short, readable slugs for a destination URL. Check that one is free, then use it to create your link. > **In short:** > > Send a destination URL and get up to three short, readable slug ideas back. Check that the one you like is free, then create the link with it. Each call uses one of your workspace's daily AI slug credits. A slug is the part of a short link after the domain. In `clik.is/summer-sale`, the slug is `summer-sale`. The API calls it `short_code`. ## You need * **An API key:** **Write** permission. A suggestion uses a credit, so it counts as a change. * **A role:** Editor or admin in the key's workspace. * **A plan:** Any plan, including Free. The number of credits per day depends on the plan. ## Get a slug for a link ### Step 1. Ask for ideas Send the destination URL. Add the page's title and description if you have them. The AI works from the URL and the text you send. It does not open the page itself. ```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" ] } } ``` To get a page's title, call [Preview a page's social card](https://clik.so/docs/api/links/preview-link) first and pass its `og_title` along. ### Step 2. Check that the slug is free The ideas are not checked against links that already exist. Ask whether the one you like is still free on your domain. ```bash curl "https://app.clik.so/api/links/slug-check?slug=sale-30-off&domain=clik.is" \ -H "Authorization: Bearer $CLIKSO_API_KEY" ``` Response 200: ```json { "status": 200, "success": true, "message": "Success", "data": { "available": true, "slug": "sale-30-off" } } ``` ### Step 3. Create the link Use the slug as `short_code` when you create the link. ```bash curl -X POST "https://app.clik.so/api/links" \ -H "Authorization: Bearer $CLIKSO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destination_url": "https://example.com/summer-sale", "short_code": "sale-30-off" }' ``` You get the new link back, just like in the [Quickstart](https://clik.so/docs/quickstart). If someone took the slug in the meantime, you get `409 CONFLICT`. Try the next idea. ### Want different ideas? Send the slugs you already turned down in `exclude`. The AI then tries to avoid them. Put the ones you most want to skip first. ```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", "exclude": [ "summer-sale", "sale-30-off", "summer-deals" ] }' ``` Response 200: ```json { "status": 200, "success": true, "message": "Success", "data": { "slugs": [ "hot-summer", "sun-sale", "big-summer-deal" ] } } ``` ## Check your daily credits This call tells you how many suggestions your workspace used today and how many are left. It is a `POST`, but it only reads the count. ```bash curl -X POST "https://app.clik.so/api/links/ai-slug/consume" \ -H "Authorization: Bearer $CLIKSO_API_KEY" ``` Response 200: ```json { "status": 200, "success": true, "message": "Success", "data": { "used_today": 3, "limit": 10, "remaining": 7 } } ``` On a plan with no daily limit, `limit` and `remaining` are `-1`. | Limit | Free | Starter | Pro | Business | | ---------------------------------------------------------------- | ---- | ------- | --- | --------- | | AI slug suggestions per day (Per workspace, resets at 00:00 UTC) | 10 | 30 | 200 | Unlimited | ## What you get back * **Suggest slugs:** `data.slugs`, a list of up to three ideas. They use lower-case letters, digits and hyphens. * **Check a slug:** `data.available` is `true` when the slug is free, and `data.slug` repeats it. When it is `false`, `data.reason` and `data.message` may say why. * **AI slug usage:** `used_today`, `limit` and `remaining`. ## Common errors | Status | Code | What it means | What to do | | ------ | --------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | 401 | `UNAUTHORIZED` | The key is missing or wrong. | Send `Authorization: Bearer clik_live_…` with a key from Settings → API. | | 403 | `FORBIDDEN` | The key only has Read permission, or its creator is a viewer. | Check the key’s permission and your role. If you send `Workspace-Id`, it must match the key’s workspace. | | 422 | `VALIDATION_ERROR` | `url` is missing, or does not start with `http://` or `https://`. | Fix the field and send the request again. | | 429 | `USAGE_LIMIT_REACHED` | Your workspace used all of today's AI slug credits. | Wait for the reset at 00:00 UTC, or upgrade. | | 429 | `RATE_LIMITED` | Too many suggestions this minute, or the key went over its own limit. | Wait the number of seconds in the `Retry-After` header, then try again. | | 500 | `INTERNAL_ERROR` | The AI service failed or gave nothing usable. | Try again, or use [Generate a random slug](https://clik.so/docs/api/links/generate-slug). | ## Good to know * Each successful call uses one credit, even if you use none of the ideas. A call that fails does not use one. * Credits are counted per workspace, not per key. All your keys share them. * Credits reset at 00:00 UTC. * On top of the daily credits, a workspace can ask for at most 15 suggestions a minute. * You may get fewer than three ideas. Ideas that Clikso would refuse on its own domains are left out. * `exclude` takes up to 50 slugs. Extra ones are ignored. * You never need an AI slug to make a link. Leave out `short_code` and Clikso picks a random 7-character one. --- Source: https://clik.so/docs/guides/ai-slugs