Hunnt AI API Documentation

Introduction

Description will show here

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

To authenticate requests, include a x-api-key header with the value "{YOUR_API_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Reports

Get Website Health Report

GET
https://hunnt.ai
/api/v1/site/healthy-report
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
{string} Optional. Language preference (en|ar). Default: en
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://hunnt.ai/api/v1/site/healthy-report" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: {string} Optional. Language preference (en|ar). Default: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
Headers 
                                                            cache-control
                                                            : no-cache, private
                                                                                                                    content-type
                                                            : application/json
                                                                                                                    access-control-allow-origin
                                                            : *
                                                         
{
    "success": false,
    "message": "api.Invalid API key",
    "errors": [
        "api.Invalid API key"
    ]
}

Articles

This endpoint allows clients to submit their existing articles for AI-powered improvement

Improve Existing Articles

POST
https://hunnt.ai
/api/v1/article/improve
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Authorization
Example:
Bearer {token} Required. Client authentication token
Accept-Language
Example:
{string} Optional. Language preference (en|ar). Default: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://hunnt.ai/api/v1/article/improve" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Authorization: Bearer {token} Required. Client authentication token" \
    --header "Accept-Language: {string} Optional. Language preference (en|ar). Default: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"articles_list\": [
        \"consequatur\"
    ]
}"
Example response:
{
    "success": true,
    "message": "Data Saved with session id: sess_abc123,sess_abc124",
    "data": {
        "post_ids": [
            123,
            456
        ]
    }
}
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "articles_list": [
            "The articles list field is required."
        ],
        "articles_list.0.article_id": [
            "The article id field is required."
        ],
        "articles_list.0.article_title": [
            "The article title field is required."
        ],
        "articles_list.0.article_content": [
            "The article content field is required."
        ]
    }
}
{
    "success": false,
    "message": "The below articles already sent.",
    "errors": {
        "Article ID 123": "SEO Best Practices 2025",
        "Article ID 456": "Content Marketing Guide 2025"
    }
}

Generate New Articles (Client)

POST
https://hunnt.ai
/api/v1/article/generate
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
{string} Optional. Language preference (en|ar). Default: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://hunnt.ai/api/v1/article/generate" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: {string} Optional. Language preference (en|ar). Default: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"articles_list\": [
        {
            \"number_of_articles\": 15,
            \"language\": \"en\"
        }
    ],
    \"custom_title\": {
        \"en\": [
            \"Best SEO strategies\"
        ],
        \"ar\": [
            \"أفضل طرق تحسين السيو\"
        ]
    },
    \"enable_source_citations\": true,
    \"enable_topic_planning\": true
}"
Example response:
{
    "success": true,
    "message": "Articles is generating",
    "data": []
}
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "articles_list": [
            "The articles list field is required.",
            "The total number of articles must be 15, 30, 60, 90, 120, or a number less than 15."
        ],
        "articles_list.0.number_of_articles": [
            "The number of articles field is required."
        ],
        "articles_list.0.language": [
            "The selected language is invalid."
        ]
    }
}
{
    "success": false,
    "message": "Insufficient articles quota",
    "errors": [
        "You don't have enough articles in your subscription plan. Please upgrade your plan."
    ]
}
{
    "success": false,
    "message": "Internal server error",
    "errors": []
}

Restore Original Article Content

GET
https://hunnt.ai
/api/v1/article/restore
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
{string} Optional. Language preference (en|ar). Default: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

article_id
integer
required

The article ID from your CMS/platform.

Example:
123
Example request: 
curl --request GET \
    --get "https://hunnt.ai/api/v1/article/restore?article_id=123" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: {string} Optional. Language preference (en|ar). Default: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "message": "Article restored successfully",
    "data": {
        "article": {
            "article_title": "SEO Best Practices 2025",
            "article_content": "<p>This is the original article content before improvement...</p>",
            "article_slug": "seo-best-practices-2025",
            "language": "en",
            "categories": [
                "SEO",
                "Marketing",
                "Digital"
            ]
        }
    }
}
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "article_id": [
            "The article id field is required.",
            "The article id must be a number."
        ]
    }
}
{
    "success": false,
    "message": "Article not found",
    "errors": [
        "Article not found"
    ]
}
{
    "success": false,
    "message": "Internal server error",
    "errors": []
}

