WeGenius API - Getting AI Suggestions

Overview

After submitting an article for analysis, you can retrieve AI-generated suggestions through our API endpoints. This guide covers all the ways to get and work with AI suggestions.

Complete Workflow

1. Submit Article for Analysis

POST /api/ai/articles/submit
Headers:
  X-API-KEY: your-api-key
  Content-Type: application/json

Body:
{
  "wp_post_id": 123,
  "title": "10 Best SEO Tips for WordPress",
  "content": "<p>Your article content...</p>",
  "action_type": "improve",
  "focus_keyphrase": "WordPress SEO optimization"
}

Response:

{
  "success": true,
  "message": "Article submitted for analysis",
  "data": {
    "analysis_id": 456,
    "post_id": 789,
    "wp_post_id": 123,
    "title": "10 Best SEO Tips for WordPress",
    "analysis_type": "improve",
    "status": "pending",
    "estimated_completion": "2025-10-10T10:35:00Z"
  }
}

2. Check Analysis Status

GET /api/ai/articles/analyses/{analysisId}/status
Headers:
  X-API-KEY: your-api-key

Response:

{
  "success": true,
  "data": {
    "analysis": {
      "id": 456,
      "status": "completed",
      "progress_percentage": 100,
      "analysis_type": "improve",
      "started_at": "2025-10-10T10:30:00Z",
      "completed_at": "2025-10-10T10:33:00Z"
    }
  }
}

Getting AI Suggestions

Method 1: Get All Suggestions for an Analysis

Endpoint:

GET /api/ai/suggestions/analysis/{analysisId}
Headers:
  X-API-KEY: your-api-key

Query Parameters (Optional):

status - Filter by status: pending, approved, rejected, implemented
type - Filter by type: seo, readability, content_improvement, new_article, etc.

Example:

GET /api/ai/suggestions/analysis/456?status=pending&type=seo

Response:

{
  "success": true,
  "data": {
    "analysis_id": 456,
    "analysis_type": "improve",
    "suggestions": [
      {
        "id": 1001,
        "type": "seo",
        "section": "meta_tags",
        "status": "pending",
        "suggested_content": {
          "meta_description": "Improve your WordPress SEO with these 10 proven tips...",
          "keywords": ["WordPress", "SEO", "optimization"]
        },
        "explanation": "Optimize meta description for better click-through rates",
        "meta_data": {
          "priority": "high",
          "estimated_impact": "medium"
        },
        "created_at": "2025-10-10T10:33:00Z",
        "implemented_at": null,
        "generate_image": false,
        "generated_image_url": null,
        "image_generation_status": null,
        "has_generated_image": false
      },
      {
        "id": 1002,
        "type": "new_article",
        "section": "content",
        "status": "pending",
        "suggested_content": {
          "title": "Advanced WordPress SEO Techniques for 2025",
          "topic": "WordPress SEO optimization",
          "content_outline": [
            "Introduction to Advanced SEO",
            "Technical SEO for WordPress",
            "Content Optimization Strategies"
          ]
        },
        "explanation": "Related article idea based on content gap analysis",
        "meta_data": {
          "priority": "medium"
        },
        "created_at": "2025-10-10T10:33:00Z",
        "implemented_at": null,
        "generate_image": true,
        "generated_image_url": "https://image.pollinations.ai/prompt/...",
        "image_generation_status": "completed",
        "has_generated_image": true
      }
    ],
    "summary": {
      "total": 2,
      "by_status": {
        "pending": 2,
        "approved": 0,
        "rejected": 0
      },
      "by_type": {
        "seo": 1,
        "new_article": 1
      }
    }
  }
}

Method 2: Get Single Suggestion Details

Endpoint:

GET /api/ai/suggestions/{suggestionId}
Headers:
  X-API-KEY: your-api-key

Example:

GET /api/ai/suggestions/1001

Response:

{
  "success": true,
  "data": {
    "suggestion": {
      "id": 1001,
      "type": "seo",
      "section": "meta_tags",
      "status": "pending",
      "position": null,
      "original_content": null,
      "suggested_content": {
        "meta_description": "Improve your WordPress SEO...",
        "keywords": ["WordPress", "SEO"]
      },
      "explanation": "Optimize meta description for better click-through rates",
      "meta_data": {
        "priority": "high"
      },
      "created_at": "2025-10-10T10:33:00Z",
      "updated_at": "2025-10-10T10:33:00Z",
      "implemented_at": null,
      "generate_image": false,
      "generated_image_url": null,
      "image_generation_status": null,
      "image_generation_error": null,
      "has_generated_image": false
    },
    "analysis": {
      "id": 456,
      "type": "improve",
      "status": "completed"
    },
    "article": {
      "id": 789,
      "title": "10 Best SEO Tips for WordPress",
      "wp_post_id": 123
    }
  }
}

