API Documentation

Introduction

The PakSurf API is a RESTful API that allows you to programmatically manage your backlinks, trigger verifications, access analytics, and integrate PakSurf into your existing workflows.

RESTful Design

Standard HTTP methods and JSON responses

Secure

API key authentication with HTTPS

Fast

Optimized for performance with rate limiting

Base URL

https://paksurf.com/api/v1

All API requests should be made to this base URL over HTTPS.

✅ API is Live!

The PakSurf API is now fully operational for Business plan subscribers. Generate your API key →

API Key Format

All API keys start with psk_ prefix (e.g., psk_abc123def456...). You can have up to 5 active API keys per account.

Authentication

All API requests require authentication using an API key. You can provide your API key in three ways:

Method 1: HTTP Header (Recommended)

X-API-Key: psk_your_api_key_here

Method 2: Alternative Header

X-APIKEY: psk_your_api_key_here

Method 3: Query Parameter (Fallback)

curl "https://paksurf.com/api/v1/backlinks?api_key=psk_your_api_key_here"

Complete Example Request

curl -X GET "https://paksurf.com/api/v1/backlinks" \
  -H "X-API-Key: psk_your_api_key_here" \
  -H "Content-Type: application/json"

🔑 Getting Your API Key

Log in to your PakSurf account
Go to Account Settings
Navigate to the API Keys tab
Click "Generate New API Key"
Give your key a name (e.g., "Production", "Testing")
Copy and securely store your API key

⚠️ Important: Your API key is shown only once. Save it immediately in a secure location.

🔒 Security Best Practices

Never commit API keys to version control (Git, SVN)
Use environment variables in production
Rotate keys regularly (every 90 days recommended)
Revoke compromised keys immediately
Use separate keys for development and production

Rate Limits

To ensure fair usage and system stability, API requests are rate-limited based on your subscription plan.

Plan	Requests/Minute	Requests/Day	Burst Limit
Free	Not available	Not available	Not available
Pro	Not available	Not available	Not available
Business ⭐	60	10,000	10

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1719676800 // Unix timestamp

⚠️ Rate Limit Exceeded: If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait until the X-RateLimit-Reset timestamp before making more requests.

💡 Tip: Implement exponential backoff in your application. If you receive a 429 error, wait 1 second, then 2 seconds, then 4 seconds, etc.

Error Handling

The API uses standard HTTP status codes to indicate success or failure. All error responses follow a consistent JSON format.

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid or expired."
  }
}

HTTP Status Codes

200

OK

Request succeeded

201

Created

Resource created successfully (e.g., new backlink or API key)

400

Bad Request

Invalid request parameters or missing required fields

401

Unauthorized

Invalid or missing API key

403

Forbidden

API key doesn't have permission (requires Business plan or subscription inactive)

404

Not Found

Resource doesn't exist or doesn't belong to you

405

Method Not Allowed

HTTP method not supported for this endpoint

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Complete Error Codes Reference

Error Code	HTTP Status	Description	Solution
MISSING_API_KEY	401	No API key provided	Add X-API-Key header
INVALID_API_KEY	401	API key is invalid or revoked	Generate a new API key
ACCOUNT_BANNED	403	Your account has been suspended	Contact support
PLAN_REQUIRED	403	Business plan required	Upgrade to Business plan
SUBSCRIPTION_INACTIVE	403	Business subscription expired	Renew subscription
RATE_LIMIT_EXCEEDED	429	Too many requests	Wait and retry
MISSING_FIELDS	400	Required fields missing	Provide all required fields
INVALID_URL	400	Invalid website URL	Provide valid URL with protocol
INVALID_ID	400	Invalid resource ID	Provide valid numeric ID
BACKLINK_NOT_FOUND	404	Backlink not found	Check ID or create backlink
BACKLINK_LIMIT	403	Backlink limit reached	Upgrade plan or delete backlinks
KEY_LIMIT	403	Maximum 5 API keys reached	Revoke unused keys
KEY_NOT_FOUND	404	API key not found	Check key ID
CANNOT_REVOKE_CURRENT	400	Cannot revoke active key	Use different key for request
METHOD_NOT_ALLOWED	405	HTTP method not supported	Use correct HTTP method
SERVER_ERROR	500	Internal server error	Retry or contact support