Generate New Articles (Agency)

POST
https://hunnt.ai
/api/v1/agency/article/generate
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
{string} Optional. Language preference (en|ar). Default: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://hunnt.ai/api/v1/agency/article/generate" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: {string} Optional. Language preference (en|ar). Default: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"publish_type\": \"manual\",
    \"articles\": [
        {
            \"language\": \"en\",
            \"number_of_articles\": 15
        },
        {
            \"language\": \"ar\",
            \"number_of_articles\": 10
        }
    ],
    \"start_date\": \"2025-03-01\",
    \"start_time\": \"10:00\",
    \"repeat_days\": 7,
    \"publish_datetime\": {
        \"en\": [
            \"2025-03-01 10:00:00\",
            \"2025-03-08 10:00:00\"
        ],
        \"ar\": [
            \"2025-03-02 14:00:00\"
        ]
    }
}"
Example response:
{
    "success": true,
    "message": "Articles is generating",
    "data": []
}
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "publish_type": [
            "The publish type field is required."
        ],
        "articles": [
            "The articles field is required."
        ],
        "start_date": [
            "The start date field is required when publish type is semi_automatic."
        ],
        "start_time": [
            "The start time field is required when publish type is semi_automatic."
        ],
        "repeat_days": [
            "The repeat days field is required when publish type is semi_automatic."
        ],
        "publish_datetime": [
            "The publish datetime must contain at least one of the following keys: ar or en.",
            "The publish datetime contains invalid keys: fr"
        ]
    }
}
{
    "success": false,
    "message": "You don't have permission to generate articles",
    "errors": {
        "site": [
            "You don't have permission to generate articles"
        ]
    }
}
{
    "success": false,
    "message": "There is not enough credit to generate new articles",
    "errors": {
        "There is not enough credit to generate new articles": [
            "There is not enough credit to generate new articles"
        ]
    }
}
{
    "success": false,
    "message": "Article generation is not available for this site at this time",
    "errors": {
        "error": "Article generation is not available for this site at this time",
        "start_date": "Start Date: 01 Mar 2025",
        "end_date": "End Date: 31 Mar 2025"
    }
}
{
    "success": false,
    "message": "No articles plan found",
    "errors": [
        "No articles plan found"
    ]
}
{
    "success": false,
    "message": "Internal server error",
    "errors": []
}

Products

This endpoint allows clients to submit existing WooCommerce products for AI-powered content and SEO improvement.

The endpoint can also optionally generate related articles for each submitted product. Article generation can be configured separately for Arabic and English.

Each product must contain either a short description or a long description with at least 100 characters after removing HTML tags.

When article generation is enabled:

  • product_articles is required.
  • Each product ID inside product_articles must exist in products_list.
  • Arabic and English article counts must be between 0 and 100.
  • At least one language count must be greater than zero for each requested product.

Improve Existing Products

POST
https://hunnt.ai
/api/v1/product/improve
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
{string} Optional. Preferred response language. Supported values: en, ar. Default: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://hunnt.ai/api/v1/product/improve" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: {string} Optional. Preferred response language. Supported values: en, ar. Default: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"products_list\": [
        \"consequatur\"
    ],
    \"generate_articles\": true,
    \"product_articles\": {
        \"456\": {
            \"ar\": 2,
            \"en\": 3
        }
    }
}"
Example response:
{
    "success": true,
    "data": {
        "product_ids": [
            456,
            789
        ]
    },
    "message": "Products queued for improvement"
}
{
    "success": false,
    "errors": {
        "product_articles": [
            "Product articles are required when generate_articles is enabled."
        ]
    }
}
{
    "success": false,
    "errors": {
        "product_articles.999": [
            "Article request product_id must exist in products_list."
        ]
    }
}
{
    "success": false,
    "errors": {
        "product_articles.456": [
            "At least one article count must be greater than zero."
        ]
    }
}
{
    "success": false,
    "errors": {
        "products_list.0.short_description": [
            "Either short description or long description must be at least 100 characters."
        ],
        "products_list.0.long_description": [
            "Either short description or long description must be at least 100 characters."
        ]
    }
}

