v1.3.0 Active

Developer API & Website Integration

Integrate PicPulse into your website or application to list pictures, display albums, query custom slugs, and automate uploads.

Website Integration (SDK) Authentication List Pictures API Albums & Collections Upload & Base64 Update Slug Analytics Code Snippets
Client SDK & Embed Kit

Website Integration — Show Pictures & Albums in Any Website

Developer leh website neitute'n PicPulse an website-ah awlsam takin an integrate thei a. Script 1 dah luh ringawtin picture zawng zawng, user gallery, emaw album collection te list leh grid mawi takin a rawn in-render nghal vek thei a ni.

Step 1: Include the PicPulse SDK in your HTML

<!-- Paste this before </body> in your website --> <script src="https://picpulse.lushai.dev/cdn/sdk.js" async></script>

Step 2: Drop-in Declarative Containers (Zero Code Required)

A. Render Complete Picture List / Gallery on Your Site:
<!-- Automatically fetches and renders your images in a responsive grid with zoom lightbox --> <div data-picpulse-gallery="all" data-limit="24" data-sort="newest"></div> <!-- Filter by specific user or category --> <div data-picpulse-gallery="all" data-user="username" data-category="photography"></div>
B. Render Pictures From a Specific Album:
<!-- Display all pictures inside an album --> <div data-picpulse-album="YOUR_ALBUM_TOKEN"></div>
C. Render User Albums List:
<!-- Display album cards with picture counts and cover thumbnails --> <div data-picpulse-albums="all" data-user="username"></div>

Step 3: Programmatic JavaScript API (For Custom Web & Mobile Apps)

Developers can also call the JavaScript methods directly in React, Vue, Svelte, or vanilla JS:

// 1. Fetch picture list programmatically
PicPulse.listImages({ limit: 12, sort: 'popular' }).then(response => {
    console.log("Found pictures:", response.data);
    response.data.forEach(img => {
        console.log("Title/Slug:", img.slug, "CDN URL:", img.urls.direct_url);
    });
});

// 2. Fetch all albums
PicPulse.listAlbums().then(response => {
    console.log("Albums list:", response.data);
});

// 3. Render a picture gallery into any target element
PicPulse.renderGallery('#my-custom-container', {
    album: 'YOUR_ALBUM_TOKEN',
    limit: 20
});

Authentication & Headers

Every authenticated write or private request must provide a valid API Key in the headers. You can generate or revoke keys in your Account Settings.

Header Option 1 (Recommended): X-API-Key: your_api_key_here
Header Option 2 (Bearer Token): Authorization: Bearer your_api_key_here
Base URL: https://picpulse.lushai.dev/api/v1 — All endpoints return standard application/json with proper HTTP status codes.

Platform & Health Endpoints

GET /ping

Public health check verifying API responsiveness and server availability.

curl -X GET "https://picpulse.lushai.dev/api/v1/ping"

GET /stats

Returns public platform-wide statistics (total images, total views, bandwidth hosted, max limits).

curl -X GET "https://picpulse.lushai.dev/api/v1/stats"

GET /categories

Returns active image categories sorted by popularity.

GET /tags

Returns top image tags across public community uploads.

List Pictures & Image API

GET /images

List pictures with full pagination, keyword search, tag filtering, album filtering, category matching, and sorting.

Query Parameters

Parameter Type Default Description
page Integer 1 Page index for pagination
limit Integer 24 Results per page (1 – 100)
q String Search query matching slug name, title, description, or tags
album String Filter pictures by album token or album ID
user String Filter pictures by username, or pass user=me to view your own uploads
category String Filter by category (e.g. nature, wallpaper)
tag String Filter by tag keyword
sort String newest Sorting: newest, oldest, popular, size

Example Request & Response

curl -X GET "https://picpulse.lushai.dev/api/v1/images?limit=2&sort=newest"
{
  "status": "success",
  "pagination": {
    "total": 240,
    "page": 1,
    "limit": 2,
    "total_pages": 120,
    "has_next": true,
    "has_previous": false
  },
  "data": [
    {
      "id": 105,
      "slug": "scenic-lake-dock",
      "title": "scenic-lake-dock",
      "file_size": 1542030,
      "file_size_formatted": "1.47 MB",
      "format": "JPG",
      "dimensions": { "width": 1920, "height": 1080 },
      "views": 42,
      "is_public": true,
      "category": "nature",
      "tags": ["lake", "sunset", "peaceful"],
      "created_at": "2025-05-12 14:20:00",
      "urls": {
        "view_page": "https://picpulse.lushai.dev/i/scenic-lake-dock",
        "direct_url": "https://picpulse.lushai.dev/raw/...",
        "thumbnail_url": "https://picpulse.lushai.dev/thumb/...",
        "cdn_embed": "https://picpulse.lushai.dev/cdn.php?id=scenic-lake-dock"
      },
      "embed_codes": {
        "html": "<img src=\"https://picpulse.lushai.dev/raw/...\" alt=\"scenic-lake-dock\" />",
        "markdown": "![scenic-lake-dock](https://picpulse.lushai.dev/raw/...)"
      }
    }
  ]
}

