---
name: xpolink
description: Manage branded short links via the Xpolink API. Run /xpolink to create, list, update, or manage links, domains, and API keys without leaving your editor.
---

# Xpolink — Branded Short Links

You are a skill that manages branded short links using the Xpolink API. When the user runs `/xpolink`, follow these steps:

## Step 1: Check for API Key

Check if the environment variable `XPOLINK_API_KEY` is set:

```bash
echo $XPOLINK_API_KEY
```

If the variable is **empty or not set**, ask the user:

> "I need your Xpolink API key to manage short links. You can generate one at https://xpolink.app/dashboard/settings/api-keys
>
> Please paste your API key:"

Once the user provides the key, store it in their global shell config so it works across all projects:

```bash
echo '\nexport XPOLINK_API_KEY="<THE_KEY>"' >> ~/.zshenv
```

If the user uses bash instead of zsh, use `~/.bashrc` instead. Then export it for the current session:

```bash
export XPOLINK_API_KEY="<THE_KEY>"
```

**IMPORTANT:** Never store the API key in the skill file, in any project file, or in any commit. It must only live in the user's global shell environment.

## Step 2: Determine the Action

Ask the user what they'd like to do, or infer from context. Supported actions:

- **Create a link** — shorten a URL
- **List links** — show existing links
- **Get link details** — view a specific link
- **Update a link** — change URL, title, status, or redirect type
- **View link stats** — see click analytics
- **Delete a link** — remove a link
- **Export clicks** — download click analytics as CSV (Business plan)
- **List captured emails** — view email gate submissions (Business plan)
- **Export emails** — download captured emails as CSV (Business plan)
- **List domains** — show custom domains
- **Add a domain** — register a new custom domain
- **Verify a domain** — check DNS verification status
- **Delete a domain** — remove a custom domain
- **Import links** — bulk import from JSON (Pro/Business)

If the user just says `/xpolink` with no further context, look for a URL in their current context (selection, clipboard, or file) and offer to create a short link for it. If no URL is found, ask what they'd like to do.

## Step 3: Execute the Action

### Create a link
```bash
curl -s -X POST https://xpolink.app/api/v1/links \
  -H "Authorization: Bearer $XPOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "<LONG_URL>"}'
```
Optional body fields: `shortCode` (custom slug), `title` (friendly name), `domain` (custom domain hostname).

### List links
```bash
curl -s https://xpolink.app/api/v1/links?page=1 \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```
Optional query params: `page` (number), `search` (text).

### Get link details
```bash
curl -s https://xpolink.app/api/v1/links/<ID> \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```

### Update a link
```bash
curl -s -X PATCH https://xpolink.app/api/v1/links/<ID> \
  -H "Authorization: Bearer $XPOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "<NEW_URL>", "title": "<TITLE>", "isActive": true, "redirectType": 301}'
```
All fields optional. `longUrl` editing requires Pro+ plan.

### View link stats
```bash
curl -s https://xpolink.app/api/v1/links/<ID>/stats \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```

### Delete a link
```bash
curl -s -X DELETE https://xpolink.app/api/v1/links/<ID> \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```

### Export clicks (Business plan)
```bash
curl -s https://xpolink.app/api/v1/links/<ID>/export \
  -H "Authorization: Bearer $XPOLINK_API_KEY" \
  -o clicks.csv
```

### List captured emails (Business plan)
```bash
curl -s "https://xpolink.app/api/v1/links/<ID>/emails?page=1" \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```

### Export captured emails (Business plan)
```bash
curl -s https://xpolink.app/api/v1/links/<ID>/emails/export \
  -H "Authorization: Bearer $XPOLINK_API_KEY" \
  -o emails.csv
```

### List domains
```bash
curl -s https://xpolink.app/api/v1/domains \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```

### Add a domain
```bash
curl -s -X POST https://xpolink.app/api/v1/domains \
  -H "Authorization: Bearer $XPOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "<HOSTNAME>"}'
```
Returns DNS records (CNAME/A + TXT) to configure at the registrar.

### Verify a domain
```bash
curl -s -X POST https://xpolink.app/api/v1/domains/<ID>/verify \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```

### Delete a domain
```bash
curl -s -X DELETE https://xpolink.app/api/v1/domains/<ID> \
  -H "Authorization: Bearer $XPOLINK_API_KEY"
```

### Bulk import (Pro/Business)
```bash
curl -s -X POST https://xpolink.app/api/v1/links/import \
  -H "Authorization: Bearer $XPOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @links.json
```
JSON file: array of objects with `url` (required), `short_code`, `domain`, `title`. Max 500 per import.

## Step 4: Return the Result

Parse the JSON response and present results clearly:

- **Create**: show the short URL (`https://{domainHostname}/{shortCode}`)
- **List**: show links in a readable format with short URL, destination, and click count
- **Stats**: show total clicks, top countries, and retention period
- **Export**: confirm the file was saved and its path
- **Domains**: show hostname, verification status, and DNS records for unverified domains
- **Errors**: show the error message from the response (e.g., plan limits, invalid URL, auth failure)

## API Reference Summary

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /links | Create a short link |
| GET | /links | List links (paginated) |
| GET | /links/:id | Get link details |
| PATCH | /links/:id | Update a link |
| DELETE | /links/:id | Delete a link |
| GET | /links/:id/stats | Link analytics |
| GET | /links/:id/export | Export clicks CSV (Business) |
| GET | /links/:id/emails | List captured emails (Business) |
| GET | /links/:id/emails/export | Export emails CSV (Business) |
| POST | /links/import | Bulk import (Pro/Business) |
| GET | /domains | List domains |
| POST | /domains | Add a domain |
| GET | /domains/:id | Get domain details |
| POST | /domains/:id/verify | Verify domain DNS |
| DELETE | /domains/:id | Delete a domain |
| GET | /api-keys | List API keys |
| POST | /api-keys | Create an API key |
| DELETE | /api-keys/:id | Delete an API key |

Base URL: `https://xpolink.app/api/v1`
Auth: `Authorization: Bearer <API_KEY>`