Method 3: Get Analysis Results (Includes Suggestions)

Endpoint:

GET /api/ai/articles/analyses/{analysisId}/results
Headers:
  X-API-KEY: your-api-key

Response:

{
  "success": true,
  "data": {
    "analysis": {
      "id": 456,
      "status": "completed",
      "analysis_type": "improve",
      "overall_score": 78,
      "focus_keyphrase": "WordPress SEO optimization",
      "completed_at": "2025-10-10T10:33:00Z"
    },
    "metrics": {
      "seo_score": 82,
      "readability_score": 75,
      "content_score": 80,
      "engagement_score": 70
    },
    "post": {
      "id": 789,
      "title": "10 Best SEO Tips for WordPress",
      "wp_post_id": 123
    },
    "suggestions": [
      // Same format as Method 1
    ],
    "suggestion_summary": {
      "total": 5,
      "pending": 5,
      "implemented": 0
    }
  }
}

Working with Suggestions

Approve Suggestions

POST /api/ai/suggestions/approve
Headers:
  X-API-KEY: your-api-key
  Content-Type: application/json

Body:
{
  "suggestion_ids": [1001, 1002]
}

Response:

{
  "success": true,
  "message": "2 suggestions approved successfully",
  "data": {
    "approved_count": 2
  }
}

Reject Suggestions

POST /api/ai/suggestions/reject
Headers:
  X-API-KEY: your-api-key
  Content-Type: application/json

Body:
{
  "suggestion_ids": [1003],
  "rejection_reason": "Not applicable to our content strategy"
}

Response:

{
  "success": true,
  "message": "1 suggestion rejected successfully"
}

Implement Suggestions

POST /api/ai/suggestions/implement
Headers:
  X-API-KEY: your-api-key
  Content-Type: application/json

Body:
{
  "suggestion_ids": [1001],
  "auto_apply": true
}

Response:

{
  "success": true,
  "message": "1 suggestion implemented successfully",
  "data": {
    "implemented_count": 1,
    "content_version": {
      "version_number": 2,
      "created_at": "2025-10-10T10:40:00Z"
    }
  }
}

Image Generation Features

Toggle Image Generation for New Article Suggestions

POST /api/ai/suggestions/{suggestionId}/generate-image
Headers:
  X-API-KEY: your-api-key
  Content-Type: application/json

Body:
{
  "generate_image": true
}

Response:

{
  "success": true,
  "message": "Image generation queued successfully",
  "data": {
    "suggestion_id": 1002,
    "generate_image": true,
    "image_generation_status": "pending",
    "estimated_time": "3-5 seconds"
  }
}

Check Image Generation Status

GET /api/ai/suggestions/{suggestionId}/image-status
Headers:
  X-API-KEY: your-api-key

Response:

{
  "success": true,
  "data": {
    "suggestion_id": 1002,
    "generate_image": true,
    "image_generation_status": "completed",
    "generated_image_url": "https://image.pollinations.ai/prompt/Advanced-WordPress-SEO-Techniques...",
    "image_generation_error": null,
    "has_generated_image": true
  }
}

Image Generation Statuses:

pending - Image generation queued
processing - Currently generating
completed - Image generated successfully
failed - Generation failed
skipped - Image generation disabled

Export Suggestions

Export to Various Formats

GET /api/ai/suggestions/analysis/{analysisId}/export?format=markdown
Headers:
  X-API-KEY: your-api-key

Query Parameters:

format - Export format: markdown, json, csv
status - Filter: pending, approved, rejected
type - Filter: seo, readability, etc.

Response (Markdown):

# AI Suggestions for: 10 Best SEO Tips for WordPress

## SEO Suggestions

### Suggestion #1001
**Type:** seo  
**Status:** pending  
**Explanation:** Optimize meta description for better click-through rates

**Suggested Content:**
- Meta Description: Improve your WordPress SEO...
- Keywords: WordPress, SEO, optimization

Complete Code Example (PHP/WordPress)

