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. Once enabled, organization admins create and manage keys from the dashboard — see Managing API Keys.

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.

---

AI Search

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

Run an AI-powered search against your product catalog: send a natural-language query and receive ranked products from your live catalog together with a conversational answer. Documented on its own page — see AI Search.

---

Related Pages

• AI Search — AI-powered product search over your catalog

• Managing API Keys — Create, scope, and revoke API keys from the dashboard

• 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