← Back ClipSend

📚 API Documentation

Integrate ClipSend into your applications with our REST API

Enter your API Key and all code examples will update automatically so you can copy and paste directly.

🔐 Authentication

All API requests require authentication via the header X-API-Key.

On top of the monthly quota, each plan has an hourly limit (Premium: 500 requests/hour). Every response includes the headers 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

Create a new link with content that will self-destruct after being viewed.

Parameter Type Description
content required string The secret content to share
max_uses optional integer Number of allowed views: 1, 2, 5, 10. Default: 1
slug optional string Custom slug for the URL. If not provided, a random one will be generated
expires_in optional integer Seconds until expiration: 900, 3600, 86400 or 604800. Never expires by default.
notify_on_read optional boolean true to receive an email each time the link is read.
is_code optional boolean true to treat the content as code (rendered with syntax highlighting).
code_language optional string Snippet language: 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']}"

✅ Successful Response (201)

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

Retrieves all active links and reserved slugs for the user.

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);

✅ Successful Response (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}

Retrieves the content of a link. ⚠️ This action consumes one use of the link (burn after reading).

Parámetro Tipo Descripción
slug required string The unique identifier of the link 
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

Check the status of one of your links without consuming any use.

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}`);

✅ ✅ Successful Response (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

Check your current API key usage for this month.

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
}

Outgoing webhooks

Register a URL in your dashboard (/dashboard/webhooks) and ClipSend will send you a signed JSON POST when the events you choose occur.

POST https://your-server.com/your-endpoint

Available events: link.read (the link was read) and link.expired (the link expired unread). Every delivery includes the X-ClipSend-Event and X-ClipSend-Signature headers.

📦 Payload example

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

🔐 Signature verification (PHP)

The signature is the HMAC-SHA256 of the body with your secret (shown once when the webhook is created).

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

❌ Error Codes

The API uses standard HTTP status codes to indicate the result of requests.

400 Bad Request

Invalid or missing parameters

401 Unauthorized

Invalid or missing API key

403 Forbidden

You do not have access to the API (free plan)

404 Not Found

Link does not exist

410 Gone

Link has expired or reached maximum uses

429 Too Many Requests

Monthly API limit reached