Reference
REST API Reference
Base URL: https://api.wpsignal.io
1. Health Check
No authentication required. Confirms the server is reachable.
curl https://api.wpsignal.io/healthzReturns: { "status": "ok" }
2. Auth
Signup
Create a new account. Returns a session token and API key.
curl -s -X POST https://api.wpsignal.io/auth/signup \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"yourpassword"}'Returns: { "token": "session_jwt", "api_key": "hex_string" }
Login
Authenticate with email and password.
curl -s -X POST https://api.wpsignal.io/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"yourpassword"}'Returns: { "token": "session_jwt", "api_key": "hex_string" }
Get Current User
Verify a session token and retrieve account details.
curl -s https://api.wpsignal.io/auth/me \
-H 'Authorization: Bearer YOUR_SESSION_JWT'Returns: { "email": "...", "api_key": "...", "role": "user" }
3. Site Registration
Register a new site. Requires your API key from the dashboard. Create a free account at wpsignal.io. Returns credentials that the WordPress plugin saves automatically.
curl -s -X POST https://api.wpsignal.io/api/sites/register \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"site_url":"https://example.com","site_name":"My Site"}'Returns: { "site_key": "...", "publish_secret": "...", "jwt_secret": "..." }
4. Dashboard
List My Sites
curl -s https://api.wpsignal.io/api/dashboard/sites \
-H 'Authorization: Bearer YOUR_SESSION_JWT'Delete a Site
curl -s -X DELETE https://api.wpsignal.io/api/dashboard/sites/YOUR_SITE_KEY \
-H 'Authorization: Bearer YOUR_SESSION_JWT'Regenerate API Key
curl -s -X POST https://api.wpsignal.io/api/dashboard/regenerate-key \
-H 'Authorization: Bearer YOUR_SESSION_JWT'Returns: { "api_key": "new_hex_string" }
5. Publish
Push an event to a channel. The request must be HMAC-SHA256 signed using your
publish_secret.
The signature covers body + "." + timestamp_ms.
Required headers
x-wp-signal-key: your site_key
x-wp-signal-ts: Unix timestamp in milliseconds
x-wp-signal-sign: HMAC-SHA256 hex signature
SITE_KEY="YOUR_SITE_KEY"
SITE_SECRET="YOUR_PUBLISH_SECRET"
BODY='{"channel":"events","event":"post.updated","data":{"id":1,"title":"Hello"}}'
TIMESTAMP=$(date +%s%3N)
SIGNATURE=$(echo -n "${BODY}.${TIMESTAMP}" | openssl dgst -sha256 -hmac "$SITE_SECRET" | awk '{print $2}')
curl -s -X POST https://api.wpsignal.io/publish \
-H 'Content-Type: application/json' \
-H "x-wp-signal-key: $SITE_KEY" \
-H "x-wp-signal-ts: $TIMESTAMP" \
-H "x-wp-signal-sign: $SIGNATURE" \
-d "$BODY"Returns: { "ok": true }
Limits
Payload: 256 KB maximum
Timestamp tolerance: 60 seconds in the past, 5 seconds in the future
Rate limit: 30 burst, 10 requests/second per site_key
6. Dev Token
Mint a short-lived connection JWT without authentication. Intended for development and testing only.
curl -s -X POST https://api.wpsignal.io/dev/token \
-H 'Content-Type: application/json' \
-d '{"site_key":"YOUR_SITE_KEY","user_id":"1","channels":["events"]}'Returns: { "token": "connection_jwt", "channels": ["events"], "exp": 1234567890 }
7. SSE (Server-Sent Events)
Subscribe to channels over a persistent HTTP connection. Use -N to disable cURL buffering.
curl -s -N 'https://api.wpsignal.io/sse?token=YOUR_SESSION_JWT&channels=events'Events are streamed in SSE format. The connection stays open until either side closes it. Use the connection JWT from /dev/token or the WordPress plugin's REST endpoint.
8. WebSocket
The WebSocket transport is not directly usable with cURL. Use websocat for command-line testing.
websocat 'wss://api.wpsignal.io/ws?token=YOUR_SESSION_JWT'Client-to-server frames
| Frame | Example |
|---|---|
| subscribe | {"type":"subscribe","channels":["events"]} |
| unsubscribe | {"type":"unsubscribe","channels":["events"]} |
| auth | {"type":"auth","token":"new_jwt"} |
| pong | {"type":"pong"} |
Server-to-client frames
| Type | Description |
|---|---|
| message | Published event payload |
| subscribed | Confirmation of subscription |
| unsubscribed | Confirmation of unsubscription |
| auth_ok | Token refresh accepted |
| ping | Keepalive sent every 20 seconds; respond with pong |
| error | Error details from the server |
9. Admin
All admin endpoints require a session JWT with the admin role.
List All Users
curl -s https://api.wpsignal.io/api/admin/users \
-H 'Authorization: Bearer YOUR_SESSION_JWT'Delete a User
curl -s -X DELETE https://api.wpsignal.io/api/admin/users/USER_ID \
-H 'Authorization: Bearer YOUR_SESSION_JWT'List All Sites
curl -s https://api.wpsignal.io/api/admin/sites \
-H 'Authorization: Bearer YOUR_SESSION_JWT'Hub Stats
curl -s https://api.wpsignal.io/api/admin/stats \
-H 'Authorization: Bearer YOUR_SESSION_JWT'Returns: { "active_connections": 0, "published_messages": 0, "dropped_messages": 0, "total_users": 1, "total_sites": 1 }