# cliqo API — LLM / agent context

cliqo is a URL shortener. This is a concise, machine-readable guide to its public REST API (v1). Paste it into your AI coding agent so it can build integrations against cliqo.

## Basics
- Base URL: https://api.cliqo.link
- Short links are returned on the short domain (clq.sh); the API itself lives on api.cliqo.link.
- Format: JSON request and response bodies.
- Auth: send your API key as a Bearer token on every request — `Authorization: Bearer YOUR_API_KEY`.
- Create an API key in the dashboard under API keys; it is shown only once.
- One link credit is consumed per created link. A link's destination (url) is fixed once created — to point somewhere else, create a new link. Its metadata (name, tags, password, UTM params, QR config) can be edited with PATCH.

## Scopes
- `links:read` — List and read your links
- `links:write` — Create and update links (implies links:read)
- `links:delete` — Revoke links (implies links:write)
- `billing:read` — Read your link credit balance

## Endpoints
### GET /api/v1/links  (scope: links:read)
List the authenticated user's links, newest first by default.
Query params:
- sort[id] — asc | desc — also sort[shortCode], sort[url], sort[name]
- tags.name — Exact tag name to filter by
- exists[deletedAt] — true | false — include or exclude revoked links
Example:
```bash
curl -s "https://api.cliqo.link/api/v1/links?sort[id]=desc" \
  -H "Authorization: Bearer $CLIQO_API_KEY" \
  -H "Accept: application/json"
```

### GET /api/v1/links/{id}  (scope: links:read)
Retrieve a single link you own by id. Returns 404 if it doesn't exist or isn't yours.
Example:
```bash
curl -s "https://api.cliqo.link/api/v1/links/123" \
  -H "Authorization: Bearer $CLIQO_API_KEY" \
  -H "Accept: application/json"
```

### POST /api/v1/links  (scope: links:write)
Create a shortened link. Consumes one link credit. Only url is required; every other field is optional.
Body fields:
- url (required) — The destination URL to shorten
- name — A label for the link
- password — Protect the link (write-only, never returned)
- qrConfig — QR options, e.g. { "size": 300, "margin": 10 }
- utmSource…utmContent — UTM parameters (letters, numbers, - , _)
- tags — Array of tag IRIs, e.g. ["/app/tags/1"]
Example:
```bash
curl -s -X POST "https://api.cliqo.link/api/v1/links" \
  -H "Authorization: Bearer $CLIQO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/some/long/url",
    "name": "My campaign link",
    "utmSource": "newsletter",
    "utmCampaign": "spring_sale"
  }'
```
Example response:
```json
{
  "id": 123,
  "shortLink": "https://clq.sh/k7Bx2",
  "url": "https://example.com/some/long/url",
  "name": "My campaign link"
}
```

### PATCH /api/v1/links/{id}  (scope: links:write)
Update an existing link's mutable metadata. Does not consume a credit. Send only the fields you want to change; the destination url, domain, expiry and max redirects are fixed at creation and rejected here (400).
Body fields (all optional):
- name — A label for the link
- password — Protect the link (write-only; send "" to remove it)
- qrConfig — QR options, e.g. { "size": 300, "margin": 10 }
- utmSource…utmContent — UTM parameters (letters, numbers, - , _)
- tags — Array of tag IRIs, e.g. ["/app/tags/1"]
Example:
```bash
curl -s -X PATCH "https://api.cliqo.link/api/v1/links/123" \
  -H "Authorization: Bearer $CLIQO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed link", "utmCampaign": "summer_sale" }'
```

### DELETE /api/v1/links/{id}  (scope: links:delete)
Revoke (soft-delete) a link you own. Returns 204 No Content on success.
Example:
```bash
curl -s -X DELETE "https://api.cliqo.link/api/v1/links/123" \
  -H "Authorization: Bearer $CLIQO_API_KEY"
```

### GET /api/v1/credits  (scope: billing:read)
Get your remaining link credits. Each link creation consumes one credit.
Example:
```bash
curl -s "https://api.cliqo.link/api/v1/credits" \
  -H "Authorization: Bearer $CLIQO_API_KEY"
```
Example response:
```json
{ "links": 72 }
```

## Errors
- 400 Bad request — Malformed body, or an immutable field (e.g. url) sent to PATCH.
- 401 Unauthorized — Missing or invalid API key.
- 403 Forbidden — The key is valid but lacks the required scope.
- 404 Not found — The resource doesn't exist or isn't yours.
- 422 Unprocessable — Validation failed, or you're out of link credits.