# Aura Analyst API

> **📝 Note**: This is a Preview feature.

[Aura Analyst](https://docs.singlestore.com/cloud/ai/aura-analyst.md) is a managed, AI-powered data analyst built natively for SingleStore. It enables you to submit natural language queries, which are automatically translated into optimized SQL statements and executed against the selected data sources. Built on SingleStore's Agentic AI platform, Aura Analyst delivers context-aware, governed, and accurate insights.

SingleStore Aura Analyst API ("the API") enables you to embed [Aura Analyst](https://docs.singlestore.com/cloud/ai/aura-analyst.md) capabilities in your applications, workflows, and user experiences via a REST interface to provide conversational access to data and analytics. Query the API using natural language queries and receive insights on your SingleStore data as tables, charts, or summaries.

## Why Use the Analyst API

The Analyst API provides a streamlined model to integrate Aura Analyst in your applications, which allows you to:

* Send natural language queries and receive generated SQL, results, and visualizations.
* Build interactive analytics experiences using a streaming chat endpoint that delivers real-time events over Server-Sent Events (SSE).
* Maintain multi-turn analytic sessions enabling follow-up questions to reuse prior context and results.

## Analyst API Endpoint Reference

Analyst API currently supports the following endpoints:

| Endpoint                 | HTTP Method | Request Body | Description                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/query`                 | `POST`      | Required     | **Structured Query Endpoint**Runs a natural language analytics query and returns a single, structured JSON response containing generated SQL, optional result data, charts, and explanatory text. Use this endpoint for integrations, pipelines, scheduled jobs, and embedded use-cases that require deterministic, machine-readable output instead of a chat-based stream. |
| `/chat`                  | `POST`      | Required     | **Streaming Chat Endpoint**Runs a natural language analytics query and streams back Server-Sent Events (SSE) for use in interactive chat-style UIs. Use this endpoint when real-time typing indicators or incremental responses are required for a chat-based stream.                                                                                                       |
| `/conversation-starters` | `GET`       |              | **Conversation Starter Endpoint**Returns a list of generated starter prompts tailored to the current domain and agent context. Use this endpoint to populate suggested questions in the UI before a user submits the first query or starts a chat session.                                                                                                                  |

Use the `/query` endpoint for most integrations. It returns a single structured JSON response and is easier to parse in back-end services, pipelines, and embedded product workflows. Use the `/chat` endpoint for a streaming, interactive chat experience over Server-Sent Events (SSE), such as real-time typing indicators or incremental responses in a UI.

Refer to [Aura Analyst API Reference](https://docs.singlestore.com/cloud/ai/aura-analyst/aura-analyst-api-reference.md) for more information.

## Authentication

Analyst API authenticates to the server using [Bearer authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) standard, which must be used in conjunction with SSL (HTTPS) for secure communication over the network. To access the API, provide the Analyst API key in the Authorization request header in each HTTP request (API call). The API key is scoped at the domain-level, i.e., each API key is unique to the domain selected while generating the API key.

## Generate an API Key

To generate an API key for Analyst API:

1. On the [Cloud Portal](https://portal.singlestore.com), select **AI > Analyst** on the left navigation pane.

2. On the **Analyst** page, enable **Creator Mode**.

3. From the **Domain** list, select a domain.

4. Under **Governance**, select **API Keys** in the left pane.

5. On the **API Keys** page, select **Create API Key**.

6. In the **Create API key** dialog, enter a name for the API key and select an expiration window.

7. Select **Create API Key**.

8. Copy and securely store the API key. Alternatively, select **Save As Secret** to store the API key as a secret; enter a name for the secret in the **New Secret** dialog, and select **Create Secret**.
   > **📝 Note**: The API key is displayed only once.

9. Select **Close**.

Use this key in the API call to authorize access to the API.

## Revoke an API Key

To revoke an existing API key:

1. Select **AI > Analyst**, enable **Creator Mode**, and select a domain.

2. Navigate to the **API Keys** section in the left pane.

3. Under the **Actions** column for the API key, select the delete icon.

4. On the **Revoke API Key** dialog, acknowledge the warning, and select **Revoke**.

The API key is now successfully revoked.

## Access the Analyst API

Copy the endpoint URL from the [Cloud Portal](https://portal.singlestore.com):

1. Select **AI > Analyst**, enable **Creator Mode**, and select a domain.

2. Navigate to the **API Keys** section in the left pane.

3. Select **Copy Endpoint** to copy the URL of the `/chat` endpoint. Replace `chat` with the endpoint to access in the URL.

The base URL of the Analyst API conforms to the following format:

```URL
https://apps.{region}.cloud.singlestore.com/v1/organizations/{orgID}/projects/{projectID}/analyst/<endpoint>
```

> **📝 Note**: The Analyst API endpoints use a domain-scoped API key for authentication. The API key's JWT claims encode the allowed domain, project, organization, and creator for a request. The `{orgID}` and `{projectID}` in the request path must match the key’s claims; otherwise, the request is rejected with `403 INVALID_API_KEY`.

To access the Analyst API, specify the API key in the Authorization header of the API request. For example, while making API calls through an HTTP client (such as cURL), specify the endpoint URL and API key as follows:

```shell
curl -X 'POST' \
  '<api_endpoint_url>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_key>'
```

## Getting Started with Aura Analyst API

To get started with the API:

1. [Create a domain](https://docs.singlestore.com/cloud/ai/aura-analyst/#section-id235182638851576.md) on the [Cloud Portal](https://portal.singlestore.com), or select an existing domain.

2. [Generate an API key](https://docs.singlestore.com/#section-id235672341710795.md) for the Analyst API.

3. [Copy the endpoint URL](https://docs.singlestore.com/#section-id235672343574668.md).

4. Use the API endpoint to access Aura Analyst via the API.

## Start a New Chat Session

Use the `POST /chat` endpoint to start an interactive Aura Analyst conversation over Server-Sent Events (SSE). To create a new chat session, omit `session_id` from the request body. You can also send `null` or an empty string and the gateway will create a new session automatically. The returned session can then be reused in later requests to continue the conversation. For example (update the endpoint, the API key, and message before running the following command):

```shell
curl -X POST "https://apps.${REGION}.cloud.singlestore.com/v1/organizations/${ORG_ID}/projects/${PROJECT_ID}/analyst/chat" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Show me sales data for Q4."
  }'
```

The first stream includes a `response.created` event containing the generated `session_id`. Capture this value and include it in the next request to continue the same chat context.

## Continue an Existing Chat Session

Use the same `POST /chat` endpoint (used to start a new chat) to continue a prior Aura Analyst conversation. Include the previously returned `session_id` in the request body so the Analyst can reuse the earlier context and interpret follow-up questions correctly. For example (update the endpoint, the API key, message, and session ID before running the following command):

```shell
curl -X POST "https://apps.${REGION}.cloud.singlestore.com/v1/organizations/${ORG_ID}/projects/${PROJECT_ID}/analyst/chat" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Break that down by region",
    "session_id": "${SESSION_ID}"
  }'
