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
- Build sets in the admin: Share sets.
- How counts and clicks are gathered: Share counts.
- The email form behind the public route: Email capture PRO.
- Change behaviour in PHP instead: Hooks.
Quick Links
Share