REST API Reference

Authentication

The ClicAven API uses API keys for authentication. Each request must include your key in the Authorization header.

How to get an API key

1. Log in to your ClicAven account and go to the API Keys page
2. Name your key and click Create
3. Copy the displayed key — it won't be shown again

Required headers

Authorization: Bearer ca_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST/api/links

Create a new short link. Requires a valid API key.

Required headers

Authorization: Bearer ca_votre_cle_api
Content-Type: application/json

Request body

{
  "url": "https://example.com/une-url-tres-longue",
  "title": "Promo Noël LinkedIn",
  "customSlug": "promo-noel",
  "domainHostname": "go.mon-domaine.com",
  "permanent": true
}

The title field is optional (120 characters maximum). It is used to find the link in the dashboard and the CSV export; it is never shown publicly.

Link fields

The full, current schema is published as OpenAPI 3.1: /api/openapi.json and /api/openapi.yaml. It is generated from the code, so it is the authoritative reference.

Response (201 Created)

{
  "@context": "/api/contexts/Link",
  "@id": "/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "@type": "Link",
  "id": "01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "url": "https://example.com/une-url-tres-longue",
  "short": "aB3xYz",
  "shortUrl": "https://clicaven.com/aB3xYz",
  "title": "Promo Noël LinkedIn",
  "clickCount": 0,
  "createdAt": "2026-04-18T12:00:00+00:00",
  "permanent": true,
  "domainHostname": null
}

curl example

curl -s -X POST https://clicaven.com/api/links \
  -H "Authorization: Bearer ca_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page-longue?utm_source=api","title":"Campagne API"}'

GET/api/links

List all your short links. Requires a valid API key.

curl example

curl -s https://clicaven.com/api/links \
  -H "Authorization: Bearer ca_votre_cle_api" | jq .

Response (200 OK)

{
  "@context": "/api/contexts/Link",
  "@id": "/api/links",
  "@type": "Collection",
  "totalItems": 1,
  "member": [
    {
      "@id": "/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9",
      "@type": "Link",
      "id": "01a08b81-78ad-7720-a4c8-3133c7752bb9",
      "url": "https://example.com/page-longue",
      "short": "aB3xYz",
      "shortUrl": "https://clicaven.com/aB3xYz",
      "title": "Promo Noël LinkedIn",
      "clickCount": 14,
      "createdAt": "2026-04-18T12:00:00+00:00",
      "permanent": true,
      "domainHostname": null
    }
  ]
}

GET/api/links/{id}

Get details of a specific link, including the click counter.

curl example

curl -s https://clicaven.com/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9 \
  -H "Authorization: Bearer ca_votre_cle_api" | jq .

Response (200 OK)

{
  "@context": "/api/contexts/Link",
  "@id": "/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "@type": "Link",
  "id": "01a08b81-78ad-7720-a4c8-3133c7752bb9",
  "url": "https://example.com/page-longue",
  "short": "aB3xYz",
  "shortUrl": "https://clicaven.com/aB3xYz",
  "title": "Promo Noël LinkedIn",
  "clickCount": 14,
  "createdAt": "2026-04-18T12:00:00+00:00",
  "permanent": true,
  "domainHostname": null
}

DELETE/api/links/{id}

Permanently delete a link. The redirect will be immediately inactive. This action is irreversible.

curl example

curl -s -X DELETE https://clicaven.com/api/links/01a08b81-78ad-7720-a4c8-3133c7752bb9 \
  -H "Authorization: Bearer ca_votre_cle_api"
# → 204 No Content (success, no body)

6. Error codes

Error format

{
  "error": "authentication_failed",
  "message": "Invalid or expired API key."
}

PHP & JavaScript Examples

No SDK needed: the API is a simple JSON REST API. Here are copy-paste examples for the most common languages.

PHP

<?php
// ClicAven API — PHP example (no SDK needed)
$apiKey = 'ca_votre_cle_api';
$url    = 'https://example.com/une-url-tres-longue';

$ch = curl_init('https://clicaven.com/api/links');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['url' => $url]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $response['shortUrl'];
// => https://clicaven.com/aB3xYz

JavaScript (Node.js / fetch)

const API_KEY = 'ca_votre_cle_api';

const res = await fetch('https://clicaven.com/api/links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com/une-url-tres-longue' }),
});

const link = await res.json();
console.log(link.shortUrl);
// => https://clicaven.com/aB3xYz

Link with custom slug (Pro+)

curl -s -X POST https://clicaven.com/api/links \
  -H "Authorization: Bearer ca_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/promo","customSlug":"ma-promo"}'

{
  "id": 43,
  "short": "rT9kWm",
  "customSlug": "ma-promo",
  "shortUrl": "https://clicaven.com/ma-promo",
  "url": "https://example.com/promo",
  "clickCount": 0,
  "createdAt": "2026-04-25T14:00:00+00:00"
}

Custom slugs require a Pro plan or higher. 3 to 60 characters, letters, numbers and hyphens.