Aura Analyst API

Generate an API Key

To generate an API key for Analyst API:

1. On the Cloud Portal, 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.

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):

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):

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

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"]
  }'

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"]
  }'