Contents
On this page

Plugixa Easy Social Share Buttons REST API - Plugixa Easy Social Share Buttons

The integration surface for Plugixa Easy Social Share Buttons: share sets you can list, create, change, copy and delete, the catalogue of networks, positions and styles they can use, a post’s share counts, the click beacon, share analytics, and the site’s follow profiles. Pro adds the public route behind the “Save this post” email form. Enough to set up the same buttons on many sites from a script, feed click numbers into a dashboard, or draw counts in a headless front end.

Authentication. The plugin has no API keys of its own. A script signs in the way WordPress already allows, normally with an Application Password for an account that holds the permissions below. The two visitor routes, counts and the click beacon, and Pro’s email form need no sign-in at all.

Everything the admin app does, it does over REST under the namespace plugixa-social-share/v1. Every permission the screens enforce is enforced at the endpoint rather than in the page.

This is the API the plugin itself uses. It is not a separately versioned public API, and the plugin makes no promise that routes, parameters or response shapes stay the same between versions. Pin the plugin version you build against, and test after updating.

Base URL

https://your-site.example/wp-json/plugixa-social-share/v1

On a site with plain permalinks, pass the route as a parameter instead:

https://your-site.example/?rest_route=/plugixa-social-share/v1/sets

Authentication

Send an Application Password with HTTP Basic authentication. Create one under Users -> Profile -> Application Passwords for an account that holds the capability the endpoint needs:

curl -s "https://your-site.example/wp-json/plugixa-social-share/v1/sets" \
  -u "admin:$WP_APP_PASSWORD"
Caller How it signs in
A script or another system An Application Password, or any other method WordPress accepts for REST requests
The admin app The logged-in cookie plus a REST nonce in the X-WP-Nonce header, the normal WordPress way
A visitor’s browser Nothing. The public routes need no login and no nonce, because they are called from cached pages

Permissions

Permission Capability Allows
View plugixa_social_share_view List and read share sets, the catalogue, share analytics and follow buttons
Edit plugixa_social_share_edit Create, change, duplicate and delete share sets, and save follow buttons
Public None Read a post’s counts, record a click, and send the email form PRO

Only administrators hold these when the plugin is activated, and an account with manage_options always holds them all. Grant them to another role with a role editor. The View and Edit checks pass through the plugixa_social_share_user_can filter, so code can narrow or widen them: see Hooks.

Plugin-wide settings need a third capability, plugixa_social_share_manage_settings. The routes behind the Settings screen, the live previews and the import tool are part of the admin app and are not documented here.

Responses

Every successful response is wrapped the same way:

{
  "success": true,
  "data": { "item": { "id": 2, "name": "Footer row" } }
}

Booleans are real booleans and ids and counts are integers. Share sets carry their created and modified times as Unix timestamps; analytics dates are UTC days in the form 2026-11-12.

Lists and pagination

Nothing in this API is paged. List Share Sets returns every set at once, the catalogue returns every network, and the analytics lists are capped by the plugin (the 10 busiest posts). There are no page, per_page or search parameters and no X-WP-Total header.

Every write to a share set answers with the whole list in data.items as well as the set it changed, because saving one set can take a spot from another.

Endpoints

Resource Endpoints
Share Sets List, Create, Get, Update, Delete, Duplicate, Usage
Catalogue Get
Share Counts Get (public), Record click (public)
Analytics Get
Follow Buttons Get, Save
Email Capture PRO Save post by email (public)

A feature that is switched off takes its routes with it: they answer 404. Share counts, Share analytics, Follow buttons and Pro’s Save this post by email can each be off.

Errors

Errors use the standard WordPress shape. Where one input caused the error, data.field names it:

{
  "code": "plugixa_social_share_set_invalid",
  "message": "Choose at least one network.",
  "data": { "status": 400, "field": "instance.networks" }
}

These can come back from any endpoint that is not public. Each endpoint page lists its own errors on top of them.

Status Code When
401 plugixa_social_share_forbidden The request is not signed in: no Application Password, or a cookie sent without a nonce.
401 incorrect_password WordPress itself refused the Application Password before the plugin saw the request.
403 plugixa_social_share_forbidden Signed in, but the account lacks the capability the endpoint needs.
404 rest_no_route No such route or method, or the feature that registers it is switched off.
400 rest_invalid_param A parameter has the wrong type, for example a string where post takes an integer.
400 rest_missing_callback_param A required parameter is missing.

There is no rate limit on signed-in routes. The click beacon allows 60 requests a minute and the email form five in ten minutes, per IP address.

Filtering what comes back

Hook Changes
plugixa_social_share_filter_output Every success payload, with what produced it: sets, counts, analytics, follow or subscribe
plugixa_social_share_user_can The View and Edit permission decision
plugixa_social_share_analytics_payload The analytics answer: add a block under a key of your own. The plugin’s own keys cannot be overwritten
plugixa_social_share_analytics_windows The days values analytics accepts, from 1 to 365
plugixa_social_share_set_usage The answer of Share Set Usage
plugixa_social_share_click_placements Extra placement values the click beacon records

plugixa_social_share_register_rest_routes fires when routes are being registered and passes the namespace, which is where to add your own alongside them. See Hooks for the full set.

Post meta over REST

One post’s own choices are ordinary post meta, exposed through WordPress’s own posts routes (/wp/v2/posts/{id} and the like) on post types that support custom fields. Whoever can edit the post can change them.

Meta key Type Edition
_plugixa_share_hide boolean Free
_plugixa_share_off string[], position slugs Free
_plugixa_share_set integer, a share set number Pro PRO
_plugixa_share_pin_image integer, an attachment ID Pro PRO
_plugixa_share_pin_description string Pro PRO
_plugixa_share_pin_nohover boolean Pro PRO

See Per-post controls.

Troubleshooting

Symptom Usual cause
401 from a script No Application Password, a wrong one, or the host strips the Authorization header before PHP sees it.
403 for an account that is not an administrator It lacks plugixa_social_share_view or plugixa_social_share_edit. Grant the capability to its role.
401 or 403 from the browser The REST nonce is missing or stale. Reload the admin.
404 on a route that should exist Its feature is switched off, or the route is Pro-only and the site runs the free build.
A share set lost its style or placements after an update instance and placements are replaced whole. Send the full objects back, not just the field you changed.
A click never shows in analytics The post is not published, the network or placement is unknown, or the 60-a-minute limit was reached. The beacon answers 204 either way.
Counts come back empty They are below Hide counts below in Settings, or the post is not published.

See also

Quick Links

Share