📚 API Documentation

Integra ClipSend en tus aplicaciones con nuestra REST API

🔑 Tu API Key

Introduce tu API Key y todos los ejemplos de código se actualizarán automáticamente para que puedas copiar y pegar directamente.

🔐 Autenticación

Todas las peticiones a la API requieren autenticación mediante el header X-API-Key.

Además del límite mensual, cada plan tiene un límite por hora (Premium: 500 peticiones/hora). Cada respuesta incluye las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

curl -H "X-API-Key: YOUR_API_KEY" \
     https://www.clipsend.net/api/usage

import requests

headers = {
    "X-API-Key": "YOUR_API_KEY"
}

response = requests.get(
    "https://www.clipsend.net/api/usage",
    headers=headers
)
print(response.json())

const response = await fetch("https://www.clipsend.net/api/usage", {
    headers: {
        "X-API-Key": "YOUR_API_KEY"
    }
});

const data = await response.json();
console.log(data);

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://www.clipsend.net/api/usage",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: YOUR_API_KEY"
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://www.clipsend.net/api/usage", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

require 'net/http'
require 'json'

uri = URI("https://www.clipsend.net/api/usage")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
end

puts JSON.parse(response.body)

📝 Endpoints

POST /api/links

Crea un nuevo enlace con contenido que se autodestruirá después de ser visualizado.

Parámetro	Tipo	Descripción
content requerido	string	El contenido secreto a compartir
max_uses opcional	integer	Número de visualizaciones permitidas: 1, 2, 5, 10. Por defecto: 1
slug opcional	string	Slug personalizado para la URL. Si no se proporciona, se genera uno aleatorio
expires_in opcional	integer	Segundos hasta que caduque: 900, 3600, 86400 o 604800. Por defecto no caduca.
notify_on_read opcional	boolean	true para recibir un email cada vez que se lea el enlace.
is_code opcional	boolean	true para tratar el contenido como código (se muestra con resaltado de sintaxis).
code_language opcional	string	Lenguaje del snippet: javascript, python, php, sql, json...

curl -X POST https://www.clipsend.net/api/links \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"content": "Mi mensaje secreto", "max_uses": 1, "slug": "mi-slug"}'

import requests

response = requests.post(
    "https://www.clipsend.net/api/links",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "content": "Mi mensaje secreto",
        "max_uses": 1,
        "slug": "mi-slug"  # opcional
    }
)

data = response.json()
print(f"Link creado: {data['link']}")

const response = await fetch("https://www.clipsend.net/api/links", {
    method: "POST",
    headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        content: "Mi mensaje secreto",
        max_uses: 1,
        slug: "mi-slug"  // opcional
    })
});

const data = await response.json();
console.log(`Link creado: ${data.link}`);

<?php
$ch = curl_init();

$payload = json_encode([
    "content" => "Mi mensaje secreto",
    "max_uses" => 1,
    "slug" => "mi-slug"  // opcional
]);

curl_setopt_array($ch, [
    CURLOPT_URL => "https://www.clipsend.net/api/links",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: YOUR_API_KEY",
        "Content-Type: application/json"
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
echo "Link creado: " . $data['link'];

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "content":  "Mi mensaje secreto",
        "max_uses": 1,
        "slug":     "mi-slug",
    })

    req, _ := http.NewRequest("POST", "https://www.clipsend.net/api/links", 
        bytes.NewBuffer(payload))
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

require 'net/http'
require 'json'

uri = URI("https://www.clipsend.net/api/links")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = "YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
    content: "Mi mensaje secreto",
    max_uses: 1,
    slug: "mi-slug"
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
end

data = JSON.parse(response.body)
puts "Link creado: #{data['link']}"

✅ Respuesta exitosa (201)

{
    "success": true,
    "link": "https://www.clipsend.net/mi-slug",
    "slug": "mi-slug",
    "max_uses": 1
}

GET /api/links

Obtiene todos los links activos y slugs reservados del usuario.

curl "https://www.clipsend.net/api/links" \
     -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://www.clipsend.net/api/links",
    headers={"X-API-Key": "YOUR_API_KEY"}
)

print(response.json())

const response = await fetch("https://www.clipsend.net/api/links", {
    headers: {
        "X-API-Key": "YOUR_API_KEY"
    }
});

const data = await response.json();
console.log(data);

✅ Respuesta exitosa (200)