```

The `session_id` must be a valid UUID.

## Get the Generated SQL from a Chat

## Streaming Chat Endpoint

To retrieve generated SQL from the streaming chat endpoint, send the request to `POST /chat` endpoint and set `included_events` to `["sql"]`, which is the event type used for generated SQL queries. The `included_events` field controls which event types are returned for chat responses. If you omit `included_events` or pass an empty array, the API returns all chat events. For example (update the endpoint, the API key, and message before running the following command):

```shell
curl -X POST "https://apps.${REGION}.cloud.singlestore.com/v1/organizations/${ORG_ID}/projects/${PROJECT_ID}/analyst/chat" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "What were the top 10 products by revenue last month?",
    "included_events": ["sql"]
  }'
```

To query the results in addition to the SQL, use `["sql", "data"]` instead. SingleStore recommends this combination for developer and debugging workflows because it returns both the generated SQL and the executed results. Refer to [Aura Analyst API Reference](https://docs.singlestore.com/cloud/ai/aura-analyst/aura-analyst-api-reference.md) for more information.

## Structured Query Endpoint

To retrieve the generated SQL for a back-end integration, use the `POST /query` endpoint instead of the streaming chat endpoint. Set `output_modes` to `["sql"]` to return only the generated SQL or `["sql", "data"]` to return both the generated SQL and the executed results. For example (update the endpoint, the API key, and message before running the following command):

```shell
curl -X POST "https://apps.${REGION}.cloud.singlestore.com/v1/organizations/${ORG_ID}/projects/${PROJECT_ID}/analyst/query" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were the top 10 products by revenue last month?",
    "output_modes": ["sql"]
  }'
```

The generated SQL is returned in `results[].sql.command` in the response. Refer to [Aura Analyst API Reference](https://docs.singlestore.com/cloud/ai/aura-analyst/aura-analyst-api-reference.md) for more information.

## Related Topics

* [Aura Analyst](https://docs.singlestore.com/cloud/ai/aura-analyst.md)
* [Aura Analyst API Reference](https://docs.singlestore.com/cloud/ai/aura-analyst/aura-analyst-api-reference.md)

***

Modified at: July 16, 2026

Source: [/cloud/ai/aura-analyst/aura-analyst-api/](https://docs.singlestore.com/cloud/ai/aura-analyst/aura-analyst-api/)

(An index of the documentation is available at /llms.txt)