List Improved Products

GET
https://hunnt.ai
/api/v1/product/list
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
string optional Preferred API response language. Supported values: en, ar. Example: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

page
integer

optional Page number. Minimum: 1.

Example:
1
per_page
integer

optional Number of products returned per page. Minimum: 1. Maximum: 100. Default: 20.

Example:
20
search
string

optional Search products by title, external product ID, slug, AI product name, meta title, or meta description. Maximum 255 characters.

Example:
coffee
language
string

optional Filter products by language. Accepted values: ar, en.

Example:
en
Example request: 
curl --request GET \
    --get "https://hunnt.ai/api/v1/product/list?page=1&per_page=20&search=coffee&language=en" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: string optional Preferred API response language. Supported values: en, ar. Example: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "message": "Improved products retrieved successfully.",
    "data": {
        "products": [
            {
                "id": 25,
                "uuid": "54cb2b86-c963-4a95-a5e4-4e213d562419",
                "external_product_id": "456",
                "product_title": "Organic Coffee Beans",
                "product_slug": "organic-coffee-beans",
                "full_product_url": "https://example.com/product/organic-coffee-beans",
                "language": "English",
                "status": "success",
                "is_published": true,
                "publish_date_time": "2026-08-14 12:00:00",
                "ai_completed_date": "2026-08-14 11:45:00",
                "improved_data": {
                    "product_name": "Premium Organic Coffee Beans",
                    "short_description": "Premium organic coffee beans with a rich aroma and balanced flavor.",
                    "long_description": "<p>Discover our premium organic coffee beans...</p>",
                    "category": "Coffee",
                    "tags": [
                        "coffee",
                        "organic",
                        "arabica"
                    ],
                    "meta_title": "Premium Organic Coffee Beans",
                    "meta_description": "Shop premium organic coffee beans with a rich aroma and balanced flavor.",
                    "keywords": [
                        "organic coffee",
                        "arabica coffee"
                    ],
                    "keywords_source": null,
                    "attributes": {
                        "roast": [
                            "Medium"
                        ]
                    },
                    "image_alts": [],
                    "images_input": [],
                    "schema_type": "Product",
                    "schema_data": {},
                    "full_product_url": "https://example.com/product/organic-coffee-beans"
                },
                "created_at": "2026-08-14T08:30:00.000000Z",
                "updated_at": "2026-08-14T09:00:00.000000Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 35,
            "last_page": 2,
            "from": 1,
            "to": 20,
            "has_more_pages": true
        }
    }
}
{
    "success": true,
    "message": "Improved products retrieved successfully.",
    "data": {
        "products": [],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 0,
            "last_page": 1,
            "from": null,
            "to": null,
            "has_more_pages": false
        }
    }
}
{
    "success": false,
    "message": "Client site not found.",
    "errors": {
        "client_site": [
            "Client site not found."
        ]
    }
}
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "language": [
            "The selected language is invalid."
        ]
    }
}
{
    "success": false,
    "message": "Internal Server Error.",
    "errors": {
        "Internal server error": "Internal Server Error. Please try again later."
    }
}

Real Estate

This endpoint is used to either generate a new real estate/property entry or improve an existing one using AI.

The operation type is controlled by realestate.realestate_type:

  • generate: Generate a new real estate entry.
  • improve: Improve an existing real estate entry.

When realestate_type is generate, target_post_type is required. When realestate_type is improve, realestate_id is required.

The request can generate content in Arabic, English, or both. One real estate generation/improvement credit is charged per selected language.

Optionally, related SEO articles can also be generated for the selected languages.

At least one content source must be provided:

  • realestate.free_text
  • realestate.file_urls

If no file_urls are provided, free_text must contain at least 100 characters after HTML tags are removed.

Generate or Improve Real Estate