API Endpoints

Backlinks

GET /api/v1/backlinks

Retrieve a list of all your backlinks with pagination support.

Query Parameters

Parameter	Type	Default	Description
status	string	all	Filter by status: active, inactive, pending, all
page	integer	1	Page number for pagination
per_page	integer	20	Items per page (max: 100)

Example Request

curl "https://paksurf.com/api/v1/backlinks?status=active&page=1" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "backlinks": [
      {
        "id": 1,
        "website_url": "https://example.com",
        "anchor_text": "Example",
        "status": "active",
        "embed_type": "link",
        "total_clicks": 42,
        "last_verified_at": "2026-06-29 10:00:00",
        "last_failed_at": null,
        "created_at": "2026-06-28 17:31:15"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "per_page": 20,
      "total_pages": 3
    }
  }
}

POST /api/v1/backlinks

Create a new backlink. Returns the verification code to embed on your site.

Request Body (JSON)

Field	Type	Required	Description
website_url	string	Yes	Full URL including protocol (https://)
anchor_text	string	Yes	Anchor text for the backlink
embed_type	string	No	link, meta, or comment (default: link)

Example Request

curl -X POST "https://paksurf.com/api/v1/backlinks" \
  -H "X-API-Key: psk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "website_url": "https://example.com",
    "anchor_text": "My Website",
    "embed_type": "link"
  }'

Example Response (201)

{
  "success": true,
  "data": {
    "id": 51,
    "website_url": "https://example.com",
    "anchor_text": "My Website",
    "verification_token": "abc123def456...",
    "status": "pending",
    "embed_type": "link",
    "embed_code": "<a href='https://paksurf.com' data-paksurf-id='abc123...'>PakSurf</a>",
    "message": "Backlink created successfully. Embed the code on your site and verify."
  }
}

GET /api/v1/backlinks/{id}

Retrieve details of a specific backlink by ID.

Example Request

curl "https://paksurf.com/api/v1/backlinks/51" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "id": 51,
    "website_url": "https://example.com",
    "anchor_text": "My Website",
    "verification_token": "abc123...",
    "status": "active",
    "embed_type": "link",
    "total_clicks": 42,
    "last_verified_at": "2026-06-29 10:00:00",
    "last_failed_at": null,
    "created_at": "2026-06-28 17:31:15",
    "embed_code": "<a href=...>PakSurf</a>"
  }
}

DELETE /api/v1/backlinks/{id}

Delete a backlink permanently. This action cannot be undone.

Example Request

curl -X DELETE "https://paksurf.com/api/v1/backlinks/51" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "message": "Backlink deleted successfully.",
    "id": 51
  }
}

Verification

POST /api/v1/backlinks/{id}/verify

Trigger immediate verification for a specific backlink.

Example Request

curl -X POST "https://paksurf.com/api/v1/backlinks/51/verify" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "id": 51,
    "website_url": "https://example.com",
    "status": "active",
    "verified": true,
    "last_verified_at": "2026-06-29 12:00:00",
    "last_failed_at": null,
    "message": "✅ Verification successful! Your backlink is now active."
  }
}

Statistics

GET /api/v1/stats

Get comprehensive statistics about your backlinks and clicks.

Example Request

curl "https://paksurf.com/api/v1/stats" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "total_backlinks": 50,
    "active_backlinks": 45,
    "inactive_backlinks": 3,
    "pending_backlinks": 2,
    "total_clicks": 1250,
    "clicks_today": 42,
    "clicks_this_week": 285,
    "clicks_this_month": 1100,
    "top_backlinks": [
      {
        "id": 1,
        "website_url": "https://example.com",
        "anchor_text": "Example",
        "total_clicks": 150,
        "status": "active"
      }
    ]
  }
}

Account

GET /api/v1/account

Get your account information and current subscription details.

Example Request

curl "https://paksurf.com/api/v1/account" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "plan": {
      "name": "Business",
      "slug": "business",
      "max_backlinks": 999999,
      "verification_frequency": 5
    },
    "subscription": {
      "status": "active",
      "billing_cycle": "monthly",
      "current_period_start": "2026-06-29 16:17:24",
      "current_period_end": "2026-07-29 16:17:24"
    },
    "backlinks_used": 50,
    "backlinks_limit": 999999,
    "api_keys_count": 2,
    "email_notifications": true,
    "email_frequency": "weekly",
    "created_at": "2026-06-28 17:31:15"
  }
}