GET /images/{slug_or_id}

Fetch details and direct CDN links for a specific picture by custom slug or ID. Automatically increments view metrics.

curl -X GET "https://picpulse.lushai.dev/api/v1/images/scenic-lake-dock"

Upload Images (Dual Pipeline: Binary Multipart & Base64 JSON)

Upload files programmatically using standard multipart/form-data or pure JSON with image_base64 payload. Strictly requires authentication.

POST /images

Parameters

Field Type Required Description
image Binary File Yes (for multipart) JPG, PNG, GIF, WebP, BMP, or SVG (Up to 50MB)
image_base64 String Yes (for JSON) Base64 encoded image string (data URI or raw base64)
slug String Optional Custom URL slug (e.g. epic-landscape-2025). Auto-generated if omitted.
title String Optional Public display title. Defaults to custom slug.
description String Optional Image description or caption text
category String Optional Category name (e.g. photography)
tags String Optional Comma-separated tags (e.g. mountains,sunset,hiking)
is_public Integer Optional 1 for Public (default), 0 for Unlisted / Private
album String Optional Album token or ID to associate the upload with

Multipart File Example

curl -X POST "https://picpulse.lushai.dev/api/v1/images" \ -H "X-API-Key: YOUR_API_KEY" \ -F "image=@/path/to/photo.jpg" \ -F "slug=epic-sunset" \ -F "category=nature" \ -F "tags=sunset,mountains"

JSON Base64 Example

curl -X POST "https://picpulse.lushai.dev/api/v1/images" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "filename": "sample_pixel.png", "slug": "sample-pixel", "tags": "test,pixel" }'

Update Image Metadata & Custom Slug

PUT PATCH /images/{slug_or_id}

Update title, custom URL slug, description, tags, category, or visibility. Image owners and administrators only.

JSON Request Body

curl -X PUT "https://picpulse.lushai.dev/api/v1/images/old-sunset-slug" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "slug": "new-awesome-sunset-slug", "title": "Breathtaking Golden Hour", "tags": "goldenhour,mountains,scenic", "category": "landscape", "is_public": 1 }'

DELETE /images/{slug_or_id}

Permanently delete an image and clean up cached thumbnails. Authorized for owners, administrators, or requests supplying delete_token.

curl -X DELETE "https://picpulse.lushai.dev/api/v1/images/new-awesome-sunset-slug" \ -H "X-API-Key: YOUR_API_KEY"

Album Management & Picture Collections

GET /albums

List public albums, or pass user=me to list all albums belonging to your account.

curl -X GET "https://picpulse.lushai.dev/api/v1/albums?user=me" -H "X-API-Key: YOUR_API_KEY"

GET /albums/{token_or_id}/images

Get a paginated list of all pictures inside a specific album (includes thumbnails, direct links, and slug names).

curl -X GET "https://picpulse.lushai.dev/api/v1/albums/YOUR_ALBUM_TOKEN/images?limit=50"

POST /albums

Create a new album collection.

curl -X POST "https://picpulse.lushai.dev/api/v1/albums" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Summer Holidays 2025", "description": "Family beach and mountain memories", "is_public": 1 }'

POST DELETE /albums/{token_or_id}/images

Add (POST) or remove (DELETE) an image from an album.

curl -X POST "https://picpulse.lushai.dev/api/v1/albums/ALBUM_TOKEN/images" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image": "my-beach-slug"}'

Analytics & User Profile

GET /images/{slug_or_id}/analytics

Get 30-day time-series view trends and top referring websites for any image owned by your account.

curl -X GET "https://picpulse.lushai.dev/api/v1/images/golden-mountain-sunset/analytics" -H "X-API-Key: YOUR_API_KEY"

GET /user

Retrieve authenticated user profile, total hosted disk bytes, total views, upload counts, and API key metadata.

curl -X GET "https://picpulse.lushai.dev/api/v1/user" -H "X-API-Key: YOUR_API_KEY"

Integration Code Snippets — Fetch Pictures & Albums

// Fetch all pictures for a user or website integration
async function getPictures() {
    const res = await fetch('https://picpulse.lushai.dev/api/v1/images?limit=20&sort=newest', {
        headers: { 'Accept': 'application/json' }
    });
    const json = await res.json();
    
    // Iterate and display pictures in your custom UI
    json.data.forEach(picture => {
        console.log("Picture Name:", picture.slug);
        console.log("Thumbnail:", picture.urls.thumbnail_url);
        console.log("Full Image:", picture.urls.direct_url);
    });
}

// Fetch all albums
async function getAlbums() {
    const res = await fetch('https://picpulse.lushai.dev/api/v1/albums');
    const json = await res.json();
    console.log("Albums list:", json.data);
}

getPictures();