POST
https://hunnt.ai
/api/v1/realestate/generate-improve
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
string optional Preferred API response language. Supported values: en, ar. Example: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://hunnt.ai/api/v1/realestate/generate-improve" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: string optional Preferred API response language. Supported values: en, ar. Example: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"realestate\": {
        \"realestate_type\": \"generate\",
        \"realestate_id\": \"1250\",
        \"reference_realestate_id\": \"1200\",
        \"realestate_title\": \"Roya Sedra Residential Project\",
        \"realestate_slug\": \"roya-sedra-riyadh\",
        \"realestate_url\": \"https:\\/\\/example.com\\/property\\/roya-sedra-riyadh\",
        \"free_text\": \"Roya Sedra is a residential development located in Riyadh offering modern units, landscaped areas, and family-oriented facilities.\",
        \"file_urls\": [
            \"https:\\/\\/example.com\\/files\\/project-brochure.pdf\"
        ],
        \"primary_keyword\": \"apartments in Riyadh\",
        \"project_name\": \"Roya Sedra\",
        \"target_post_type\": \"property\",
        \"developer_name\": \"Retal Urban Development\",
        \"city\": \"Riyadh\",
        \"target_word_count\": 1200,
        \"price\": \"SAR 1,250,000\",
        \"short_description\": \"Modern residential units in a family-oriented community in Riyadh.\",
        \"meta_title\": \"Roya Sedra Apartments in Riyadh | Hunnt\",
        \"meta_description\": \"Discover Roya Sedra residential units in Riyadh with modern facilities and a strategic location.\",
        \"category\": \"Residential > Apartments\",
        \"tags\": [
            \"riyadh\",
            \"apartments\",
            \"residential\"
        ],
        \"categories_list\": [
            \"consequatur\"
        ],
        \"realestate_image\": \"https:\\/\\/example.com\\/uploads\\/project-main.jpg\",
        \"realestate_images\": [
            \"https:\\/\\/example.com\\/uploads\\/project-1.jpg\",
            \"https:\\/\\/example.com\\/uploads\\/project-2.jpg\"
        ],
        \"attributes\": [
            \"consequatur\"
        ],
        \"custom_fields\": [
            \"fave_property_price\",
            \"fave_property_size\",
            \"fave_property_bedrooms\"
        ],
        \"custom_fields_schema\": [
            \"consequatur\"
        ],
        \"current_custom_fields\": [
            \"consequatur\"
        ],
        \"seo_meta\": [
            \"consequatur\"
        ],
        \"taxonomies_schema\": [
            \"consequatur\"
        ]
    },
    \"languages\": [
        \"ar\",
        \"en\"
    ],
    \"generate_articles\": true,
    \"realestate_articles\": {
        \"ar\": 2,
        \"en\": 3
    },
    \"remove_sources_links\": \"yes\"
}"
Example response:
{
    "success": true,
    "data": {
        "realestate_ids": [
            101,
            102
        ],
        "requested_languages": [
            "ar",
            "en"
        ],
        "charged_realestate_count": 2,
        "charged_articles_count": 5,
        "generate_articles": true
    },
    "message": "Realestate queued"
}
{
    "success": false,
    "errors": {
        "realestate.realestate_type": [
            "The realestate.realestate_type field is required."
        ]
    }
}
{
    "success": false,
    "errors": {
        "realestate.realestate_id": [
            "The realestate.realestate_id field is required when realestate.realestate_type is improve."
        ]
    }
}
{
    "success": false,
    "errors": {
        "realestate.target_post_type": [
            "The realestate.target_post_type field is required when realestate.realestate_type is generate."
        ]
    }
}
{
    "success": false,
    "errors": {
        "realestate.free_text": [
            "Either free_text or file_urls is required."
        ],
        "realestate.file_urls": [
            "Either file_urls or free_text is required."
        ]
    }
}
{
    "success": false,
    "errors": {
        "realestate.free_text": [
            "free_text must be at least 100 characters when no file_urls are provided."
        ]
    }
}
{
    "success": false,
    "errors": {
        "languages": [
            "Duplicate languages are not allowed."
        ]
    }
}
{
    "success": false,
    "errors": {
        "realestate_articles": [
            "Realestate articles are required when generate_articles is enabled."
        ]
    }
}
{
    "success": false,
    "errors": {
        "realestate_articles.en": [
            "Article language must exist in selected realestate languages."
        ]
    }
}
{
    "success": false,
    "errors": {
        "realestate_articles": [
            "At least one article count must be greater than zero."
        ]
    }
}