API Keys

GET /api/v1/api-keys

List all your API keys with usage statistics.

Example Request

curl "https://paksurf.com/api/v1/api-keys" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "api_keys": [
      {
        "id": 1,
        "name": "Production",
        "key_prefix": "psk_abc123",
        "is_active": true,
        "last_used_at": "2026-06-29 18:00:00",
        "last_used_ip": "192.168.1.1",
        "total_requests": 1250,
        "created_at": "2026-06-28 17:31:15"
      }
    ]
  }
}

POST /api/v1/api-keys

Generate a new API key. The full key is shown only once!

Request Body (JSON)

Field	Type	Required	Description
name	string	No	Friendly name for the key (default: "API Key")

Example Request

curl -X POST "https://paksurf.com/api/v1/api-keys" \
  -H "X-API-Key: psk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

Example Response (201)

{
  "success": true,
  "data": {
    "id": 2,
    "name": "Production",
    "api_key": "psk_abc123def456...",
    "key_prefix": "psk_abc123",
    "message": "⚠️ Save this API key now. It will not be shown again."
  }
}

DELETE /api/v1/api-keys/{id}

Revoke an API key. This action cannot be undone.

Example Request

curl -X DELETE "https://paksurf.com/api/v1/api-keys/2" \
  -H "X-API-Key: psk_your_key"

Example Response (200)

{
  "success": true,
  "data": {
    "message": "API key revoked successfully.",
    "id": 2
  }
}

Code Examples

Complete examples in multiple programming languages to help you get started quickly.

PHP Example (using cURL)

$api_key = 'psk_your_api_key_here';
$base_url = 'https://paksurf.com/api/v1';

// Initialize cURL
$ch = curl_init();

// List all backlinks
curl_setopt_array($ch, [
    CURLOPT_URL => $base_url . '/backlinks',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $api_key,
        'Content-Type: application/json',
    ],
]);

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

if ($data['success']) {
    foreach ($data['data']['backlinks'] as $backlink) {
        echo $backlink['website_url'] . " - " . $backlink['status'] . "\n";
    }
}

curl_close($ch);

SDKs & Libraries

Official and community-maintained SDKs to simplify integration:

🐘

PHP SDK

Official • v1.0.0

Full-featured PHP client with type hints and autocompletion.

composer require paksurf/sdk

📦

Node.js SDK

Official • v1.0.0

TypeScript-ready Node.js client with Promise support.

npm install @paksurf/sdk

🐍

Python SDK

Community • v0.9.0

Pythonic client with async support and type hints.

pip install paksurf

💎

Ruby SDK

Community • v0.8.0

Ruby client with Rails integration support.

gem install paksurf

💡 Want to contribute? We welcome community SDKs in other languages. Contact us to get featured here.

Support

Need Help?

Our support team is here to help you integrate the PakSurf API into your applications.

Contact Support View FAQ

PakSurf API Documentation

Introduction

RESTful Design

Secure

Fast

Authentication

Method 1: HTTP Header (Recommended)

Method 2: Alternative Header

Method 3: Query Parameter (Fallback)

Complete Example Request

🔑 Getting Your API Key

🔒 Security Best Practices

Rate Limits

Rate Limit Headers

Error Handling

Error Response Format

HTTP Status Codes

Complete Error Codes Reference

API Endpoints

Backlinks

Query Parameters

Example Request

Example Response (200)

Request Body (JSON)

Example Request

Example Response (201)

Example Request

Example Response (200)

Example Request

Example Response (200)

Verification

Example Request

Example Response (200)

Statistics

Example Request

Example Response (200)

Account

Example Request

Example Response (200)

API Keys

Example Request

Example Response (200)

Request Body (JSON)

Example Request

Example Response (201)

Example Request

Example Response (200)

Code Examples

PHP Example (using cURL)

JavaScript Example (using Fetch API)

Python Example (using requests)

cURL Examples

SDKs & Libraries

PHP SDK

Node.js SDK

Python SDK

Ruby SDK

Support

Need Help?