<?php
/**
 * WeGenius API Integration Example
 */

class WeGeniusAPIClient {
    private $apiKey;
    private $baseUrl = 'https://wegenius.test/api/ai';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    /**
     * Submit article for analysis
     */
    public function submitArticle($postId) {
        $post = get_post($postId);
        
        $response = wp_remote_post($this->baseUrl . '/articles/submit', [
            'headers' => [
                'X-API-KEY' => $this->apiKey,
                'Content-Type' => 'application/json',
            ],
            'body' => json_encode([
                'wp_post_id' => $post->ID,
                'title' => $post->post_title,
                'content' => $post->post_content,
                'action_type' => 'improve',
                'focus_keyphrase' => get_post_meta($postId, 'focus_keyphrase', true),
                'permalink' => get_permalink($postId),
                'status' => $post->post_status,
                'author_name' => get_the_author_meta('display_name', $post->post_author),
            ]),
            'timeout' => 30,
        ]);
        
        if (is_wp_error($response)) {
            return ['error' => $response->get_error_message()];
        }
        
        return json_decode(wp_remote_retrieve_body($response), true);
    }
    
    /**
     * Get AI suggestions for an analysis
     */
    public function getSuggestions($analysisId, $filters = []) {
        $url = $this->baseUrl . "/suggestions/analysis/{$analysisId}";
        
        if (!empty($filters)) {
            $url .= '?' . http_build_query($filters);
        }
        
        $response = wp_remote_get($url, [
            'headers' => [
                'X-API-KEY' => $this->apiKey,
            ],
            'timeout' => 15,
        ]);
        
        if (is_wp_error($response)) {
            return ['error' => $response->get_error_message()];
        }
        
        return json_decode(wp_remote_retrieve_body($response), true);
    }
    
    /**
     * Get single suggestion detail
     */
    public function getSuggestionDetail($suggestionId) {
        $response = wp_remote_get(
            $this->baseUrl . "/suggestions/{$suggestionId}",
            [
                'headers' => ['X-API-KEY' => $this->apiKey],
                'timeout' => 15,
            ]
        );
        
        if (is_wp_error($response)) {
            return ['error' => $response->get_error_message()];
        }
        
        return json_decode(wp_remote_retrieve_body($response), true);
    }
    
    /**
     * Approve suggestions
     */
    public function approveSuggestions($suggestionIds) {
        $response = wp_remote_post($this->baseUrl . '/suggestions/approve', [
            'headers' => [
                'X-API-KEY' => $this->apiKey,
                'Content-Type' => 'application/json',
            ],
            'body' => json_encode([
                'suggestion_ids' => $suggestionIds,
            ]),
            'timeout' => 15,
        ]);
        
        if (is_wp_error($response)) {
            return ['error' => $response->get_error_message()];
        }
        
        return json_decode(wp_remote_retrieve_body($response), true);
    }
    
    /**
     * Generate featured image for new article suggestion
     */
    public function generateImage($suggestionId) {
        $response = wp_remote_post(
            $this->baseUrl . "/suggestions/{$suggestionId}/generate-image",
            [
                'headers' => [
                    'X-API-KEY' => $this->apiKey,
                    'Content-Type' => 'application/json',
                ],
                'body' => json_encode(['generate_image' => true]),
                'timeout' => 15,
            ]
        );
        
        if (is_wp_error($response)) {
            return ['error' => $response->get_error_message()];
        }
        
        return json_decode(wp_remote_retrieve_body($response), true);
    }
    
    /**
     * Check image generation status
     */
    public function getImageStatus($suggestionId) {
        $response = wp_remote_get(
            $this->baseUrl . "/suggestions/{$suggestionId}/image-status",
            [
                'headers' => ['X-API-KEY' => $this->apiKey],
                'timeout' => 15,
            ]
        );
        
        if (is_wp_error($response)) {
            return ['error' => $response->get_error_message()];
        }
        
        return json_decode(wp_remote_retrieve_body($response), true);
    }
}

// Usage Example
$client = new WeGeniusAPIClient('your-api-key-here');

// 1. Submit article
$result = $client->submitArticle(123);
$analysisId = $result['data']['analysis_id'];

// 2. Wait for analysis (poll status or use webhooks)
sleep(30);

// 3. Get all suggestions
$suggestions = $client->getSuggestions($analysisId);

