> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/developer-reference/api.md).

# REST API

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

{% hint style="info" %}
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](/docs/developer-reference/api/managing-api-keys.md).
{% endhint %}

{% hint style="info" %}
You only need an API key for backend integrations. For frontend integration, use the [Website SDK](broken://pages/szWmW7TWjvUL73dzCaY6).
{% endhint %}

## 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

<mark style="color:green;">`POST`</mark> `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](#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

```shell
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

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

***

## Product FAQs - Developer API

<mark style="color:blue;">`GET`</mark> `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.

{% hint style="info" %}
Product FAQs must be enabled in your dashboard under **Settings > Integrations > AI Powered FAQs** before this endpoint will return results.
{% endhint %}

#### 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

```shell
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

```json
{
  "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.

```json
{
  "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

```json
{
  "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](#send-message) endpoint. The `query_text` must exactly match the FAQ's `question` field.

```shell
# 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

<mark style="color:green;">`POST`</mark> `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](/docs/developer-reference/api/ai-search.md).

***

## Related Pages

* [AI Search](/docs/developer-reference/api/ai-search.md) — AI-powered product search over your catalog
* [Managing API Keys](/docs/developer-reference/api/managing-api-keys.md) — Create, scope, and revoke API keys from the dashboard
* [Custom Data](/docs/developer-reference/website-sdk/custom-data.md) — How to use `user_metadata` to pass user context for personalized AI responses
* [Product FAQs](/docs/features/product-faqs.md) — Dashboard setup and configuration for Product FAQs
* [Website SDK](/docs/developer-reference/website-sdk/javascript-api.md) — Frontend JavaScript API reference