API Endpoints

The platform exposes functionality through three mechanisms: WordPress REST API endpoints, AJAX endpoints (admin-ajax.php), and internal cron scripts.

---

REST API Endpoints

Suma Gemini (/wp-json/suma/gemini/)

POST /wp-json/suma/gemini/rewrite

Rewrites text content using Gemini AI.

Authentication: API key via suma-gemini-security-key header or WordPress nonce.

Request Body:

{
  "text": "Original text to rewrite",
  "instructions": "Optional rewriting instructions"
}

Response (200):

{
  "success": true,
  "rewritten_text": "The rewritten content..."
}

---

POST /wp-json/suma/gemini/ticket-urgency

Analyzes support ticket content for urgency scoring.

Authentication: API key via suma-gemini-security-key header.

Request Body:

{
  "subject": "Ticket subject line",
  "body": "Full ticket body content",
  "client_name": "Client Organization Name",
  "is_vip": false
}

Response (200):

{
  "success": true,
  "urgency": {
    "score": 65,
    "level": "HIGH",
    "summary": "Brief urgency summary",
    "reasoning": "Explanation of scoring",
    "timeline": "Suggested resolution timeline",
    "suggested_title": "Improved ticket title"
  }
}

Urgency Levels:

Level	Score Range	Description
CRITICAL	75–100	Production down, revenue impact
HIGH	50–74	Major functionality broken
MEDIUM	25–49	Non-critical issue
LOW	0–24	Enhancement request or minor issue

Modifiers:

• VIP client: +10 points
• Workaround available: -15 points

---

POST /wp-json/suma/gemini/parse-email-reply

Parses email thread to extract the latest reply content.

Authentication: API key via suma-gemini-security-key header.

Request Body:

{
  "email_body": "Full email thread content including quoted text"
}

Response (200):

{
  "success": true,
  "parsed_reply": "Extracted latest reply only"
}

---

Suma Harvest (/wp-json/suma/v1/)

POST /wp-json/suma/v1/harvest_time_sync

Synchronizes all Harvest data (clients, projects, tasks, time entries).

Authentication: Public (designed for cron triggers).

Response (200):

{
  "success": true,
  "message": "Harvest sync completed",
  "data": {
    "clients": 15,
    "projects": 42,
    "tasks": 8,
    "time_entries": 1250
  }
}

note

This endpoint takes several minutes due to API rate limiting (10-second delays between Harvest API calls).

---

POST /wp-json/suma/v1/update_milestones

Checks all project milestones and sends alerts for newly triggered thresholds.

Authentication: Public (designed for cron triggers).

Response (200):

{
  "success": true,
  "alerts_sent": 3
}

---

POST /wp-json/suma/v1/update_milestones_tasks

Checks task-level milestones and sends Teams webhook alerts.

Authentication: Public (designed for cron triggers).

Response (200):

{
  "success": true,
  "alerts_sent": 5
}

---

Suma Order Volume Monitor (/wp-json/suma/v1/)

POST /wp-json/suma/v1/trigger-order-volume-tests

Triggers order volume tests for all configured sites.

Authentication: Public (designed for cron triggers).

Response (200):

{
  "success": true,
  "results": [
    {"site": "example.com", "status": "SUCCESS", "message": "2 orders in last 24 hours"},
    {"site": "shop.com", "status": "FAILURE", "message": "0 orders in last 8 hours"}
  ]
}

---

Suma Toolshed (/wp-json/suma-tools/v1/)

Routes are dynamically discovered from /inc/routes/ subdirectories. Each subdirectory with an init.php file registers its own endpoints.

Route Discovery: The API class scans the routes directory and calls register_routes() on each discovered route class.

Common route types:

• BigCommerce routes (extend BigCommerce_Route) — perform operations against BigCommerce v2/v3 APIs
• WooCommerce routes (extend WooCommerce_Route) — perform operations against WooCommerce REST API

---

AJAX Endpoints (admin-ajax.php)

All AJAX endpoints require WordPress nonce authentication and manage_options capability.

Site Management

Action	Method	Description
get_sites	POST	Retrieve paginated site list with filters
get_site	POST	Get single site detail
update_site	POST	Update site properties
delete_site	POST	Delete a site record
archive_site	POST	Archive a site (soft-delete)
add_site	POST	Create new site record
sync_site	POST	Trigger manual sync for one site

Cost Management

Action	Method	Description
get_costs	POST	List all costs with filters
get_cost	POST	Get single cost detail
add_cost	POST	Create new cost record
update_cost	POST	Update cost properties
delete_cost	POST	Delete cost record
assign_cost_to_site	POST	Link a cost to a site
remove_cost_from_site	POST	Unlink a cost from a site

License Management

Action	Method	Description
get_licenses	POST	List license CPT records
map_license	POST	Map license to cost record

Pinecone Vector Operations

Action	Method	Description
pinecone_test_connection	POST	Test Pinecone API connectivity
pinecone_sync_all	POST	Full vectorization of all sites
pinecone_sync_site	POST	Vectorize single site
pinecone_get_stats	POST	Get index statistics (vector count, namespace)

Reports

Action	Method	Description
generate_report	POST	Generate a named report
export_sites	POST	Export sites as CSV
export_plugins	POST	Export plugin data as CSV

Utilities

Action	Method	Description
get_logs	POST	Retrieve activity logs
clear_logs	POST	Clear log entries
get_cron_queue	POST	View pending cron queue
run_lighthouse	POST	Trigger Lighthouse audit for a site
take_screenshot	POST	Capture site screenshot
search_sites	POST	Full-text site search
update_cloudflare	POST	Update Cloudflare zone data
check_ssl	POST	Verify SSL certificate
check_indexed	POST	Check Google indexing status

Gemini AI (AJAX)

Action	Method	Description
test_ticket_urgency	POST	Test urgency analysis with sample data
gemini_rewrite	POST	Rewrite text via Gemini
gemini_clear_cache	POST	Clear AI response cache

---

Security

API Key Validation (Gemini)

// Header-based authentication
$api_key = $request->get_header('suma-gemini-security-key');
$stored_key = get_option('suma-gemini_api_key');

if (!hash_equals($stored_key, $api_key)) {
    return new WP_Error('unauthorized', 'Invalid API key', ['status' => 401]);
}

Rate Limiting (Gemini)

// Transient-based rate limiting (60 requests per 60 seconds)
$transient_key = 'suma_gemini_rate_' . md5($client_ip);
$current_count = get_transient($transient_key) ?: 0;

if ($current_count >= get_option('suma-gemini_rate_limit', 60)) {
    return new WP_Error('rate_limited', 'Too many requests', ['status' => 429]);
}

set_transient($transient_key, $current_count + 1, 60);

AJAX Nonce Verification

// All AJAX handlers verify nonce and capability
check_ajax_referer('suma_management_nonce', 'nonce');

if (!current_user_can('manage_options')) {
    wp_send_json_error('Insufficient permissions');
}

---

Error Responses

All endpoints follow consistent error response patterns:

REST API Errors:

{
  "code": "error_code",
  "message": "Human-readable error description",
  "data": {
    "status": 400
  }
}

AJAX Errors:

{
  "success": false,
  "data": "Error message string"
}

Common Error Codes:

Code	HTTP Status	Description
unauthorized	401	Invalid or missing API key
rate_limited	429	Too many requests
invalid_params	400	Missing or invalid parameters
ai_error	500	Gemini API failure (after retries)
sync_error	500	Data synchronization failure