API v1 Documentation

Build powerful integrations with PikSend

Introduction

The PikSend API v1 allows Pro users to programmatically manage their galleries and receive real-time notifications via webhooks. Build custom integrations, automate workflows, and extend PikSend's functionality to fit your needs.

RESTful API

Simple HTTP endpoints with JSON responses

Real-time Webhooks

Get notified instantly when events occur

Pro Feature

Available for Pro plan subscribers

Base URL

https://piksend.com/api/v1

Authentication

All API requests (except /health) require authentication using an API key.

Getting Your API Key

1.Upgrade to Pro plan
2.Go to Settings → API Keys
3.Create a new API key
4.Copy the key (shown only once)

Using Your API Key

Include your API key in the Authorization header:

Authorization: Bearer pk_live_<your_api_key>

Security Best Practices

✅ Store API keys securely (environment variables, secrets manager)
✅ Never commit API keys to version control
✅ Rotate keys regularly
❌ Never expose API keys in client-side code

Galleries

Manage your galleries programmatically with these endpoints.

GET/api/v1/galleries

List all your galleries with pagination and filters

Query Parameters

pagePage number (default: 1)

per_pageItems per page (default: 20, max: 100)

statusFilter by status: active, archived

searchSearch by gallery name

Example Request

curl -H "Authorization: Bearer pk_live_..." \
  "https://piksend.com/api/v1/galleries?page=1&per_page=20"

GET/api/v1/galleries/:id

Get detailed information about a specific gallery

Example Request

curl -H "Authorization: Bearer pk_live_..." \
  https://piksend.com/api/v1/galleries/550e8400-e29b-41d4-a716-446655440000

📖 Full API Reference: See the complete API v1 Reference Documentation for all endpoints, parameters, and response formats.

Webhooks

Receive real-time notifications when events occur in your galleries.

Available Events

gallery.created

New gallery created

gallery.viewed

Client viewed gallery

gallery.downloaded

Client downloaded photos

gallery.validated

Client validated selection

gallery.expired

Gallery expired

gallery.deleted

Gallery deleted

POST/api/v1/webhooks

Create a webhook subscription

Example Request

curl -X POST \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks","events":["gallery.created"]}' \
  https://piksend.com/api/v1/webhooks

Webhook Security

All webhooks include an HMAC-SHA256 signature in the X-PikSend-Signature header. Verify this signature to ensure the webhook came from PikSend.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

HTTP Status Codes

200

Request successful

400

Bad Request

Invalid request parameters

401

Unauthorized

Missing or invalid API key

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid gallery ID format",
    "details": {
      "field": "id",
      "issue": "Must be a valid UUID"
    }
  }
}

Code Examples

Code examples in popular programming languages.

Node.js (with axios)

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://piksend.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.PIKSEND_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// List galleries
const galleries = await client.get('/galleries', {
  params: { page: 1, per_page: 20, status: 'active' }
});

console.log(`Found ${galleries.data.pagination.total} galleries`);

Python (with requests)

import requests
import os

class PikSendClient:
    def __init__(self, api_key):
        self.base_url = 'https://piksend.com/api/v1'
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def list_galleries(self, page=1, per_page=20):
        response = self.session.get(
            f'{self.base_url}/galleries',
            params={'page': page, 'per_page': per_page}
        )
        response.raise_for_status()
        return response.json()

client = PikSendClient(os.environ['PIKSEND_API_KEY'])
galleries = client.list_galleries()
print(f"Found {galleries['pagination']['total']} galleries")

cURL

# List galleries
curl -H "Authorization: Bearer pk_live_..." \
  "https://piksend.com/api/v1/galleries?page=1&per_page=20"

# Create webhook
curl -X POST \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks","events":["gallery.created"]}' \
  https://piksend.com/api/v1/webhooks

Help Center Contact Support