List Real Estate Results

GET
https://hunnt.ai
/api/v1/realestate/list
requires authentication

Headers

x-api-key
Example:
{YOUR_API_KEY}
Accept-Language
Example:
string optional Preferred API response language. Supported values: en, ar. Example: en
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

page
integer

optional Page number. Minimum: 1.

Example:
1
per_page
integer

optional Number of results returned per page. Minimum: 1. Maximum: 100. Default: 20.

Example:
20
search
string

optional Search by title, project name, external real estate ID, slug, or meta description. Maximum 255 characters.

Example:
Riyadh
language
string

optional Filter results by language. Accepted values: ar, en.

Example:
en
realestate_type
string

optional Filter by real estate operation type. Accepted values: generate, improve.

Example:
generate
Example request: 
curl --request GET \
    --get "https://hunnt.ai/api/v1/realestate/list?page=1&per_page=20&search=Riyadh&language=en&realestate_type=generate" \
    --header "x-api-key: {YOUR_API_KEY}" \
    --header "Accept-Language: string optional Preferred API response language. Supported values: en, ar. Example: en" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "message": "Real estate results retrieved successfully.",
    "data": {
        "realestate": [
            {
                "id": 15,
                "uuid": "54cb2b86-c963-4a95-a5e4-4e213d562419",
                "external_realestate_id": "1250",
                "reference_realestate_id": null,
                "realestate_title": "Roya Sedra Residential Project",
                "realestate_slug": "roya-sedra-riyadh",
                "full_realestate_url": "https://example.com/property/roya-sedra-riyadh",
                "language": "English",
                "realestate_type": "generate",
                "target_post_type": "property",
                "status": "success",
                "is_published": true,
                "publish_date_time": "2026-08-14 12:00:00",
                "ai_completed_date": "2026-08-14 11:45:00",
                "result": {
                    "project_name": "Roya Sedra",
                    "developer_name": "Retal Urban Development",
                    "city": "Riyadh",
                    "title": "Roya Sedra Residential Project in Riyadh",
                    "body": "<h1>Roya Sedra Residential Project</h1><p>...</p>",
                    "summary": "A modern residential development in Riyadh.",
                    "meta_description": "Discover Roya Sedra residential properties in Riyadh.",
                    "primary_keyword": "apartments in Riyadh",
                    "schema_jsonld": {
                        "@context": "https://schema.org"
                    },
                    "full_realestate_url": "https://example.com/property/roya-sedra-riyadh",
                    "custom_fields": {
                        "fave_property_price": "1250000",
                        "fave_property_bedrooms": "3"
                    },
                    "taxonomies": {
                        "property_city": [
                            "Riyadh"
                        ]
                    },
                    "gallery_field": "fave_property_images"
                },
                "created_at": "2026-08-14T08:30:00.000000Z",
                "updated_at": "2026-08-14T09:00:00.000000Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 25,
            "last_page": 2,
            "from": 1,
            "to": 20,
            "has_more_pages": true
        }
    }
}
{
    "success": true,
    "message": "Real estate results retrieved successfully.",
    "data": {
        "realestate": [],
        "pagination": {
            "current_page": 1,
            "per_page": 20,
            "total": 0,
            "last_page": 1,
            "from": null,
            "to": null,
            "has_more_pages": false
        }
    }
}
{
    "success": false,
    "message": "Client site not found.",
    "errors": {
        "client_site": [
            "Client site not found."
        ]
    }
}
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "realestate_type": [
            "The selected realestate type is invalid."
        ]
    }
}
{
    "success": false,
    "message": "Internal Server Error.",
    "errors": {
        "Internal server error": "Internal Server Error. Please try again later."
    }
}