REST-API-Referenz

Authentifizierung

Die ClicAven-API verwendet API-Keys zur Authentifizierung. Jede Anfrage muss Ihren Schlüssel im Authorization-Header enthalten.

So erhalten Sie einen API-Key

1. Melden Sie sich bei Ihrem ClicAven-Konto an und öffnen Sie die Seite API-Keys
2. Geben Sie Ihrem Schlüssel einen Namen und klicken Sie auf Erstellen
3. Kopieren Sie den angezeigten Schlüssel — er wird danach nicht mehr angezeigt

Erforderliche Header

Authorization: Bearer ca_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST/api/links

Neuen Kurzlink erstellen. Erfordert einen gültigen API-Key.

Erforderliche Header

Authorization: Bearer ca_votre_cle_api
Content-Type: application/json

Anfrage-Body

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

Das Feld title ist optional (maximal 120 Zeichen). Es dient dazu, den Link im Dashboard und im CSV-Export wiederzufinden; es wird niemals öffentlich angezeigt.

Felder des Links

Das vollständige, aktuelle Schema wird als OpenAPI 3.1 veröffentlicht: /api/openapi.json und /api/openapi.yaml. Es wird aus dem Code generiert und ist damit maßgeblich.

Antwort (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-Beispiel

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

Alle Ihre Kurzlinks auflisten. Erfordert einen gültigen API-Key.

curl-Beispiel

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

Antwort (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}

Details eines bestimmten Links abrufen, einschließlich des Klickzählers.

curl-Beispiel

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

Antwort (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}

Link dauerhaft löschen. Die Weiterleitung wird sofort inaktiv. Diese Aktion ist irreversibel.

curl-Beispiel

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

6. Fehlercodes

Fehlerformat

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

PHP- & JavaScript-Beispiele

Sie benötigen kein SDK: Die API ist eine einfache JSON-REST-API. Hier sind Kopier-Einfügen-Beispiele für die gängigsten Sprachen.

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 mit benutzerdefiniertem 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"
}

Benutzerdefinierte Slugs erfordern einen Pro-Plan oder höher. 3 bis 60 Zeichen, Buchstaben, Ziffern und Bindestriche.