Skip to content

Piwigo Web API

Jump to bottom
Linty edited this page Jun 9, 2025 · 3 revisions

API = Application Programming Interface. This is the way other applications can communicate with Piwigo. This feature is also know as Web Services.

Examples:

  • Wordpress (web blog software) can display random photos from a Piwigo gallery in its sidebar
  • Lightroom (photo management software for desktop) can create albums and upload photos to Piwigo

This documentation is under construction: not all methods are described here. You won't have to find methods by yourself in Piwigo source code, we have a web API browser, distributed in Piwigo itself. On any Piwigo installation, go to http://yourdomain/yourpiwigo/tools/ws.htm from your web browser and discover all methods. For example web API browser on Piwigo demo.

API Key authentication

Since Piwigo 16, each user can generate one or more personal API keys from their profile. These keys allow secure, stateless access to the Piwigo web API without requiring a user session.

Generate an API key

  1. Log in to your Piwigo account.
  2. Go to your user profile and open the API Keys section.
  3. Click on New API Key.
  4. Choose a name and a validity duration (in days or a custom expiration date).
  5. Copy and save the secret key: it will never be displayed again.

Use an API key

  • To authenticate your API requests, use the Authorization HTTP header:
    Authorization: pkid-XXXXXXXX-XXXXXXXXXXXX:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

    • pkid-XXX... = public identifier of the key
    • YYYYY... = secret key
      Don't forget : between them

  • Example with curl:

curl -H "Authorization: pkid-20250609-abcdef1234567890:0123456789abcdef0123456789abcdef01234567" \
  -d "method=pwg.categories.getList" \
  -d "format=json" \
  https://your-piwigo/ws.php

Restrictions and security

  • Some sensitive methods are explicitly blocked for API key usage (see the prohibited methods by default, you can also add or remove methods in $conf['api_key_forbidden_methods']).
  • A key can be revoked or renamed at any time from the profile.
  • An expired or revoked key can no longer be used to access the API.
  • Access is tracked (date last used).
  • The secret key is displayed only once on creation.

Test your keys:

Use the built-in tool https://your-piwigo/tools/ws.htm
An Authorization field lets you test your requests with an API key.

Best practices:

  • Use a different key for each application or script.
  • Revoke unused keys.
  • Never share the secret key.
Clone this wiki locally