Developer API & Website Integration
Integrate PicPulse into your website or application to list pictures, display albums, query custom slugs, and automate uploads.
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)
<!-- 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>
<!-- Display all pictures inside an album -->
<div data-picpulse-album="YOUR_ALBUM_TOKEN"></div>
<!-- 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.
X-API-Key: your_api_key_here
Authorization: Bearer your_api_key_here
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": ""
}
}
]
}
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();