REST API Reference

REST API Reference

Base URL: /wp-json/bpquotes/v1/

Authentication: All routes require a valid WordPress session. Pass the X-WP-Nonce header with a nonce generated from wp_create_nonce( 'wp_rest' ). The plugin’s frontend scripts expose the nonce as bpquotes_obj.rest_nonce.

Error format: All errors return a WP_Error-style JSON object with a stable code string so clients can branch without parsing messages.

{
  "code": "bpquotes_render_throttled",
  "message": "Too many render requests. Try again shortly.",
  "data": { "status": 429 }
}

---

Render

POST /render/{activity_id}

Renders a posted quote to a PNG image and returns share links.

Permission: Logged-in member.

Path parameter:

Parameter	Type	Description
activity_id	integer	The BuddyPress activity ID to render

Body parameters:

Parameter	Type	Default	Description
size	string	card	Output dimensions. One of card, square, story.

Response (200):

{
  "url": "https://example.com/wp-content/uploads/bpquotes-shared/abc123.png",
  "expires_at": "2025-06-02T15:00:00+00:00",
  "share_links": {
    "twitter":   "https://twitter.com/intent/tweet?...",
    "facebook":  "https://www.facebook.com/sharer/sharer.php?...",
    "whatsapp":  "https://wa.me/?text=...",
    "linkedin":  "https://www.linkedin.com/sharing/share-offsite/?...",
    "pinterest": "https://pinterest.com/pin/create/button/?..."
  }
}

The rendered PNG is cached for one hour. Repeated calls within that window return the same URL without re-rendering.

Notable error codes:

Code	Status	Meaning
bpquotes_not_quoted	400	The activity does not have a quote background
bpquotes_render_throttled	429	Render rate limit exceeded

---

Scheduled Posts

POST /scheduled

Schedule a new quote post for a future time.

Permission: Logged-in member.

Body parameters:

Parameter	Type	Required	Description
scheduled_for	string	Yes	ISO 8601 date-time string for when to publish
content	string	Yes	Quote text (sanitised with wp_kses_post)
bg_type	string	No	Background type (quotesimg, quotescolor, etc.)
bg_value	string	No	Background value (image URL or color)
bg_inverted_value	string	No	Text/inverted color
group_id	integer	No	BuddyPress group ID for group posts
visibility	string	No	Activity visibility setting

Response (200):

{
  "id": 42,
  "scheduled_for": "2025-06-10T09:00:00+00:00",
  "status": "pending"
}

---

GET /scheduled

List the current user’s scheduled posts.

Permission: Logged-in member (returns only the caller’s own posts).

Query parameters:

Parameter	Type	Default	Description
status	string	(all)	Filter by status: pending, published, cancelled
limit	integer	50	Maximum rows to return

Response (200):

{
  "items": [ ... ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

---

GET /scheduled/admin

Site-wide list of all scheduled posts.

Permission: Admin (manage_options capability).

Query parameters:

Parameter	Type	Default	Description
status	string	(all)	Filter by status
limit	integer	50	Maximum rows
offset	integer	0	Pagination offset

---

DELETE /scheduled/{id}

Cancel a pending scheduled post.

Permission: Logged-in member. The caller must own the scheduled post, or be an admin.

Path parameter:

Parameter	Type	Description
id	integer	Scheduled post row ID

Response (200):

{
  "cancelled": true,
  "id": 42
}

---

AI Suggestions

POST /ai/suggest

Generate candidate quote text from a short prompt.

Permission: Logged-in member.

Body parameters:

Parameter	Type	Required	Default	Description
prompt	string	Yes	—	Topic, mood, or theme for the quote
context	string	No	—	compose (new quote) or refine (rewrite existing text)
count	integer	No	3	Number of suggestions to return (1–5)

Response (200):

{
  "suggestions": [
    "The only way to do great work is to love what you do.",
    "Innovation distinguishes between a leader and a follower.",
    "Stay hungry, stay foolish."
  ],
  "model": "claude-3-haiku-20240307",
  "latency_ms": 842,
  "remaining_quota": 7
}

remaining_quota is the caller’s remaining daily suggestion count.

Notable error codes:

Code	Status	Meaning
bpquotes_ai_unavailable	503	No AI provider configured
bpquotes_ai_quota_exceeded	429	Daily cap reached for this user or site

---

POST /ai/report

Report an AI-generated suggestion as inappropriate.

Permission: Logged-in member.

Body parameters:

Parameter	Type	Required	Description
text	string	Yes	The exact suggestion text being reported
reason	string	No	Optional short reason

Response (200):

{
  "reported": true
}

---

GET /ai/reports

Retrieve recent content-safety reports.

Permission: Admin.

Response (200):

{
  "items": [
    {
      "id": 3,
      "user_id": 44,
      "text": "Reported text...",
      "reason": "offensive",
      "reported_at": "2025-06-01T11:05:00+00:00"
    }
  ],
  "total": 1
}

Returns up to the 50 most recent reports.

---

JavaScript Usage Example

const response = await fetch(
    `${bpquotes_obj.rest_root}bpquotes/v1/render/${activityId}`,
    {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-WP-Nonce': bpquotes_obj.rest_nonce,
        },
        body: JSON.stringify( { size: 'card' } ),
    }
);
const data = await response.json();
// data.url — PNG URL
// data.share_links.twitter — pre-built Twitter share URL

The plugin localises bpquotes_obj on all frontend pages where the quote UI is active.