// 4. Filter pending SEO suggestions
$seoSuggestions = $client->getSuggestions($analysisId, [
    'status' => 'pending',
    'type' => 'seo'
]);

// 5. Get specific suggestion
$suggestion = $client->getSuggestionDetail(1001);

// 6. Approve suggestions
$client->approveSuggestions([1001, 1002]);

// 7. Generate image for new article suggestion
$client->generateImage(1002);

// 8. Check if image is ready
$imageStatus = $client->getImageStatus(1002);
if ($imageStatus['data']['has_generated_image']) {
    $imageUrl = $imageStatus['data']['generated_image_url'];
    // Download and set as featured image
}

Error Responses

404 - Not Found

{
  "success": false,
  "message": "Analysis not found"
}

403 - Unauthorized

{
  "success": false,
  "message": "Unauthorized access"
}

422 - Validation Error

{
  "success": false,
  "message": "Validation error",
  "errors": {
    "suggestion_ids": ["The suggestion ids field is required."]
  }
}

500 - Server Error

{
  "success": false,
  "message": "Failed to get suggestions",
  "error": "Internal server error"
}

Rate Limiting

Limit: 60 requests per minute per API key
Headers: Check X-RateLimit-Limit and X-RateLimit-Remaining in response

Best Practices

Poll Status: Check analysis status before requesting suggestions
Filter Suggestions: Use query parameters to get only relevant suggestions
Batch Operations: Approve/reject multiple suggestions in one request
Image Generation: Poll image status every 2-3 seconds (not more frequently)
Cache Results: Cache suggestion data to reduce API calls
Error Handling: Always check success field and handle errors gracefully
Use Focus Keyphrase: Include focus_keyphrase when submitting articles for better SEO analysis

Quick Reference

Endpoint	Method	Purpose
`/api/ai/articles/submit`	POST	Submit article for analysis
`/api/ai/articles/analyses/{id}/status`	GET	Check analysis status
`/api/ai/articles/analyses/{id}/results`	GET	Get complete analysis with suggestions
`/api/ai/suggestions/analysis/{id}`	GET	Get all suggestions for analysis
`/api/ai/suggestions/{id}`	GET	Get single suggestion detail
`/api/ai/suggestions/approve`	POST	Approve suggestions
`/api/ai/suggestions/reject`	POST	Reject suggestions
`/api/ai/suggestions/implement`	POST	Implement suggestions
`/api/ai/suggestions/{id}/generate-image`	POST	Toggle image generation
`/api/ai/suggestions/{id}/image-status`	GET	Check image status
`/api/ai/suggestions/analysis/{id}/export`	GET	Export suggestions

Support

For questions or issues:

Documentation: https://wegenius.test/api-documentation
Email: support@wegenius.com
GitHub: https://github.com/arifulhoque7/wegenius

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WeGenius API - Getting AI Suggestions

Overview

Complete Workflow

1. Submit Article for Analysis

2. Check Analysis Status

Getting AI Suggestions

Method 1: Get All Suggestions for an Analysis

Method 2: Get Single Suggestion Details

Method 3: Get Analysis Results (Includes Suggestions)

Working with Suggestions

Approve Suggestions

Reject Suggestions

Implement Suggestions

Image Generation Features

Toggle Image Generation for New Article Suggestions

Check Image Generation Status

Export Suggestions

Export to Various Formats

Complete Code Example (PHP/WordPress)

Error Responses

404 - Not Found

403 - Unauthorized

422 - Validation Error

500 - Server Error

Rate Limiting

Best Practices

Quick Reference

Support

FilesExpand file tree

API_SUGGESTIONS_GUIDE.md

Latest commit

History

API_SUGGESTIONS_GUIDE.md

File metadata and controls

WeGenius API - Getting AI Suggestions

Overview

Complete Workflow

1. Submit Article for Analysis

2. Check Analysis Status

Getting AI Suggestions

Method 1: Get All Suggestions for an Analysis

Method 2: Get Single Suggestion Details

Method 3: Get Analysis Results (Includes Suggestions)

Working with Suggestions

Approve Suggestions

Reject Suggestions

Implement Suggestions

Image Generation Features

Toggle Image Generation for New Article Suggestions

Check Image Generation Status

Export Suggestions

Export to Various Formats

Complete Code Example (PHP/WordPress)

Error Responses

404 - Not Found

403 - Unauthorized

422 - Validation Error

500 - Server Error

Rate Limiting

Best Practices

Quick Reference

Support