# 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.
{% 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.

***

## Related Pages

* [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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alhena.gitbook.io/docs/developer-reference/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.