Update docs with v2 version of execute program api (#173)

## Description 📝
This pull request introduces significant updates to the documentation
for the Execute Program API, focusing on adding support for multiple API
versions, improving structure, and enhancing clarity. Key changes
include the introduction of API versioning (v1 and v2), detailed request
and response specifications for each version, and additional guidance on
DDN authentication and build selection.

## Quick Links 🚀
-
https://rakesh-pql-606-update-docs-w.promptql-docs.pages.dev/promptql-apis/execute-program-api/
<!-- Links to the relevant place(s) in the CloudFlare Pages build. Wait
for CF comment for link. -->

## Assertion Tests 🤖

<!-- Add assertions between the comments below to have ChatGPT check the
quality of your docs contribution (Diff) and
how well it integrates with existing docs. E.g., A user should be able
to easily understand how to make a simple
query. -->

<!-- For more info, see the Action's docs in the marketplace:
https://github.com/marketplace/actions/docs-assertion-tester#usage -->

<!-- DX:Assertion-start -->
<!-- DX:Assertion-end -->

Author: rakeshkky

docs/promptql-apis/execute-program-api.mdx

@@ -10,6 +10,8 @@ toc_max_heading_level: 4
 ---
 
 import Thumbnail from "@site/src/components/Thumbnail";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 # Execute Program API
 
@@ -101,8 +103,6 @@ As you add your own custom business logic, you're providing more specific tools
 
 Execute a PromptQL program with your data.
 
-### Request
-
 `POST https://promptql.ddn.hasura.app/api/execute_program`
 
 :::note Private DDN Endpoint
@@ -116,16 +116,40 @@ by the control plane. For example:
 
 :::
 
-**Headers**
+### API Versions
+
+The Execute Program API supports two versions:
+
+- **Version 1 (v1)**: Uses direct DDN URL configuration with optional LLM settings
+- **Version 2 (v2)**: Uses DDN build-based configuration with settings from build metadata
+
+## Request Specifications
+
+<Tabs groupId="api-version" className="api-tabs">
+<TabItem value="v1" label="Version 1">
+
+### Request
+
+#### Headers
 
 ```
 Content-Type: application/json
+Authorization: Bearer <your-promptql-api-key>
 ```
 
-**Request Body**
+:::info Authentication
+
+Version 1 requests support both the `Authorization` header (recommended) and the deprecated `promptql_api_key` field in
+the request body. For new implementations, use the `Authorization` header with the `Bearer <your-promptql-api-key>`
+token format.
+
+:::
+
+#### Request Body
 
 ```json
 {
+  "version": "v1",
   "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
   "promptql_api_key": "<YOUR_API_KEY_HERE>",
   "ai_primitives_llm": {
@@ -139,17 +163,20 @@ Content-Type: application/json
 }
 ```
 
-**Request Body Fields**
+#### Request Body Fields
 
 | Field               | Type   | Required | Description                                              |
 | ------------------- | ------ | -------- | -------------------------------------------------------- |
+| `version`           | string | No       | Optional, must be "v1" for version 1 requests            |
 | `code`              | string | Yes      | The PromptQL program code to execute                     |
-| `promptql_api_key`  | string | Yes      | PromptQL API key created from project settings           |
+| `promptql_api_key`  | string | No\*     | PromptQL API key (deprecated, use Authorization header)  |
 | `ai_primitives_llm` | object | Yes      | Configuration for the AI primitives LLM provider         |
 | `ddn`               | object | Yes      | DDN configuration including URL and headers              |
 | `artifacts`         | array  | Yes      | List of artifacts to provide as context or initial state |
 
-**LLM Provider Options**
+\*Required if not using Authorization header
+
+#### LLM Provider Options
 
 The `ai_primitives_llm` field supports the following providers:
 
@@ -179,7 +206,134 @@ The `ai_primitives_llm` field supports the following providers:
 }
 ```
 
-**Artifacts**
+#### Artifacts
+
+The `artifacts` array can contain both text and table artifacts:
+
+1. Text Artifact:
+
+```json
+{
+  "identifier": "my_text",
+  "title": "My Text Document",
+  "artifact_type": "text",
+  "data": "Text content here"
+}
+```
+
+2. Table Artifact:
+
+```json
+{
+  "identifier": "my_table",
+  "title": "My Data Table",
+  "artifact_type": "table",
+  "data": [
+    {
+      "column1": "value1",
+      "column2": "value2"
+    }
+  ]
+}
+```
+
+#### Request DDN Auth
+
+The `ddn.headers` field can be used to pass any auth header information through to DDN. Read more about
+[auth with these APIs](/promptql-apis/auth.mdx).
+
+</TabItem>
+<TabItem value="v2" label="Version 2">
+
+### Request
+
+Version 2 requests use supergraph build versions instead of direct DDN URLs. The `build_version` refers to the version
+of supergraph builds created in your DDN project. Users can view build details in the DDN console or fetch information
+using the [`ddn supergraph build get`](/reference/cli/commands/ddn_supergraph_build_get) command.
+
+When `build_version` is not specified in the request, the project's applied build is automatically chosen. This allows
+you to use the currently deployed build without needing to specify its version explicitly.
+
+#### Headers
+
+```
+Content-Type: application/json
+Authorization: Bearer <your-promptql-api-key>
+```
+
+:::info Authentication
+
+Version 2 requests require the PromptQL API key to be sent as a Bearer token in the Authorization header.
+
+:::
+
+#### Request Body
+
+```json
+{
+  "version": "v2",
+  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
+  "ddn": {
+    "build_version": "505331f4b2",
+    "headers": {}
+  },
+  "artifacts": []
+}
+```
+
+**Example using applied build (without specifying build_version):**
+
+```json
+{
+  "version": "v2",
+  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
+  "ddn": {
+    "headers": {}
+  },
+  "artifacts": []
+}
+```
+
+**Example using build_id instead of build_version:**
+
+```json
+{
+  "version": "v2",
+  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
+  "ddn": {
+    "build_id": "8ac7ccd4-7502-44d5-b2ee-ea9639b1f653",
+    "headers": {}
+  },
+  "artifacts": []
+}
+```
+
+#### Request Body Fields
+
+| Field       | Type   | Required | Description                                              |
+| ----------- | ------ | -------- | -------------------------------------------------------- |
+| `version`   | string | Yes      | Must be "v2" for version 2 requests                      |
+| `code`      | string | Yes      | The PromptQL program code to execute                     |
+| `ddn`       | object | No       | DDN configuration for build selection and headers        |
+| `artifacts` | array  | No       | List of artifacts to provide as context or initial state |
+
+#### DDN Configuration Fields
+
+| Field           | Type   | Required | Description                                                |
+| --------------- | ------ | -------- | ---------------------------------------------------------- |
+| `build_id`      | string | No       | UUID of the DDN build. Cannot be used with `build_version` |
+| `build_version` | string | No       | Version of the DDN build. Cannot be used with `build_id`   |
+| `headers`       | object | No       | HTTP headers that should be forwarded to DDN               |
+
+:::note Build Selection
+
+- If both `build_id` and `build_version` are omitted, the project's applied build is automatically used
+- You can specify either `build_id` OR `build_version`, but not both simultaneously
+- The `build_version` refers to supergraph build versions created in your DDN project
+
+:::
+
+#### Artifacts
 
 The `artifacts` array can contain both text and table artifacts:
 
@@ -215,7 +369,10 @@ The `artifacts` array can contain both text and table artifacts:
 The `ddn.headers` field can be used to pass any auth header information through to DDN. Read more about
 [auth with these APIs](/promptql-apis/auth.mdx).
 
-### Response
+</TabItem>
+</Tabs>
+
+## Response
 
 ```json
 {
@@ -246,7 +403,7 @@ The `ddn.headers` field can be used to pass any auth header information through
 }
 ```
 
-### Response Fields
+## Response Fields
 
 | Field                   | Type         | Description                                                      |
 | ----------------------- | ------------ | ---------------------------------------------------------------- |
@@ -256,7 +413,7 @@ The `ddn.headers` field can be used to pass any auth header information through
 | `modified_artifacts`    | array        | List of artifacts that were created or modified during execution |
 | `llm_usages`            | array        | Details about LLM usage during execution                         |
 
-**LLM Usage Fields**
+### LLM Usage Fields
 
 | Field           | Type    | Description                                                   |
 | --------------- | ------- | ------------------------------------------------------------- |
@@ -265,7 +422,7 @@ The `ddn.headers` field can be used to pass any auth header information through
 | `input_tokens`  | integer | Number of input tokens consumed                               |
 | `output_tokens` | integer | Number of output tokens generated                             |
 
-### Error Response
+## Error Response
 
 When the API encounters an error, it will return a 422 status code with a validation error response:
 
@@ -281,20 +438,84 @@ When the API encounters an error, it will return a 422 status code with a valida
 }
 ```
 
