REST API

The Alhena API allows developers to send queries to their Alhena knowledge base and receive AI-generated responses.

API access is available to enterprise customers. Contact the Alhena team to request access.

You only need an API key for backend integrations. For frontend integration, use the Website SDK.

Terminology

A user query is the question sent to Alhena AI.

An AI response is what Alhena AI returns after a user query is submitted.

A thread is all user queries and AI responses in a conversation. All messages in a thread share the same thread_id.

Example thread:

user: Hello

Alhena AI: How can I help you?

user: What is Alhena AI?

Alhena AI: A customer success product

How thread_id works

• For a new conversation, omit thread_id. Alhena AI generates and returns a new thread_id.

• For follow-up messages, pass the thread_id from the previous response.

• Alhena AI returns the thread_id in every response.

---

Send Message

POST https://api.alhena.ai/api/v1/send_message

Send a query to Alhena AI and receive a generated response.

Headers

Name	Type	Description
Authorization *	string	Bearer <your_api_key>

Request Body

Name	Type	Description
query_text *	string	The user's question
thread_id	string	Thread ID for follow-up conversations
faq_id	integer	FAQ ID from the Product FAQs - Developer API endpoint. When provided, returns the cached FAQ answer instead of generating a new AI response. The query_text must exactly match the FAQ question.
page_url	string	The page URL the user is currently on
locale	string	Language code for the response (default: en)
user_metadata	object	Custom metadata to associate with the user

Example Request

curl https://api.alhena.ai/api/v1/send_message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ALHENA_API_KEY" \
  -d '{
     "query_text": "Hi"
   }'

Example Response

{
  "result_text": "Hello! How can I assist you today?",
  "thread_id": "bb708939-b626-48eb-a403-2ea25bb38941"
}

---

Product FAQs - Developer API

GET https://api.alhena.ai/api/v1/product-faqs

Fetch AI-generated product FAQs for a given page URL. FAQs are generated automatically based on the product content on the page.

Product FAQs must be enabled in your dashboard under Settings > Integrations > AI Powered FAQs before this endpoint will return results.

Headers

Name	Type	Description
Authorization *	string	Bearer <your_api_key>

Query Parameters

Name	Type	Description
page_url *	string	The full product page URL (must be http or https)
locale	string	Language code for FAQ translation (default: en)
count	integer	Number of FAQs to return, 1–10 (default: 5)

Response Status Values

The status field in the response indicates the current state of FAQ generation:

Status	HTTP Code	Description
ready	200	FAQs are available and returned in the faqs array
generating	202	FAQs are being generated — retry after the indicated interval
not_available	200	FAQs could not be generated or the feature is not enabled

Example Request

curl "https://api.alhena.ai/api/v1/product-faqs?page_url=https://mystore.com/products/blue-jacket&count=3" \
  -H "Authorization: Bearer $ALHENA_API_KEY"

Example Response — Ready

{
  "status": "ready",
  "faqs": [
    {
      "faq_id": 1,
      "question": "Is this jacket waterproof?"
    },
    {
      "faq_id": 2,
      "question": "What sizes are available?"
    },
    {
      "faq_id": 3,
      "question": "How do I care for this jacket?"
    }
  ]
}

Example Response — Generating

When FAQs are being generated for the first time, the API returns a 202 Accepted status with a Retry-After header.

{
  "status": "generating",
  "retry_after_seconds": 10,
  "message": "FAQs are being generated for this page. Please retry."
}

Poll the same endpoint after the retry_after_seconds interval until the status changes to ready.

Example Response — Not Available

{
  "status": "not_available",
  "faqs": [],
  "message": "Product FAQs are not enabled for this company."
}

Rate Limits

This endpoint is rate-limited to 500 requests per minute per company. Responses are cached for 24 hours.

Getting FAQ Answers

To get the answer for a specific FAQ, pass its faq_id to the Send Message endpoint. The query_text must exactly match the FAQ's question field.

# Step 1: Get FAQs for a product page
curl "https://api.alhena.ai/api/v1/product-faqs?page_url=https://mystore.com/products/blue-jacket" \
  -H "Authorization: Bearer $ALHENA_API_KEY"

# Response: { "status": "ready", "faqs": [{ "faq_id": 1, "question": "Is this jacket waterproof?" }, ...] }

# Step 2: Get the answer for a specific FAQ
curl https://api.alhena.ai/api/v1/send_message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ALHENA_API_KEY" \
  -d '{
     "query_text": "Is this jacket waterproof?",
     "faq_id": 1
   }'

When faq_id is provided, the response is returned from cache and is significantly faster than a standard AI-generated response.

---

Related Pages

• Custom Data — How to use user_metadata to pass user context for personalized AI responses

• Product FAQs — Dashboard setup and configuration for Product FAQs

• Website SDK — Frontend JavaScript API reference