⚡

Punked.co API

Build prank-powered apps with our REST API

Create prank links, list effects, get analytics, and rate effects — all programmatically. Free to use with generous rate limits.

Base URL: https://punked.co/api/v1 v1 JSON

🚀 Quick Start

Create your first prank link in one request:

curl -X POST https://punked.co/api/v1/traps \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "effect": "earthquake"}'

Response:

{
  "id": 42,
  "slug": "a1b2c3d4",
  "url": "https://punked.co/u/a1b2c3d4",
  "destination_url": "https://example.com",
  "effect": "earthquake",
  "created_at": "2025-01-15T10:30:00+00:00"
}

🔑 Authentication

The API works without authentication for read endpoints and prank creation (when the site doesn't require login).

If login is required on the site, pass your API key in the X-API-Key header:

curl -H "X-API-Key: your_api_key_here" https://punked.co/api/v1/effects

⏱️ Rate Limits

60
Requests / Minute
IP
Based Limiting
429
When Exceeded

📡 Endpoints

GET /api/v1/effects

List all available prank effects with stats and ratings.

Example Request:

curl https://punked.co/api/v1/effects

Response:

{
  "effects": [
    {
      "id": "ghost_cursor",
      "name": "Ghost Cursor",
      "icon": "👻",
      "category": "Classic Effects",
      "traps_created": 142,
      "total_hits": 1893,
      "avg_rating": 4.2,
      "rating_count": 37,
      "preview_url": "https://punked.co/effect-preview?effect=ghost_cursor",
      "page_url": "https://punked.co/pranks/ghost-cursor"
    },
    ...
  ],
  "total": 35
}
GET /api/v1/effects/{effect_id}

Get detailed information about a specific effect, including recent traps.

Parameters:

effect_id string, path required — e.g. earthquake, ghost_cursor

Example:

curl https://punked.co/api/v1/effects/earthquake
POST /api/v1/traps

Create a new prank link. Returns the shareable URL.

Request Body (JSON):

Field Type Required Description
url string yes Destination URL to prank
effect string yes Effect ID (use /effects to list)

Example:

curl -X POST https://punked.co/api/v1/traps \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "effect": "screen_crack"}'
GET /api/v1/traps/{slug}

Get details and hit count for a specific trap link.

Example:

curl https://punked.co/api/v1/traps/a1b2c3d4
POST /api/v1/ratings

Rate a prank effect (1-5 stars). One rating per IP per effect.

Request Body (JSON):

Field Type Required Description
effect string yes Effect ID
rating integer yes 1 to 5

Example:

curl -X POST https://punked.co/api/v1/ratings \
  -H "Content-Type: application/json" \
  -d '{"effect": "earthquake", "rating": 5}'

❌ Error Codes

400 Bad request — missing or invalid parameters
401 Unauthorized — API key required (when login is enforced)
403 Forbidden — URL is banned
404 Not found — endpoint or resource doesn't exist
429 Too many requests — rate limit exceeded (60/min)
500 Server error — something went wrong on our end

💻 Code Examples

JavaScript (fetch)

const response = await fetch('https://punked.co/api/v1/traps', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://example.com',
    effect: 'ghost_cursor'
  })
});
const data = await response.json();
console.log(data.url); // https://punked.co/u/a1b2c3d4

Python (requests)

import requests

resp = requests.post('https://punked.co/api/v1/traps', json={
    'url': 'https://example.com',
    'effect': 'screen_crack'
})
data = resp.json()
print(data['url'])  # https://punked.co/u/a1b2c3d4

PHP (cURL)

$ch = curl_init('https://punked.co/api/v1/traps');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://example.com',
        'effect' => 'earthquake'
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
echo $data['url']; // https://punked.co/u/a1b2c3d4

Questions or need higher rate limits?

Contact us →