API & Developer Resources

This document provides a complete reference for the ShahiAssist REST API, webhooks, integration patterns, sample code, and recommended developer workflows.

—

Table of Contents

1. Authentication & Security
2. API Endpoints (Tickets, KB, Stats)
3. Pagination, Filtering & Sorting
4. Request/Response Examples (curl, JS, PHP)
5. Webhooks: Events & Payloads
6. Rate Limiting & Best Practices
7. Extending Endpoints (custom routes)
8. Integration Examples (Zapier, Integromat, custom)
9. Changelog & Versioning

—

1. Authentication & Security


Supported authentication mechanisms:

• WordPress Application Passwords (recommended for scripts)

– Create under Users → Profile → Application Passwords
– Use basic auth header Authorization: Basic base64(user:app_pass)

• Cookie Authentication (browser sessions)

– Use when calling from logged-in frontends or admin pages

• OAuth / JWT

– Not built-in; you can install JWT/OAuth plugins and use them with REST endpoints

Security notes:

• All endpoints check capabilities where appropriate
• Sensitive routes require manageoptions or editposts depending on context
• Use HTTPS to protect credentials and webhooks

2. API Endpoints


Base namespace: /wp-json/shahi-assist/v1

Tickets
`
GET /tickets – list tickets (supports filters)
GET /tickets/{id} – single ticket
POST /tickets – create ticket
PUT /tickets/{id} – update ticket
DELETE /tickets/{id} – delete ticket
GET /tickets/{id}/replies – list replies
POST /tickets/{id}/replies – add reply
`

KB Articles
`
GET /kb-articles – list KB articles
GET /kb-articles/{id} – single article
POST /kb-articles – create article
PUT /kb-articles/{id} – update article
`

Stats
`
GET /stats – site-wide stats (counts / trending)
`

3. Pagination, Filtering & Sorting


• Pagination parameters: ?page=1&per_page=20
• Filters support: status, category, priority, assignedto, customeremail, product
• Sorting: ?orderby=created_at&order=desc

Example: /wp-json/shahi-assist/v1/tickets?status=saopen&assignedto=45&page=1&per_page=25

4. Request/Response Examples


Create ticket (curl):
`bash
curl -X POST “https://example.com/wp-json/shahi-assist/v1/tickets” \
-u “admin:apppasswordhere” \
-H “Content-Type: application/json” \
-d ‘{“subject”:”Installation issue”,”description”:”I see error X”,”email”:”user@example.com”,”category”:2}’
`

Create ticket (JavaScript, fetch):
`javascript
fetch(‘/wp-json/shahi-assist/v1/tickets’, {
method: ‘POST’,
headers: { ‘Content-Type’: ‘application/json’ },
body: JSON.stringify({ subject: ‘Hello’, description: ‘Help’ })
}).then(r => r.json()).then(console.log).catch(console.error);
`

Add reply (PHP, using wpremotepost):
`php
$response = wpremotepost(rest_url(‘shahi-assist/v1/tickets/123/replies’), [
‘body’ => json_encode([ ‘message’ => ‘Thanks, we are looking into this’ ]),
‘headers’ => [ ‘Authorization’ => ‘Basic ‘ . base64encode(“user:apppass”) , ‘Content-Type’ => ‘application/json’ ]
]);
`

5. Webhooks: Events & Payloads


Supported events:

• ticket.created
• ticket.status_changed
• ticket.reply
• article.published

Example payload (ticket.created):
`json
{
“event”: “ticket.created”,
“timestamp”: “2025-11-27T12:34:56+00:00”,
“data”: {
“ticket_id”: 123,
“ticket”: {
“id”: 123,
“ticket_id”: “SA-AB12CD34”,
“subject”: “User issue”,
“status”: “sa_open”,
“customer_email”: “user@example.com”
}
}
}
`

Delivery & retry policy:

• Webhooks are delivered via POST with JSON body
• On non-2xx responses, the plugin retries 3 times with exponential backoff
• Debug logs record request/response (if enabled)

6. Rate Limiting & Best Practices


• Plugin does not impose strict rate limits, but your host or WP could. Use sensible polling intervals (e.g., >30s) for integrations.
• Use webhooks where possible instead of polling
• Cache heavy queries server-side and use per_page limits to avoid large payloads

7. Extending Endpoints (Custom Routes)


You can extend the API by registering custom routes in a site plugin or theme:

`php
addaction(‘restapi_init’, function() {
registerrestroute(‘shahi-assist/v1’, ‘/reports/summary’, [
‘methods’ => ‘GET’,
‘callback’ => ‘shahiassistreports_summary’,
‘permissioncallback’ => function() { return currentusercan(‘viewstatistics’); }
]);
});

function shahiassistreports_summary($request) {
return restensureresponse([ ‘tickets_total’ => 123, ‘open’ => 12]);
}
`

8. Integration Examples


Zapier / Make (Integromat):

• Use webhooks to push events into Zapier
• Example: Create a Zap that triggers on ticket.created webhook and sends Slack channel message

Custom Integration (Node.js):
`javascript
const axios = require(‘axios’);
axios.post(‘https://example.com/wp-json/shahi-assist/v1/tickets’, { subject: ‘test’ }, { auth: { username: ‘user’, password: ‘app_pass’ } });
`

9. Changelog & Versioning


• API version string is shahi-assist/v1. For breaking changes, we will increment the namespace (e.g., v2) and document migration steps in the changelog.

—

If you want, I can generate a Postman collection and a small SDK (PHP or JS) for common operations. Which SDK should I generate first?