{
    "success": true,
    "links": {
        "mi-slug": {
            "type": "link",
            "slug": "mi-slug",
            "content": "Mi mensaje secreto",
            "current_uses": 0,
            "remaining_uses": 1,
            "created_at": "2025-12-13 14:59:43",
            "max_uses": 1,
            "url": "https://www.clipsend.net/mi-slug"
        },
        "mi-marca": {
            "type": "reserved",
            "slug": "mi-marca",
            "url": "https://www.clipsend.net/mi-marca",
            "is_paid": true,
            "created_at": "2025-12-10 09:30:00"
        }
    }
}

GET /api/links?slug={slug}

Obtiene el contenido de un enlace. ⚠️ Esta acción consume un uso del enlace (burn after reading).

Parámetro	Tipo	Descripción
slug requerido	string	El identificador único del enlace

curl "https://www.clipsend.net/api/links?slug=mi-slug" \
     -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://www.clipsend.net/api/links",
    params={"slug": "mi-slug"},
    headers={"X-API-Key": "YOUR_API_KEY"}
)

data = response.json()
print(f"Contenido: {data['content']}")

const response = await fetch(
    "https://www.clipsend.net/api/links?slug=mi-slug",
    {
        headers: {
            "X-API-Key": "YOUR_API_KEY"
        }
    }
);

const data = await response.json();
console.log(`Contenido: ${data.content}`);

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://www.clipsend.net/api/links?slug=mi-slug",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: YOUR_API_KEY"
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
echo "Contenido: " . $data['content'];

✅ Respuesta exitosa (200)

{
    "success": true,
    "content": "Mi mensaje secreto",
    "remaining_uses": 0,
    "slug": "mi-slug"
}

GET /api/links/{slug}/status

Consulta el estado de uno de tus enlaces sin consumir ningún uso.

curl "https://www.clipsend.net/api/links/mi-slug/status" \
     -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://www.clipsend.net/api/links/mi-slug/status",
    headers={"X-API-Key": "YOUR_API_KEY"}
)

data = response.json()
print(f"Vivo: {data['alive']}, usos restantes: {data['remaining_uses']}")

const response = await fetch(
    "https://www.clipsend.net/api/links/mi-slug/status",
    {
        headers: {
            "X-API-Key": "YOUR_API_KEY"
        }
    }
);

const data = await response.json();
console.log(`Vivo: ${data.alive}, usos restantes: ${data.remaining_uses}`);

✅ ✅ Respuesta exitosa (200)

{
    "success": true,
    "slug": "mi-slug",
    "alive": true,
    "remaining_uses": 1,
    "max_uses": 1,
    "expires_at": "2026-07-06 12:00:00",
    "is_code": false,
    "created_at": "2026-07-05 12:00:00"
}

GET /api/usage

Consulta el uso actual de tu API key este mes.

curl https://www.clipsend.net/api/usage \
     -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://www.clipsend.net/api/usage",
    headers={"X-API-Key": "YOUR_API_KEY"}
)

data = response.json()
print(f"Llamadas este mes: {data['calls_this_month']}/{data['limit']}")

const response = await fetch("https://www.clipsend.net/api/usage", {
    headers: {
        "X-API-Key": "YOUR_API_KEY"
    }
});

const data = await response.json();
console.log(`Llamadas este mes: ${data.calls_this_month}/${data.limit}`);

✅ Respuesta exitosa (200)

{
    "success": true,
    "calls_this_month": 42,
    "limit": 1000,
    "remaining": 958
}

Webhooks salientes

Registra una URL en tu panel (/dashboard/webhooks) y ClipSend te enviará un POST JSON firmado cuando ocurran los eventos que elijas.

POST https://tu-servidor.com/tu-endpoint

Eventos disponibles: link.read (el enlace se ha leído) y link.expired (el enlace ha caducado sin leerse). Cada entrega incluye las cabeceras X-ClipSend-Event y X-ClipSend-Signature.

📦 Ejemplo de payload

{
    "event": "link.read",
    "data": {
        "slug": "abc123",
        "url": "https://www.clipsend.net/abc123",
        "remaining_uses": 0
    },
    "sent_at": "2026-07-05T12:00:00+00:00"
}

🔐 Verificación de la firma (PHP)

La firma es el HMAC-SHA256 del cuerpo con tu secreto (se muestra una sola vez al crear el webhook).

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_CLIPSEND_SIGNATURE'] ?? '');

❌ Códigos de Error

La API utiliza códigos de estado HTTP estándar para indicar el resultado de las peticiones.

400 Bad Request

Parámetros inválidos o faltantes

401 Unauthorized

API key inválida o no proporcionada

403 Forbidden

No tienes acceso a la API (plan free)

404 Not Found

El enlace no existe

410 Gone

El enlace ha expirado o llegó al límite de usos

429 Too Many Requests

Límite mensual de API alcanzado