From c2455daad29ca1ffe011c74010bb8822f850efbf Mon Sep 17 00:00:00 2001
From: Paula <paula.mihu@arangodb.com>
Date: Thu, 25 Sep 2025 14:52:32 +0200
Subject: [PATCH 01/10] initial draft

---
 .../reference/natural-language-to-aql.md      | 409 ++++++++++++------
 1 file changed, 274 insertions(+), 135 deletions(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index e73234d162..10825f2fa7 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -5,149 +5,264 @@ description: >-
   The Natural Language to AQL Translation Service is a powerful tool that allows
   you to interact with your ArangoDB database using natural language queries
 weight: 20
-draft: true # Not available in pre-release
 ---
 ## Overview
 
-This service translates your questions and commands into AQL (ArangoDB Query Language),
-executes the queries, and provides responses in natural language.
+The Natural Language to AQL Translation Service provides two distinct capabilities:
 
-## Features
+**1. [Process Text](#process-text)**: Ask general questions and get natural language responses without querying your database.
+Ideal for:
+- General knowledge questions  
+- Text analysis and processing
 
-- Natural language to AQL query translation
-- Support for multiple LLM providers (via OpenAI API or a self-hosted Triton Inference Server)
+**2. [Translate Query](#translate-query)**: Convert natural language questions into AQL queries and execute them against your ArangoDB database.
+Ideal for:
+- Querying your database using natural language
+- Converting business questions into database operations
+- Exploring data through intuitive interfaces
+- Learning AQL by seeing translations
+
+The Natural Language to AQL Translation Service also includes the following features:
+- Support for multiple LLM providers (via OpenAI API or a self-hosted Triton LLM host)
 - RESTful and gRPC interfaces
 - Health monitoring endpoints
-- Flexible output formats (Natural Language, AQL, JSON)
-
-## Getting Started
+- Flexible output formats (Natural Language, AQL, JSON) for database queries
 
-### Prerequisites
+## Prerequisites
 
 - ArangoDB instance
 - OpenAI API key (if using OpenAI as provider)
 - Triton URL and model name (if using Triton as provider)
 
+## Installation and configuration
+
+When creating the service, you provide parameters in the API request that become environment variables used at runtime.
+
+{{< tabs >}}
+
+{{< tab "Required Parameters" >}}
+These parameters must be provided in all service creation requests:
+
+- `username`: Database username for authentication
+- `db_name`: Name of the ArangoDB database  
+- `api_provider`: LLM provider selection (`openai` or `triton`)
+- `genai_project_name`: Name of the project created in Step 1
+{{< /tab >}}
 
-### Configuration
+{{< tab "OpenAI Provider" >}}
+Additional parameters required when using `api_provider: "openai"`:
 
-The following environment variables are set at installation time and used at runtime:
+- `openai_api_key`: API key for OpenAI authentication
+- `openai_model`: Model name (defaults to `gpt-3.5-turbo` if not specified)
+
+Optional OpenAI parameters:
+- `openai_temperature`: Controls randomness (0.0 to 2.0)
+- `openai_max_retries`: Maximum number of retry attempts
+{{< /tab >}}
+
+{{< tab "Triton Provider" >}}
+Additional parameters required when using `api_provider: "triton"`:
+
+- `triton_url`: URL of the Triton inference server
+- `triton_model`: Model name to use with Triton
+
+Optional Triton parameters:
+- `triton_timeout`: Timeout in seconds for Triton requests
+{{< /tab >}}
+
+{{< /tabs >}}
+
+### Step 1: Create a GenAI GraphRAG project
+
+The first step is to create a new project:
 
 ```bash
-# Required Database Configuration
-ARANGODB_NAME=<your_database_name>
-ARANGODB_USER=<your_username>
+curl --request POST \
+  --url https://arangodb-platform-dev.pilot.arangodb.com/gen-ai/v1/project \
+  --header 'Authorization: Bearer <your-bearer-token>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "project_name": "your-txt2aql-project",
+    "project_type": "graphrag",
+    "project_description": "Natural language to AQL translation project"
+  }'
+```
+
+**Expected Response:**
+```json
+{
+  "projectName": "your-txt2aql-project",
+  "projectType": "graphrag",
+  "projectDescription": "Natural language to AQL translation project"
+}
+```
+
+### Step 2: Create the GraphRAG txt2aql service
 
-# LLM Provider Configuration
-API_PROVIDER=<provider>                # "openai" or "triton"
+Create the service instance with your configuration:
 
-# If using OpenAI
-OPENAI_API_KEY=<your_api_key>
-OPENAI_MODEL=<model_name>              # Optional, defaults to GPT-4
-OPENAI_TEMPERATURE=<temperature>       # Optional
-OPENAI_MAX_RETRIES=<retries>           # Optional
+```bash
+curl --request POST \
+  --url https://arangodb-platform-dev.pilot.arangodb.com/gen-ai/v1/graphrag \
+  --header 'Authorization: Bearer <your-bearer-token>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "env": {
+      "username": "<your-username>",
+      "db_name": "<your_database_name>",
+      "api_provider": "<openai>",
+      "openai_api_key": "<your-openai-api-key>",
+      "openai_model": "<gpt-4o>",
+      "genai_project_name": "<your-txt2aql-project>"
+    }
+  }'
+```
 
-# If using Triton
-TRITON_URL=<triton_server_url>
-TRITON_MODEL=<model_name>
-TRITON_TIMEOUT=<timeout_seconds>       # Optional
+**Expected Response:**
+```json
+{
+  "serviceInfo": {
+    "serviceId": "arangodb-graph-rag-xxxxx",
+    "description": "Install complete",
+    "status": "DEPLOYED",
+    "namespace": "<arangodb>",
+    "values": "<eyJhcGlfcHJvdmlkZXIi>..."
+  }
+}
 ```
 
-### Starting the Service
+{{< info >}}
+Save the `serviceId` from the above response as you'll need it for subsequent API calls.
+{{< /info >}}
 
-To start the service, use AI service endpoint `CreateGraphRag`. Please refer to the documentation of AI service for more information on how to use it.
+### Step 3: Verify the service status
 
-### Required Parameters
+Check that the service is properly deployed:
 
-These parameters must be provided in the install request sent to AI service.
+```bash
+curl --request GET \
+  --url https://<ExternalEndpoint>:8529/gen-ai/v1/service/arangodb-graph-rag-<serviceID> \
+  --header 'Authorization: Bearer <your-bearer-token>'
+```
 
-- `username`: Database username for authentication
-- `db_name`: Name of the ArangoDB database
-- `api_provider`: LLM provider selection (`openai`, `triton`)
+**Expected Response:**
+```json
+{
+  "serviceInfo": {
+    "serviceId": "arangodb-graph-rag-<serviceID>",
+    "description": "Install complete",
+    "status": "DEPLOYED",
+    "namespace": "<arangodb>",
+    "values": "<eyJhcGlfcHJvdmlkZXIi>..."
+  }
+}
+```
 
-### Provider-Specific Required Parameters
+### Step 4: Health check
 
-#### OpenAI Provider
+Verify that the service is running and healthy:
 
-- `openai_api_key`: API key for OpenAI authentication
-- `openai_model`: Model name (defaults to "gpt-3.5-turbo" if not specified)
+```bash
+curl --request GET \
+  --url <ExternalEndpoint>:8529/graph-rag/<serviceID>/v1/health \
+  --header 'Authorization: Bearer <your-bearer-token>'
+```
 
-#### Triton Provider
+**Expected Response:**
+```json
+{
+  "status": "SERVING"
+}
+```
 
-- `triton_url`: URL of the Triton inference server
-- `triton_model`: Model name to use with Triton
+{{< info >}}
+The `serviceID` in the URL is typically the last part of the full service ID (e.g., `xxxxx` from `arangodb-graph-rag-xxxxx`).
+{{< /info >}}
 
-## API Reference
+## Process Text
+
+The **Process Text** endpoint allows you to ask general questions to the LLM and receive natural language responses. 
+
+```bash
+POST /v1/process_text
+```
 
-### REST Endpoints
-
-1. **Process Text** - Ask general questions to the LLM and get a natural language response. This endpoint does not query the database.
-   ```bash
-   POST /v1/process_text
-   Content-Type: application/json
- 
-   {
-     "input_text": "What are the advantages of graph databases?"
-   }
-   ```
-
-2. **Translate Query** - Convert natural language to AQL and query the database
-   ```bash
-   POST /v1/translate_query
-   Content-Type: application/json
-   
-   {
-     "input_text": "Find all users who are friends with John",
-     "options": {
-       "output_formats": ["NL", "AQL", "JSON"]
-     }
-   }
-   ```
-
-3. **Health Check** - Monitor service health
-   ```bash
-   GET /v1/health
-   ```
-
-### gRPC Endpoints
-
-The service also provides gRPC endpoints for more efficient communication:
-
-1. **Process Text**
-   ```bash
-   grpcurl -plaintext -d '{"input_text": "Hello world"}' \
-     localhost:9090 txt2aql.Txt2AqlService/ProcessText
-   ```
-
-2. **Translate Query**
-   ```bash
-   grpcurl -plaintext -d '{
-     "input_text": "Find all characters from House Stark",
-     "options": {
-       "output_formats": ["NL","AQL","JSON"]
-     }
-   }' localhost:9090 txt2aql.Txt2AqlService/TranslateQuery
-   ```
-
-3. **Health Check**
-   ```bash
-   grpcurl -plaintext localhost:9090 txt2aql.Txt2AqlService/HealthCheck
-   ```
-
-## Output Formats
-
-The `translate_query` endpoint of the txt2aql service supports multiple output formats that can be specified in the `output_formats` field of your request. Each format serves a different purpose and can be used individually or in combination:
-
-### Natural Language (NL)
+{{< info >}}
+**This endpoint does not query your database**, it is designed for general knowledge questions and text processing.
+{{< /info >}}
+
+**Example**:
+
+```json
+{
+  "input_text": "What are the advantages of graph databases?"
+}
+```
+
+```bash
+curl --request POST \
+  --url https://arangodb-platform-dev.pilot.arangodb.com/graph-rag/<serviceID>/v1/process_text \
+  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "input_text": "What are the advantages of graph databases?"
+  }'
+```
+
+**Expected output:**
+
+```json
+{
+  "responseText": "Graph databases offer several key advantages: 1) Efficient relationship handling - they store relationships as first-class citizens, making traversals much faster than traditional SQL JOINs. 2) Flexible data modeling - schema-less design accommodates evolving datasets naturally. 3) High performance for connected data - query performance remains consistent even with large datasets. 4) Intuitive visualization - relationships can be easily visualized and understood. 5) Real-time capabilities - excellent for recommendation systems, fraud detection, and network analysis."
+}
+```
+
+## Translate Query
+
+The **Translate Query** endpoint converts natural language questions into AQL queries and executes them against your ArangoDB database. **This endpoint queries your actual data** and returns results in multiple formats.
+
+```bash
+POST /v1/translate_query
+```
+
+**Example**:
+
+```json
+{
+  "input_text": "Find all users who are friends with John",
+  "options": {
+    "output_formats": ["NL", "AQL", "JSON"]
+  }
+}
+```
+
+```bash
+curl --request POST \
+  --url https://arangodb-platform-dev.pilot.arangodb.com/graph-rag/<serviceID>/v1/translate_query \
+  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "input_text": "Find all users who are friends with John",
+    "options": {
+      "output_formats": ["NL", "AQL", "JSON"]
+    }
+  }'
+```
+
+### Output formats
+
+The `translate_query` endpoint supports multiple output formats that can be specified in the `output_formats` field of your request. Each format serves a different purpose and can be used individually or in combination.
+
+#### Natural Language (NL)
 
 - **Format identifier**: `"NL"`
 - **Returns**: A human-readable explanation of the query results
-- **Helpful for**: Understanding what the query found in plain English
+- **Helpful for**: Understanding what the query found in plain English.
 - **Example**:
   - **Input**: `Find all users who are friends with John`
   - **Output**: `I found 3 users who are friends with John, including Alice, Bob, and Carol`
 
-### AQL Query (AQL)
+#### AQL Query (AQL)
 
 - **Format identifier**: `"AQL"`
 - **Returns**: The generated ArangoDB Query Language (AQL) query
@@ -155,16 +270,16 @@ The `translate_query` endpoint of the txt2aql service supports multiple output f
   - Debugging query translation
   - Learning AQL syntax
   - Modifying queries for reuse
-- **Shows**: Exactly how your natural language was translated into database operations
+- **Shows**: Exactly how your natural language was translated into database operations.
 - **Example**:
   - **Input**: `Find all users who are friends with John`
   - **Output**: `FOR u IN users FILTER u.friends ANY == 'John' RETURN u`
 
-### JSON Results (JSON)
+#### JSON Results (JSON)
 
 - **Format identifier**: `"JSON"`
 - **Returns**: The raw query results in JSON format
-- **Provides**: Direct access to the complete dataset
+- **Provides**: Direct access to the complete dataset.
 - **Ideal for**:
   - Programmatic processing
   - Data integration
@@ -173,7 +288,7 @@ The `translate_query` endpoint of the txt2aql service supports multiple output f
   - **Input**: `Find all users who are friends with John`
   - **Output**: `[{"name":"Alice","age":30},{"name":"Bob","age":25},{"name":"Carol","age":35}]`
 
-### Example Response
+#### Examples
 
 ```json
 {
@@ -184,18 +299,52 @@ The `translate_query` endpoint of the txt2aql service supports multiple output f
 }
 ```
 
-### Usage Tips
+#### Usage and default behavior
 
-1. Request only the formats you need to minimize response size and processing time
-2. Use `NL` for user interfaces, human consumption or when wrapped as an LLM-callable function (e.g. in LLM agent frameworks)
-3. Use `AQL` for debugging and learning purposes
-4. Use `JSON` for programmatic data processing such as API calls.
+- Request only the formats you need to minimize response size and processing time.
+- Use `NL` for user interfaces, human consumption, or when wrapped as an LLM-callable function (e.g., in LLM agent frameworks).
+- Use `AQL` for debugging and learning purposes.
+- Use `JSON` for programmatic data processing such as API calls.
+- If no output formats are specified, the service defaults to `NL` format only.
+- Multiple formats can be requested simultaneously.
+- Formats are processed efficiently, with results cached where possible.
 
-### Default Behavior
+## gRPC endpoints
 
-- If no output formats are specified, the service defaults to `NL` format only
-- Multiple formats can be requested simultaneously
-- Formats are processed efficiently, with results cached where possible
+The service also provides gRPC endpoints for more efficient communication.
+
+### Process Text (gRPC)
+
+```bash
+grpcurl -plaintext -d '{"input_text": "Hello world"}' \
+  localhost:9090 txt2aql.Txt2AqlService/ProcessText
+```
+
+### Translate Query (gRPC)
+
+```bash
+grpcurl -plaintext -d '{
+  "input_text": "Find all characters from House Stark",
+  "options": {
+    "output_formats": ["NL","AQL","JSON"]
+  }
+}' localhost:9090 txt2aql.Txt2AqlService/TranslateQuery
+```
+
+### Health check (gRPC)
+
+```bash
+grpcurl -plaintext localhost:9090 txt2aql.Txt2AqlService/HealthCheck
+```
+
+## Best Practices
+
+1. Be specific in your queries to get more accurate translations.
+2. Use appropriate output formats based on your needs.
+3. Monitor the health endpoint for service status.
+4. Implement proper error handling in your client applications.
+5. Use connection pooling for better performance.
+6. Consider rate limiting for production deployments.
 
 ## Error Handling
 
@@ -209,31 +358,21 @@ The service provides clear error messages for common issues:
 
 Error responses include appropriate HTTP status codes and descriptive messages.
 
-## Best Practices
-
-1. Be specific in your queries to get more accurate translations
-2. Use appropriate output formats based on your needs
-3. Monitor the health endpoint for service status
-4. Implement proper error handling in your client applications
-5. Use connection pooling for better performance
-6. Consider rate limiting for production deployments
-
 ## Troubleshooting
 
 Common issues and solutions:
 
-1. **Connection Issues**
-   - Verify ARANGODB_ENDPOINT is accessible
-   - Check network/firewall settings
-   - Ensure proper authentication credentials
+1. **Connection issues**:
+   - Verify that ARANGODB_ENDPOINT is accessible.
+   - Check network/firewall settings.
+   - Ensure proper authentication credentials.
 
-2. **Query Translation Issues**
-   - Make queries more specific
-   - Check LLM provider configuration
-   - Verify database schema matches query context
+2. **Query Translation issues**:
+   - Make queries more specific.
+   - Check LLM provider configuration.
+   - Verify that the database schema matches the query context.
    - The quality of the generated AQL may vary depending on the LLM model used.
-     Therefore we recommend using an AQL-capable coding model (e.g. a frontier AQL-capable
-     LLM or a fine-tuned AQL-capable coding model) for better results.
+     Therefore, it is recommended to use an AQL-capable coding model (e.g., a frontier AQL-capable LLM or a fine-tuned AQL-capable coding model) for better results.
 
 ## API Reference
 

From fa6cd5a7a3f95f4756eadf88a99fb5b58af15d17 Mon Sep 17 00:00:00 2001
From: Paula <paula.mihu@arangodb.com>
Date: Fri, 24 Oct 2025 15:43:22 +0200
Subject: [PATCH 02/10] add process-text-stream

---
 .../reference/natural-language-to-aql.md      | 40 ++++++++++++++++---
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index 10825f2fa7..f6ccdd7b45 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -1,19 +1,20 @@
 ---
-title: Natural Language to AQL Translation Service (txt2aql)
-menuTitle: txt2aql
+title: Natural Language to AQL Translation Service
+menuTitle: Natural Language to AQL
 description: >-
-  The Natural Language to AQL Translation Service is a powerful tool that allows
-  you to interact with your ArangoDB database using natural language queries
+  Query your ArangoDB database using natural language or get LLM-powered answers
+  to general questions
 weight: 20
 ---
 ## Overview
 
 The Natural Language to AQL Translation Service provides two distinct capabilities:
 
-**1. [Process Text](#process-text)**: Ask general questions and get natural language responses without querying your database.
+**1. [Process Text](#process-text)**: Ask general questions and get natural language responses without querying your database. Supports both standard and [streaming](#process-text-stream) responses.
 Ideal for:
 - General knowledge questions  
 - Text analysis and processing
+- Real-time response generation with streaming
 
 **2. [Translate Query](#translate-query)**: Convert natural language questions into AQL queries and execute them against your ArangoDB database.
 Ideal for:
@@ -217,6 +218,28 @@ curl --request POST \
 }
 ```
 
+### Process Text Stream
+
+The **Process Text Stream** endpoint works like Process Text but streams the response in chunks as they are generated, providing real-time output. This is useful for long-form responses where you want to show progressive results.
+
+```bash
+POST /v1/process_text_stream
+```
+
+**Example**:
+
+```bash
+curl --request POST \
+  --url https://arangodb-platform-dev.pilot.arangodb.com/graph-rag/<serviceID>/v1/process_text_stream \
+  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "input_text": "What are the advantages of graph databases?"
+  }'
+```
+
+The streaming endpoint accepts the same request format as the standard Process Text endpoint but returns the response incrementally as chunks.
+
 ## Translate Query
 
 The **Translate Query** endpoint converts natural language questions into AQL queries and executes them against your ArangoDB database. **This endpoint queries your actual data** and returns results in multiple formats.
@@ -320,6 +343,13 @@ grpcurl -plaintext -d '{"input_text": "Hello world"}' \
   localhost:9090 txt2aql.Txt2AqlService/ProcessText
 ```
 
+### Process Text Stream (gRPC)
+
+```bash
+grpcurl -plaintext -d '{"input_text": "What are the advantages of graph databases?"}' \
+  localhost:9090 txt2aql.Txt2AqlService/ProcessTextStream
+```
+
 ### Translate Query (gRPC)
 
 ```bash

From ec12eeb300d6bf8e332cb7182d476a0f9579bd60 Mon Sep 17 00:00:00 2001
From: Paula <paula.mihu@arangodb.com>
Date: Fri, 24 Oct 2025 15:52:47 +0200
Subject: [PATCH 03/10] add info box and placeholder for external endpoint URL

---
 .../ai-suite/reference/natural-language-to-aql.md  | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index f6ccdd7b45..a16ddea7ad 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -39,6 +39,10 @@ The Natural Language to AQL Translation Service also includes the following feat
 
 When creating the service, you provide parameters in the API request that become environment variables used at runtime.
 
+{{< info >}}
+Replace `<ExternalEndpoint>` in all examples below with your Arango Data Platform deployment URL.
+{{< /info >}}
+
 {{< tabs >}}
 
 {{< tab "Required Parameters" >}}
@@ -79,7 +83,7 @@ The first step is to create a new project:
 
 ```bash
 curl --request POST \
-  --url https://arangodb-platform-dev.pilot.arangodb.com/gen-ai/v1/project \
+  --url https://<ExternalEndpoint>:8529/ai-services/v1/project \
   --header 'Authorization: Bearer <your-bearer-token>' \
   --header 'Content-Type: application/json' \
   --data '{
@@ -104,7 +108,7 @@ Create the service instance with your configuration:
 
 ```bash
 curl --request POST \
-  --url https://arangodb-platform-dev.pilot.arangodb.com/gen-ai/v1/graphrag \
+  --url https://<ExternalEndpoint>:8529/ai-services/v1/graphrag \
   --header 'Authorization: Bearer <your-bearer-token>' \
   --header 'Content-Type: application/json' \
   --data '{
@@ -202,7 +206,7 @@ POST /v1/process_text
 
 ```bash
 curl --request POST \
-  --url https://arangodb-platform-dev.pilot.arangodb.com/graph-rag/<serviceID>/v1/process_text \
+  --url https://<ExternalEndpoint>:8529/graph-rag/<serviceID>/v1/process_text \
   --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   --header 'Content-Type: application/json' \
   --data '{
@@ -230,7 +234,7 @@ POST /v1/process_text_stream
 
 ```bash
 curl --request POST \
-  --url https://arangodb-platform-dev.pilot.arangodb.com/graph-rag/<serviceID>/v1/process_text_stream \
+  --url https://<ExternalEndpoint>:8529/graph-rag/<serviceID>/v1/process_text_stream \
   --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   --header 'Content-Type: application/json' \
   --data '{
@@ -261,7 +265,7 @@ POST /v1/translate_query
 
 ```bash
 curl --request POST \
-  --url https://arangodb-platform-dev.pilot.arangodb.com/graph-rag/<serviceID>/v1/translate_query \
+  --url https://<ExternalEndpoint>:8529/graph-rag/<serviceID>/v1/translate_query \
   --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   --header 'Content-Type: application/json' \
   --data '{

From 039456f4385d542d6a5b1ff273a909bd4e4cb749 Mon Sep 17 00:00:00 2001
From: Paula <paula.mihu@arangodb.com>
Date: Wed, 29 Oct 2025 10:40:02 +0100
Subject: [PATCH 04/10] clarify provider-specific parameters, add OpenRouter,
 genai project no longer needed, add aqlizer mode

---
 .../reference/natural-language-to-aql.md      | 112 +++++++++---------
 1 file changed, 54 insertions(+), 58 deletions(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index a16ddea7ad..366ec6a1b6 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -34,91 +34,86 @@ The Natural Language to AQL Translation Service also includes the following feat
 - ArangoDB instance
 - OpenAI API key (if using OpenAI as provider)
 - Triton URL and model name (if using Triton as provider)
-
-## Installation and configuration
-
-When creating the service, you provide parameters in the API request that become environment variables used at runtime.
+- Optional: OpenRouter API key (if using OpenRouter via OpenAI compatible endpoint)
 
 {{< info >}}
 Replace `<ExternalEndpoint>` in all examples below with your Arango Data Platform deployment URL.
 {{< /info >}}
 
-{{< tabs >}}
-
-{{< tab "Required Parameters" >}}
-These parameters must be provided in all service creation requests:
+## Installation and configuration
 
-- `username`: Database username for authentication
-- `db_name`: Name of the ArangoDB database  
-- `api_provider`: LLM provider selection (`openai` or `triton`)
-- `genai_project_name`: Name of the project created in Step 1
-{{< /tab >}}
+When creating the service, you provide parameters in the API request that become environment variables used at runtime.
 
-{{< tab "OpenAI Provider" >}}
-Additional parameters required when using `api_provider: "openai"`:
+```bash
+# Required Database Configuration
+ARANGODB_NAME=<your_database_name>
+ARANGODB_USER=<your_username>
+
+# LLM Provider Configuration (chat model only)
+CHAT_API_PROVIDER=<openai|triton>
+
+# If chat provider is OpenAI
+CHAT_API_KEY=<your_chat_api_key>
+CHAT_MODEL=<model_name>                # Optional, defaults to gpt-4o-mini (e.g., gpt-4o)
+CHAT_API_URL=<base_url>                # Optional, OpenAI‑compatible endpoint (e.g., https://openrouter.ai/api/v1)
+
+# If using Triton for chat
+CHAT_API_URL=<triton_server_url>
+CHAT_MODEL=<triton_chat_model>
+TRITON_TIMEOUT=<timeout_seconds>       # Optional
+```
 
-- `openai_api_key`: API key for OpenAI authentication
-- `openai_model`: Model name (defaults to `gpt-3.5-turbo` if not specified)
+### Provider-Specific Parameters
 
-Optional OpenAI parameters:
-- `openai_temperature`: Controls randomness (0.0 to 2.0)
-- `openai_max_retries`: Maximum number of retry attempts
-{{< /tab >}}
+#### OpenAI Provider (chat)
 
-{{< tab "Triton Provider" >}}
-Additional parameters required when using `api_provider: "triton"`:
+- `chat_api_key`: API key for OpenAI chat
+- `chat_model`: Chat model (optional; defaults to `gpt-4o-mini`, e.g., "gpt-4o")
+- `chat_api_url` (optional): Override base URL for OpenAI‑compatible endpoints. This enables using providers like OpenRouter by pointing to their endpoint.
+- `openai_temperature` (optional): Controls randomness (0.0 to 2.0).
+- `openai_max_retries` (optional): Maximum number of retry attempts.
 
-- `triton_url`: URL of the Triton inference server
-- `triton_model`: Model name to use with Triton
+#### OpenRouter (via OpenAI‑compatible endpoint)
 
-Optional Triton parameters:
-- `triton_timeout`: Timeout in seconds for Triton requests
-{{< /tab >}}
+OpenRouter is supported by setting the OpenAI‑compatible base URL and using your OpenRouter API key. This allows access to many upstream LLM providers through a single API.
 
-{{< /tabs >}}
+```bash
+# Choose the OpenAI-compatible provider
+CHAT_API_PROVIDER=openai
 
-### Step 1: Create a GenAI GraphRAG project
+# Use your OpenRouter API key
+CHAT_API_KEY=<your_openrouter_api_key>
 
-The first step is to create a new project:
+# Point to OpenRouter's endpoint
+CHAT_API_URL=https://openrouter.ai/api/v1
 
-```bash
-curl --request POST \
-  --url https://<ExternalEndpoint>:8529/ai-services/v1/project \
-  --header 'Authorization: Bearer <your-bearer-token>' \
-  --header 'Content-Type: application/json' \
-  --data '{
-    "project_name": "your-txt2aql-project",
-    "project_type": "graphrag",
-    "project_description": "Natural language to AQL translation project"
-  }'
+# Select any model ID available on OpenRouter
+# (see OpenRouter's model catalog for valid ids)
+CHAT_MODEL=<openrouter_model_id>
 ```
 
-**Expected Response:**
-```json
-{
-  "projectName": "your-txt2aql-project",
-  "projectType": "graphrag",
-  "projectDescription": "Natural language to AQL translation project"
-}
-```
+#### Triton Provider (chat)
+
+- `chat_api_url`: Triton URL for chat.
+- `chat_model`: Triton chat model.
+- `triton_timeout` (optional): Timeout in seconds for Triton requests.
 
-### Step 2: Create the GraphRAG txt2aql service
+### Start the service
 
 Create the service instance with your configuration:
 
 ```bash
 curl --request POST \
-  --url https://<ExternalEndpoint>:8529/ai-services/v1/graphrag \
+  --url https://<ExternalEndpoint>:8529/ai/v1/graphrag \
   --header 'Authorization: Bearer <your-bearer-token>' \
   --header 'Content-Type: application/json' \
   --data '{
     "env": {
       "username": "<your-username>",
       "db_name": "<your_database_name>",
-      "api_provider": "<openai>",
-      "openai_api_key": "<your-openai-api-key>",
-      "openai_model": "<gpt-4o>",
-      "genai_project_name": "<your-txt2aql-project>"
+      "chat_api_provider": "<openai>",
+      "chat_api_key": "<your-openai-api-key>",
+      "chat_model": "<gpt-4o>",
     }
   }'
 ```
@@ -140,7 +135,7 @@ curl --request POST \
 Save the `serviceId` from the above response as you'll need it for subsequent API calls.
 {{< /info >}}
 
-### Step 3: Verify the service status
+### Verify the service status
 
 Check that the service is properly deployed:
 
@@ -163,7 +158,7 @@ curl --request GET \
 }
 ```
 
-### Step 4: Health check
+### Health check
 
 Verify that the service is running and healthy:
 
@@ -222,7 +217,7 @@ curl --request POST \
 }
 ```
 
-### Process Text Stream
+## Process Text Stream
 
 The **Process Text Stream** endpoint works like Process Text but streams the response in chunks as they are generated, providing real-time output. This is useful for long-form responses where you want to show progressive results.
 
@@ -239,6 +234,7 @@ curl --request POST \
   --header 'Content-Type: application/json' \
   --data '{
     "input_text": "What are the advantages of graph databases?"
+    "mode": "aqlizer"
   }'
 ```
 

From 53c5c8232c4f1df345eeebc91cefbee81aec1f61 Mon Sep 17 00:00:00 2001
From: Paula <paula.mihu@arangodb.com>
Date: Wed, 29 Oct 2025 10:50:14 +0100
Subject: [PATCH 05/10] remove grpc (only internal use)

---
 .../reference/natural-language-to-aql.md      | 37 +------------------
 1 file changed, 1 insertion(+), 36 deletions(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index 366ec6a1b6..34b4e500a8 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -25,7 +25,7 @@ Ideal for:
 
 The Natural Language to AQL Translation Service also includes the following features:
 - Support for multiple LLM providers (via OpenAI API or a self-hosted Triton LLM host)
-- RESTful and gRPC interfaces
+- RESTful interfaces
 - Health monitoring endpoints
 - Flexible output formats (Natural Language, AQL, JSON) for database queries
 
@@ -332,41 +332,6 @@ The `translate_query` endpoint supports multiple output formats that can be spec
 - Multiple formats can be requested simultaneously.
 - Formats are processed efficiently, with results cached where possible.
 
-## gRPC endpoints
-
-The service also provides gRPC endpoints for more efficient communication.
-
-### Process Text (gRPC)
-
-```bash
-grpcurl -plaintext -d '{"input_text": "Hello world"}' \
-  localhost:9090 txt2aql.Txt2AqlService/ProcessText
-```
-
-### Process Text Stream (gRPC)
-
-```bash
-grpcurl -plaintext -d '{"input_text": "What are the advantages of graph databases?"}' \
-  localhost:9090 txt2aql.Txt2AqlService/ProcessTextStream
-```
-
-### Translate Query (gRPC)
-
-```bash
-grpcurl -plaintext -d '{
-  "input_text": "Find all characters from House Stark",
-  "options": {
-    "output_formats": ["NL","AQL","JSON"]
-  }
-}' localhost:9090 txt2aql.Txt2AqlService/TranslateQuery
-```
-
-### Health check (gRPC)
-
-```bash
-grpcurl -plaintext localhost:9090 txt2aql.Txt2AqlService/HealthCheck
-```
-
 ## Best Practices
 
 1. Be specific in your queries to get more accurate translations.

From 98cc5d4a9a21eef6ce0f38e3f67437437c2a1ebb Mon Sep 17 00:00:00 2001
From: Paula <paula.mihu@arangodb.com>
Date: Wed, 29 Oct 2025 13:32:10 +0100
Subject: [PATCH 06/10] remove triton

---
 .../reference/natural-language-to-aql.md      | 23 +++++--------------
 1 file changed, 6 insertions(+), 17 deletions(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index 34b4e500a8..a8dead7ad1 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -24,7 +24,7 @@ Ideal for:
 - Learning AQL by seeing translations
 
 The Natural Language to AQL Translation Service also includes the following features:
-- Support for multiple LLM providers (via OpenAI API or a self-hosted Triton LLM host)
+- Support for multiple LLM providers (via OpenAI API or a self-hosted OpenAI-compatible models)
 - RESTful interfaces
 - Health monitoring endpoints
 - Flexible output formats (Natural Language, AQL, JSON) for database queries
@@ -33,7 +33,6 @@ The Natural Language to AQL Translation Service also includes the following feat
 
 - ArangoDB instance
 - OpenAI API key (if using OpenAI as provider)
-- Triton URL and model name (if using Triton as provider)
 - Optional: OpenRouter API key (if using OpenRouter via OpenAI compatible endpoint)
 
 {{< info >}}
@@ -50,17 +49,13 @@ ARANGODB_NAME=<your_database_name>
 ARANGODB_USER=<your_username>
 
 # LLM Provider Configuration (chat model only)
-CHAT_API_PROVIDER=<openai|triton>
+CHAT_API_PROVIDER=<openai>
 
 # If chat provider is OpenAI
 CHAT_API_KEY=<your_chat_api_key>
 CHAT_MODEL=<model_name>                # Optional, defaults to gpt-4o-mini (e.g., gpt-4o)
 CHAT_API_URL=<base_url>                # Optional, OpenAI‑compatible endpoint (e.g., https://openrouter.ai/api/v1)
 
-# If using Triton for chat
-CHAT_API_URL=<triton_server_url>
-CHAT_MODEL=<triton_chat_model>
-TRITON_TIMEOUT=<timeout_seconds>       # Optional
 ```
 
 ### Provider-Specific Parameters
@@ -69,7 +64,7 @@ TRITON_TIMEOUT=<timeout_seconds>       # Optional
 
 - `chat_api_key`: API key for OpenAI chat
 - `chat_model`: Chat model (optional; defaults to `gpt-4o-mini`, e.g., "gpt-4o")
-- `chat_api_url` (optional): Override base URL for OpenAI‑compatible endpoints. This enables using providers like OpenRouter by pointing to their endpoint.
+- `chat_api_url` (optional): Override base URL for OpenAI‑compatible endpoints. This enables using providers like OpenRouter or self-hosted OpenAI-compatible models.
 - `openai_temperature` (optional): Controls randomness (0.0 to 2.0).
 - `openai_max_retries` (optional): Maximum number of retry attempts.
 
@@ -88,16 +83,10 @@ CHAT_API_KEY=<your_openrouter_api_key>
 CHAT_API_URL=https://openrouter.ai/api/v1
 
 # Select any model ID available on OpenRouter
-# (see OpenRouter's model catalog for valid ids)
+# (see OpenRouter's model catalog for valid IDs)
 CHAT_MODEL=<openrouter_model_id>
 ```
 
-#### Triton Provider (chat)
-
-- `chat_api_url`: Triton URL for chat.
-- `chat_model`: Triton chat model.
-- `triton_timeout` (optional): Timeout in seconds for Triton requests.
-
 ### Start the service
 
 Create the service instance with your configuration:
@@ -141,7 +130,7 @@ Check that the service is properly deployed:
 
 ```bash
 curl --request GET \
-  --url https://<ExternalEndpoint>:8529/gen-ai/v1/service/arangodb-graph-rag-<serviceID> \
+  --url https://<ExternalEndpoint>:8529/ai/v1/service/arangodb-graph-rag-<serviceID> \
   --header 'Authorization: Bearer <your-bearer-token>'
 ```
 
@@ -233,7 +222,7 @@ curl --request POST \
   --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   --header 'Content-Type: application/json' \
   --data '{
-    "input_text": "What are the advantages of graph databases?"
+    "input_text": "What are the advantages of graph databases?",
     "mode": "aqlizer"
   }'
 ```

From e79f82c338a5df6323d3c80986a18251f126a502 Mon Sep 17 00:00:00 2001
From: Paula <paula.mihu@arangodb.com>
Date: Mon, 3 Nov 2025 15:27:44 +0100
Subject: [PATCH 07/10] apply review suggestions

---
 .../reference/natural-language-to-aql.md      | 152 +++++++++++-------
 1 file changed, 96 insertions(+), 56 deletions(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index a8dead7ad1..c3dc3648b9 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -29,66 +29,34 @@ The Natural Language to AQL Translation Service also includes the following feat
 - Health monitoring endpoints
 - Flexible output formats (Natural Language, AQL, JSON) for database queries
 
-## Prerequisites
-
-- ArangoDB instance
-- OpenAI API key (if using OpenAI as provider)
-- Optional: OpenRouter API key (if using OpenRouter via OpenAI compatible endpoint)
-
-{{< info >}}
-Replace `<ExternalEndpoint>` in all examples below with your Arango Data Platform deployment URL.
-{{< /info >}}
-
 ## Installation and configuration
 
-When creating the service, you provide parameters in the API request that become environment variables used at runtime.
-
-```bash
-# Required Database Configuration
-ARANGODB_NAME=<your_database_name>
-ARANGODB_USER=<your_username>
-
-# LLM Provider Configuration (chat model only)
-CHAT_API_PROVIDER=<openai>
+Deploy the Natural Language to AQL service with a single API call. You provide configuration parameters in the request, and the platform automatically configures them as environment variables for the service runtime.
 
-# If chat provider is OpenAI
-CHAT_API_KEY=<your_chat_api_key>
-CHAT_MODEL=<model_name>                # Optional, defaults to gpt-4o-mini (e.g., gpt-4o)
-CHAT_API_URL=<base_url>                # Optional, OpenAI‑compatible endpoint (e.g., https://openrouter.ai/api/v1)
-
-```
+### Prerequisites
 
-### Provider-Specific Parameters
+Before deploying, have ready:
+- An ArangoDB instance with database name and username credentials
+- An API key from your chosen LLM provider (OpenAI, OpenRouter, or other OpenAI-compatible service)
+- A Bearer token for API authentication
 
-#### OpenAI Provider (chat)
+### Obtaining a Bearer Token
 
-- `chat_api_key`: API key for OpenAI chat
-- `chat_model`: Chat model (optional; defaults to `gpt-4o-mini`, e.g., "gpt-4o")
-- `chat_api_url` (optional): Override base URL for OpenAI‑compatible endpoints. This enables using providers like OpenRouter or self-hosted OpenAI-compatible models.
-- `openai_temperature` (optional): Controls randomness (0.0 to 2.0).
-- `openai_max_retries` (optional): Maximum number of retry attempts.
-
-#### OpenRouter (via OpenAI‑compatible endpoint)
-
-OpenRouter is supported by setting the OpenAI‑compatible base URL and using your OpenRouter API key. This allows access to many upstream LLM providers through a single API.
+Before you can deploy the service, you need to obtain a Bearer token for authentication. Generate this token using the ArangoDB authentication API:
 
 ```bash
-# Choose the OpenAI-compatible provider
-CHAT_API_PROVIDER=openai
-
-# Use your OpenRouter API key
-CHAT_API_KEY=<your_openrouter_api_key>
-
-# Point to OpenRouter's endpoint
-CHAT_API_URL=https://openrouter.ai/api/v1
-
-# Select any model ID available on OpenRouter
-# (see OpenRouter's model catalog for valid IDs)
-CHAT_MODEL=<openrouter_model_id>
+curl -X POST https://<ExternalEndpoint>:8529/_open/auth \
+  -d '{"username": "your-username", "password": "your-password"}'
 ```
 
+This returns a JWT token that you can use as your Bearer token in all subsequent API calls. For more details, see the [ArangoDB Authentication](../../../develop/http-api/authentication/#jwt-user-tokens) documentation.
+
 ### Start the service
 
+{{< info >}}
+Replace `<ExternalEndpoint>` in all examples below with your Arango Data Platform deployment URL.
+{{< /info >}}
+
 Create the service instance with your configuration:
 
 ```bash
@@ -98,7 +66,6 @@ curl --request POST \
   --header 'Content-Type: application/json' \
   --data '{
     "env": {
-      "username": "<your-username>",
       "db_name": "<your_database_name>",
       "chat_api_provider": "<openai>",
       "chat_api_key": "<your-openai-api-key>",
@@ -121,10 +88,45 @@ curl --request POST \
 ```
 
 {{< info >}}
-Save the `serviceId` from the above response as you'll need it for subsequent API calls.
+Save the `serviceId` from the above response as you will need it for all subsequent API calls.
 {{< /info >}}
 
-### Verify the service status
+### Configuration Parameters
+
+All parameters are provided in the `env` object of your deployment request.
+
+You can use OpenAI directly, or OpenAI-compatible services like OpenRouter or self-hosted models.
+
+**Required:**
+- `db_name`: Database name
+- `chat_api_provider`: Set to `openai` (supports OpenAI and OpenAI-compatible services)
+- `chat_api_key`: Your LLM provider API key
+
+**Optional:**
+- `chat_model`: Model name (default: `gpt-4o-mini`)
+- `chat_api_url`: Base URL for OpenAI-compatible endpoints (only needed for OpenRouter, self-hosted models, etc.)
+- `openai_max_retries`: Maximum retry attempts for failed requests
+
+#### Using OpenAI
+
+The [deployment example](#start-the-service) above uses OpenAI directly. Simply provide your OpenAI API key as `chat_api_key`.
+
+#### Using OpenRouter
+
+OpenRouter provides access to multiple LLM providers through an OpenAI-compatible API. To use it:
+- Set `chat_api_provider` to `openai` (same as above)
+- Set `chat_api_url` to `https://openrouter.ai/api/v1`
+- Use your OpenRouter API key as `chat_api_key`
+- Choose any model from [OpenRouter's catalog](https://openrouter.ai/models)
+
+#### Using Self-Hosted Models
+
+For self-hosted OpenAI-compatible models:
+- Set `chat_api_provider` to `openai`
+- Set `chat_api_url` to your model's endpoint
+- Configure `chat_api_key` according to your setup
+
+### Verify service status
 
 Check that the service is properly deployed:
 
@@ -208,12 +210,18 @@ curl --request POST \
 
 ## Process Text Stream
 
-The **Process Text Stream** endpoint works like Process Text but streams the response in chunks as they are generated, providing real-time output. This is useful for long-form responses where you want to show progressive results.
+The **Process Text Stream** endpoint returns responses in real-time as they are generated, rather than waiting for the complete response, which is useful for showing progressive output.
 
 ```bash
 POST /v1/process_text_stream
 ```
 
+The endpoint supports two modes described below.
+
+### Default Mode (General Text Processing)
+
+The default mode provides general LLM responses without querying your database.
+
 **Example**:
 
 ```bash
@@ -222,12 +230,44 @@ curl --request POST \
   --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
   --header 'Content-Type: application/json' \
   --data '{
-    "input_text": "What are the advantages of graph databases?",
+    "input_text": "What are the advantages of graph databases?"
+  }'
+```
+
+**Response:**
+```
+Graph databases offer several key advantages: 1) Efficient relationship handling...
+```
+
+{{< info >}}
+This mode does not access your database, it provides general knowledge responses.
+{{< /info >}}
+
+### AQLizer Mode
+
+The AQLizer mode converts natural language questions into AQL queries by streaming responses from an LLM that has knowledge of your database schema.
+
+**Example:**
+
+```bash
+curl --request POST \
+  --url https://<ExternalEndpoint>:8529/graph-rag/<serviceID>/v1/process_text_stream \
+  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "input_text": "Find all users who made purchases in the last month",
     "mode": "aqlizer"
   }'
 ```
 
-The streaming endpoint accepts the same request format as the standard Process Text endpoint but returns the response incrementally as chunks.
+**Response:**
+```aql
+FOR user IN users
+  FILTER user.purchases[*].date ANY >= DATE_SUBTRACT(DATE_NOW(), 1, 'month')
+  RETURN user
+```
+
+The generated AQL is based on your actual database schema, making it immediately usable.
 
 ## Translate Query
 
@@ -334,7 +374,7 @@ The `translate_query` endpoint supports multiple output formats that can be spec
 
 The service provides clear error messages for common issues:
 
-- Invalid or missing environment variables
+- Invalid or missing configuration parameters
 - Database connection failures
 - Authentication errors
 - Invalid query formats
@@ -347,7 +387,7 @@ Error responses include appropriate HTTP status codes and descriptive messages.
 Common issues and solutions:
 
 1. **Connection issues**:
-   - Verify that ARANGODB_ENDPOINT is accessible.
+   - Verify that the ArangoDB endpoint is accessible.
    - Check network/firewall settings.
    - Ensure proper authentication credentials.
 

From d36af5bf95f5d32dfb1e898593aa636c09d904df Mon Sep 17 00:00:00 2001
From: Paula Mihu <97217318+nerpaula@users.noreply.github.com>
Date: Tue, 4 Nov 2025 17:42:49 +0100
Subject: [PATCH 08/10] apply suggestion

Co-authored-by: maxkernbach <maximilian.kernbach@gmail.com>
---
 site/content/ai-suite/reference/natural-language-to-aql.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index c3dc3648b9..236bd6d562 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -245,7 +245,7 @@ This mode does not access your database, it provides general knowledge responses
 
 ### AQLizer Mode
 
-The AQLizer mode converts natural language questions into AQL queries by streaming responses from an LLM that has knowledge of your database schema.
+The AQLizer mode generates schema-aware AQL queries from natural language by streaming responses from an LLM.
 
 **Example:**
 

From 3daa94176072967ddc430e120e9ff9e4a75b391a Mon Sep 17 00:00:00 2001
From: Simran Spiller <simran@arangodb.com>
Date: Tue, 4 Nov 2025 21:49:45 +0100
Subject: [PATCH 09/10] Fix link

---
 site/content/ai-suite/reference/natural-language-to-aql.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index 236bd6d562..170ab00ddd 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -49,7 +49,7 @@ curl -X POST https://<ExternalEndpoint>:8529/_open/auth \
   -d '{"username": "your-username", "password": "your-password"}'
 ```
 
-This returns a JWT token that you can use as your Bearer token in all subsequent API calls. For more details, see the [ArangoDB Authentication](../../../develop/http-api/authentication/#jwt-user-tokens) documentation.
+This returns a JWT token that you can use as your Bearer token in all subsequent API calls. For more details, see the [ArangoDB Authentication](../../arangodb/3.12/develop/http-api/authentication.md/#jwt-user-tokens) documentation.
 
 ### Start the service
 

From cfde74f99e2c465ace936a12436f7369f80fd9ba Mon Sep 17 00:00:00 2001
From: Paula Mihu <97217318+nerpaula@users.noreply.github.com>
Date: Wed, 5 Nov 2025 16:53:23 +0100
Subject: [PATCH 10/10] add missing https prefix in curl example URL

---
 site/content/ai-suite/reference/natural-language-to-aql.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/content/ai-suite/reference/natural-language-to-aql.md b/site/content/ai-suite/reference/natural-language-to-aql.md
index 170ab00ddd..2160ce0460 100644
--- a/site/content/ai-suite/reference/natural-language-to-aql.md
+++ b/site/content/ai-suite/reference/natural-language-to-aql.md
@@ -155,7 +155,7 @@ Verify that the service is running and healthy:
 
 ```bash
 curl --request GET \
-  --url <ExternalEndpoint>:8529/graph-rag/<serviceID>/v1/health \
+  --url https://<ExternalEndpoint>:8529/graph-rag/<serviceID>/v1/health \
   --header 'Authorization: Bearer <your-bearer-token>'
 ```