+## DDN Authentication
+
+Both API versions support passing authentication headers to DDN through the `ddn.headers` field.
+
+<Tabs groupId="api-version" className="api-tabs">
+<TabItem value="v1" label="Version 1">
+
+Configure headers in the `ddn.headers` object:
+
+```json
+{
+  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
+  "ddn": {
+    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
+    "headers": {
+      "x-hasura-ddn-token": "<YOUR_DDN_AUTH_TOKEN>"
+    }
+  }
+}
+```
+
+</TabItem>
+<TabItem value="v2" label="Version 2">
+
+Configure headers in the `ddn.headers` object:
+
+```json
+{
+  "version": "v2",
+  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
+  "ddn": {
+    "build_version": "505331f4b2",
+    "headers": {
+      "x-hasura-ddn-token": "<YOUR_DDN_AUTH_TOKEN>"
+    }
+  }
+}
+```
+
+**Using applied build:**
+
+```json
+{
+  "version": "v2",
+  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
+  "ddn": {
+    "headers": {
+      "x-hasura-ddn-token": "<YOUR_DDN_AUTH_TOKEN>"
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+Read more about [auth with these APIs](/promptql-apis/auth.mdx).
+
 ## Notes for using the Execute Program API
 
 1. **Program Code**
 
    - Ensure your PromptQL program code is properly formatted and tested
    - You can export working programs from the PromptQL playground using the "Export as API" button
 
-2. **Artifacts**
+2. **Build Selection (Version 2)**
+
+   - When using v2, you can specify either `build_id` or `build_version`, but not both
+   - If neither is specified, the project's applied build is automatically used
+
+3. **Artifacts**
 
    - Provide all necessary artifacts that your program needs to run
    - Make sure artifact identifiers match those referenced in your program code
    - Both text and table artifacts are supported
 
-3. **Error Handling**
+4. **Error Handling**
+
    - Always check the error field in the response
    - Implement appropriate retry logic for transient failures
    - Validate your inputs against the API schema to catch issues early