From 3d0502017556a92ea9e4245f1be5d30afd91e80f Mon Sep 17 00:00:00 2001 From: sarthak Date: Fri, 3 Apr 2026 17:20:00 +0530 Subject: [PATCH 1/9] persona apis --- src/lib/api-navigation.ts | 30 ++++ src/lib/navigation.ts | 10 ++ src/pages/docs/api/personas/createpersona.mdx | 159 ++++++++++++++++++ src/pages/docs/api/personas/deletepersona.mdx | 98 +++++++++++ .../docs/api/personas/duplicatepersona.mdx | 126 ++++++++++++++ src/pages/docs/api/personas/listpersonas.mdx | 122 ++++++++++++++ src/pages/docs/api/personas/updatepersona.mdx | 152 +++++++++++++++++ 7 files changed, 697 insertions(+) create mode 100644 src/pages/docs/api/personas/createpersona.mdx create mode 100644 src/pages/docs/api/personas/deletepersona.mdx create mode 100644 src/pages/docs/api/personas/duplicatepersona.mdx create mode 100644 src/pages/docs/api/personas/listpersonas.mdx create mode 100644 src/pages/docs/api/personas/updatepersona.mdx diff --git a/src/lib/api-navigation.ts b/src/lib/api-navigation.ts index 68b56675..1a6ba9f3 100644 --- a/src/lib/api-navigation.ts +++ b/src/lib/api-navigation.ts @@ -69,6 +69,36 @@ export const apiNavigation: ApiNavGroup[] = [ } ] }, + { + "title": "Personas", + "items": [ + { + "title": "List personas", + "href": "/docs/api/personas/listpersonas", + "method": "GET" + }, + { + "title": "Create persona", + "href": "/docs/api/personas/createpersona", + "method": "POST" + }, + { + "title": "Update persona", + "href": "/docs/api/personas/updatepersona", + "method": "PATCH" + }, + { + "title": "Delete persona", + "href": "/docs/api/personas/deletepersona", + "method": "DELETE" + }, + { + "title": "Duplicate persona", + "href": "/docs/api/personas/duplicatepersona", + "method": "POST" + } + ] + }, { "title": "Agent Definitions", "items": [ diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index bd1c4638..8eb40797 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -928,6 +928,16 @@ export const tabNavigation: NavTab[] = [ { title: 'Add Empty Rows', href: '/docs/api/scenarios/addemptyrowstodataset' }, ] }, + { + title: 'Personas', + items: [ + { title: 'List Personas', href: '/docs/api/personas/listpersonas' }, + { title: 'Create Persona', href: '/docs/api/personas/createpersona' }, + { title: 'Update Persona', href: '/docs/api/personas/updatepersona' }, + { title: 'Delete Persona', href: '/docs/api/personas/deletepersona' }, + { title: 'Duplicate Persona', href: '/docs/api/personas/duplicatepersona' }, + ] + }, { title: 'Agent Definitions', items: [ diff --git a/src/pages/docs/api/personas/createpersona.mdx b/src/pages/docs/api/personas/createpersona.mdx new file mode 100644 index 00000000..92c04e1d --- /dev/null +++ b/src/pages/docs/api/personas/createpersona.mdx @@ -0,0 +1,159 @@ +--- +title: "Create persona" +description: "Creates a new workspace-level persona with configurable attributes for voice or chat simulation testing." +--- + +# Create persona + +Creates a new workspace-level persona. The persona name must be unique within the workspace and must not conflict with system persona names. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Persona name. Max 255 chars. Must be unique in workspace and across system personas (case-insensitive). | +| `description` | string | Yes | Non-empty description of the persona. | +| `simulationType` | string | No | `voice` or `chat`. Default: `voice`. | +| `gender` | array | No | Values: `male`, `female`. | +| `ageGroup` | array | No | Values: `18-25`, `25-32`, `32-40`, `40-50`, `50-60`, `60+`. | +| `location` | array | No | Values: `United States`, `Canada`, `United Kingdom`, `Australia`, `India`. | +| `profession` | array | No | Values: `Student`, `Teacher`, `Engineer`, `Doctor`, `Nurse`, `Business Owner`, `Manager`, `Sales Representative`, `Customer Service`, `Technician`, `Consultant`, `Accountant`, `Marketing Professional`, `Retired`, `Homemaker`, `Freelancer`, `Other`. | +| `personality` | array | No | Values: `Friendly and cooperative`, `Professional and formal`, `Cautious and skeptical`, `Impatient and direct`, `Detail-oriented`, `Easy-going`, `Anxious`, `Confident`, `Analytical`, `Emotional`, `Reserved`, `Talkative`. | +| `communicationStyle` | array | No | Values: `Direct and concise`, `Detailed and elaborate`, `Casual and friendly`, `Formal and polite`, `Technical`, `Simple and clear`, `Questioning`, `Assertive`, `Passive`, `Collaborative`. | +| `accent` | array | No | Values: `American`, `Australian`, `Indian`, `Canadian`, `Neutral`. | +| `multilingual` | boolean | No | Multi-language support. Default: `false`. | +| `language` | array | Conditional | Values: `English`, `Hindi`. Required if `multilingual` is `true`. | +| `conversationSpeed` | array | No | Values: `0.5`, `0.75`, `1.0`, `1.25`, `1.5`. | +| `backgroundSound` | boolean | No | Include background sounds. | +| `finishedSpeakingSensitivity` | array | No | Integers `1` to `10`. | +| `interruptSensitivity` | array | No | Integers `1` to `10`. | +| `keywords` | array | No | Keywords for the persona. | +| `customProperties` | object | No | Key-value metadata. Keys and values must be non-empty strings. | +| `additionalInstruction` | string | No | Extra behavioral instructions. | +| `tone` | string | No | `formal`, `casual`, `neutral`. Default: `casual`. | +| `punctuation` | string | No | `clean`, `minimal`, `expressive`, `erratic`. Default: `clean`. | +| `slangUsage` | string | No | `none`, `moderate`, `heavy`, `light`. Default: `light`. | +| `typosFrequency` | string | No | `none`, `rare`, `occasional`, `frequent`. Default: `rare`. | +| `regionalMix` | string | No | `none`, `moderate`, `heavy`, `light`. Default: `light`. | +| `emojiUsage` | string | No | `never`, `light`, `regular`, `heavy`. Default: `light`. | +| `verbosity` | string | No | `brief`, `balanced`, `detailed`. Default: `balanced`. | + +### Example + +```json +{ + "name": "Skeptical Customer", + "description": "A cautious customer who asks many questions before making decisions", + "gender": ["female"], + "ageGroup": ["32-40"], + "personality": ["Cautious and skeptical", "Detail-oriented"], + "communicationStyle": ["Questioning"], + "accent": ["American"], + "simulationType": "voice", + "tone": "formal", + "verbosity": "detailed" +} +``` + +## Responses + +### 201 + +Persona created successfully. + +- **status**: string +- **result**: object + The full persona object including generated `id`, `persona_type` (`workspace`), and all attributes. + +### 400 + +Bad Request. Possible reasons: +- Missing required fields (`name`, `description`). +- Duplicate persona name in workspace or system personas. +- `multilingual` is `true` but no `language` provided. +- Invalid choice values for any field. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/api/personas/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "Skeptical Customer", "description": "A cautious customer who asks many questions", "gender": ["female"], "ageGroup": ["32-40"], "personality": ["Cautious and skeptical"], "simulationType": "voice"}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/api/personas/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "name": "Skeptical Customer", + "description": "A cautious customer who asks many questions", + "gender": ["female"], + "ageGroup": ["32-40"], + "personality": ["Cautious and skeptical"], + "simulationType": "voice" +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/api/personas/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "name": "Skeptical Customer", + "description": "A cautious customer who asks many questions", + "gender": ["female"], + "ageGroup": ["32-40"], + "personality": ["Cautious and skeptical"], + "simulationType": "voice" + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/personas/deletepersona.mdx b/src/pages/docs/api/personas/deletepersona.mdx new file mode 100644 index 00000000..f7351789 --- /dev/null +++ b/src/pages/docs/api/personas/deletepersona.mdx @@ -0,0 +1,98 @@ +--- +title: "Delete persona" +description: "Soft-deletes a workspace-level persona. System personas cannot be deleted." +--- + +# Delete persona + +Soft-deletes a workspace-level persona. The persona is marked as deleted and excluded from future listings. System (prebuilt) personas cannot be deleted. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `persona_id` | string (UUID) | Yes | The UUID of the persona to delete. | + +## Responses + +### 204 + +Persona deleted successfully. + +- **status**: string +- **result**: object + - **message**: string + Example: `Persona deleted successfully` + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 403 + +Forbidden. System-level personas cannot be deleted. + +### 404 + +Not Found. The persona with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X DELETE "https://api.futureagi.com/simulate/api/personas/{persona_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/api/personas/{persona_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.delete(url, headers=headers) +print(response.status_code) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/api/personas/{persona_id}/", { + method: "DELETE", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +console.log(response.status); +``` diff --git a/src/pages/docs/api/personas/duplicatepersona.mdx b/src/pages/docs/api/personas/duplicatepersona.mdx new file mode 100644 index 00000000..0c65a55b --- /dev/null +++ b/src/pages/docs/api/personas/duplicatepersona.mdx @@ -0,0 +1,126 @@ +--- +title: "Duplicate persona" +description: "Creates a copy of an existing persona as a new workspace-level persona with a custom name." +--- + +# Duplicate persona + +Creates a copy of an existing persona (system or workspace) as a new workspace-level persona. All attributes are copied from the source persona except the name, which must be provided. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `persona_id` | string (UUID) | Yes | The UUID of the persona to duplicate. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Name for the copy. Max 255 chars. Must be unique in workspace (case-insensitive). | + +### Example + +```json +{ + "name": "My Custom Persona Copy" +} +``` + +## Responses + +### 201 + +Persona duplicated successfully. + +- **status**: string +- **result**: object + The full persona object of the newly created copy, with `persona_type` set to `workspace`. + +### 400 + +Bad Request. Possible reasons: +- `name` is missing or empty. +- Duplicate persona name already exists in the workspace. +- Organization context is missing. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The source persona with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/api/personas/duplicate/{persona_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "My Custom Persona Copy"}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/api/personas/duplicate/{persona_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "name": "My Custom Persona Copy" +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/api/personas/duplicate/{persona_id}/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "name": "My Custom Persona Copy" + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/personas/listpersonas.mdx b/src/pages/docs/api/personas/listpersonas.mdx new file mode 100644 index 00000000..814788d1 --- /dev/null +++ b/src/pages/docs/api/personas/listpersonas.mdx @@ -0,0 +1,122 @@ +--- +title: "List personas" +description: "Retrieves a paginated list of personas, including system-level and workspace-level personas, with optional filtering by type, search, and simulation type." +--- + +# List personas + +Retrieves a paginated list of personas accessible to the authenticated user. This includes system-level (prebuilt) personas and workspace-level (custom) personas. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `type` | string | No | - | Filter by persona type. Values: `prebuilt` (system), `custom` (workspace). | +| `search` | string | No | - | Search personas by name, description, or keywords (case-insensitive). | +| `simulation_type` | string | No | - | Filter by simulation type. Values: `voice`, `chat`. | +| `limit` | integer | No | 10 | Number of items per page. | +| `page` | integer | No | 1 | Page number. | + +## Responses + +### 200 + +A paginated list of personas. + +- **count**: integer + Total number of matching personas. +- **next**: string or null + URL of the next page. +- **previous**: string or null + URL of the previous page. +- **total_pages**: integer +- **current_page**: integer +- **results**: array of objects + Each object contains: + - **id**: string (UUID) + - **name**: string + - **description**: string + - **persona_type**: string (`system` or `workspace`) + - **persona_type_display**: string + - **gender**: array of string + - **age_group**: array of string + - **occupation**: array of string + - **location**: array of string + - **personality**: array of string + - **communication_style**: array of string + - **simulation_type**: string (`voice` or `chat`) + - **is_default**: boolean + - **created_at**: string (datetime) + - **updated_at**: string (datetime) + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/api/personas/?type=custom&limit=10&page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/api/personas/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "type": "custom", + "limit": 10, + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ type: "custom", limit: "10", page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/api/personas/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/personas/updatepersona.mdx b/src/pages/docs/api/personas/updatepersona.mdx new file mode 100644 index 00000000..01738201 --- /dev/null +++ b/src/pages/docs/api/personas/updatepersona.mdx @@ -0,0 +1,152 @@ +--- +title: "Update persona" +description: "Partially updates a workspace-level persona. System personas cannot be modified." +--- + +# Update persona + +Partially updates an existing workspace-level persona. Only provided fields are updated. System (prebuilt) personas cannot be modified. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `persona_id` | string (UUID) | Yes | The UUID of the persona to update. | + +## Request Body + +All fields are optional (partial update). Only provided fields will be updated. See [Create persona](/docs/api/personas/createpersona) for allowed values. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Persona name. Max 255 chars. | +| `description` | string | Persona description. | +| `gender` | array | Gender options. | +| `ageGroup` | array | Age group options. | +| `location` | array | Location options. | +| `personality` | array | Personality traits. | +| `communicationStyle` | array | Communication style options. | +| `accent` | array | Accent options. | +| `multilingual` | boolean | Multi-language support. | +| `language` | array | Language options. | +| `keywords` | array | Keywords. | +| `customProperties` | object | Key-value metadata. | +| `additionalInstruction` | string | Extra behavioral instructions. | +| `tone` | string | Tone setting. | +| `punctuation` | string | Punctuation style. | +| `slangUsage` | string | Slang level. | +| `typosFrequency` | string | Typo frequency. | +| `regionalMix` | string | Regional language mix. | +| `emojiUsage` | string | Emoji usage level. | +| `verbosity` | string | Response length preference. | + +### Example + +```json +{ + "name": "Updated Persona Name", + "personality": ["Confident", "Analytical"], + "tone": "formal" +} +``` + +## Responses + +### 200 + +Persona updated successfully. + +- **status**: string +- **result**: object + The full updated persona object. + +### 400 + +Bad Request. Invalid field values. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 403 + +Forbidden. System-level personas cannot be modified. + +### 404 + +Not Found. The persona with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X PATCH "https://api.futureagi.com/simulate/api/personas/{persona_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"name": "Updated Persona Name", "tone": "formal"}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/api/personas/{persona_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "name": "Updated Persona Name", + "tone": "formal" +} + +response = requests.patch(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/api/personas/{persona_id}/", { + method: "PATCH", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "name": "Updated Persona Name", + "tone": "formal" + }) +}); + +const data = await response.json(); +console.log(data); +``` From 9167900e6760dc7b0101a9ff677653f81b55f00f Mon Sep 17 00:00:00 2001 From: sarthak Date: Fri, 3 Apr 2026 17:31:33 +0530 Subject: [PATCH 2/9] prompt simulation apis --- src/lib/api-navigation.ts | 22 +++ src/lib/navigation.ts | 7 + src/pages/docs/api/index.mdx | 3 + .../prompt-simulations/executesimulation.mdx | 144 ++++++++++++++++++ .../getsimulationdetails.mdx | 112 ++++++++++++++ .../api/prompt-simulations/listscenarios.mdx | 112 ++++++++++++++ .../prompt-simulations/listsimulations.mdx | 133 ++++++++++++++++ 7 files changed, 533 insertions(+) create mode 100644 src/pages/docs/api/prompt-simulations/executesimulation.mdx create mode 100644 src/pages/docs/api/prompt-simulations/getsimulationdetails.mdx create mode 100644 src/pages/docs/api/prompt-simulations/listscenarios.mdx create mode 100644 src/pages/docs/api/prompt-simulations/listsimulations.mdx diff --git a/src/lib/api-navigation.ts b/src/lib/api-navigation.ts index 1a6ba9f3..05bee466 100644 --- a/src/lib/api-navigation.ts +++ b/src/lib/api-navigation.ts @@ -171,6 +171,28 @@ export const apiNavigation: ApiNavGroup[] = [ "title": "Execute a test run", "href": "/docs/api/run-tests/executeruntest", "method": "POST" + { + "title": "Prompt Simulations", + "items": [ + { + "title": "List prompt simulation scenarios", + "href": "/docs/api/prompt-simulations/listscenarios", + "method": "GET" + }, + { + "title": "List simulations for prompt template", + "href": "/docs/api/prompt-simulations/listsimulations", + "method": "GET" + }, + { + "title": "Get prompt simulation details", + "href": "/docs/api/prompt-simulations/getsimulationdetails", + "method": "GET" + }, + { + "title": "Execute prompt simulation", + "href": "/docs/api/prompt-simulations/executesimulation", + "method": "POST" } ] }, diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index 8eb40797..7321825a 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -963,6 +963,13 @@ export const tabNavigation: NavTab[] = [ items: [ { title: 'Create Run Test', href: '/docs/api/run-tests/createruntest' }, { title: 'Execute Run Test', href: '/docs/api/run-tests/executeruntest' }, + { + title: 'Prompt Simulations', + items: [ + { title: 'List Scenarios', href: '/docs/api/prompt-simulations/listscenarios' }, + { title: 'List Simulations', href: '/docs/api/prompt-simulations/listsimulations' }, + { title: 'Get Simulation Details', href: '/docs/api/prompt-simulations/getsimulationdetails' }, + { title: 'Execute Simulation', href: '/docs/api/prompt-simulations/executesimulation' }, ] }, { diff --git a/src/pages/docs/api/index.mdx b/src/pages/docs/api/index.mdx index caa16b95..d40f1690 100644 --- a/src/pages/docs/api/index.mdx +++ b/src/pages/docs/api/index.mdx @@ -110,6 +110,9 @@ Get your API key from the [Future AGI Dashboard](https://app.futureagi.com/setti Evaluation configuration and templates retrieval + + Prompt simulation scenarios, runs, and execution + API key management diff --git a/src/pages/docs/api/prompt-simulations/executesimulation.mdx b/src/pages/docs/api/prompt-simulations/executesimulation.mdx new file mode 100644 index 00000000..9bba826a --- /dev/null +++ b/src/pages/docs/api/prompt-simulations/executesimulation.mdx @@ -0,0 +1,144 @@ +--- +title: "Execute prompt simulation" +description: "Triggers the execution of a prompt simulation run. Supports selecting specific scenarios or running all scenarios with exclusion." +--- + +# Execute prompt simulation + +Triggers the execution of a prompt simulation run. The execution can target all scenarios or be customized to include or exclude specific scenarios. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `prompt_template_id` | string (UUID) | Yes | The UUID of the prompt template. | +| `run_test_id` | string (UUID) | Yes | The UUID of the simulation run to execute. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `selectAll` | boolean | No | Default `false`. When `true` with `scenarioIds`, runs all *except* listed. When `true` without, runs all. | +| `scenarioIds` | array of string (UUIDs) | No | Scenario IDs to include (when `selectAll` is `false`) or exclude (when `selectAll` is `true`). | + +### Validations + +- The prompt version linked to this simulation must exist and not be deleted. + +### Example + +```json +{ + "selectAll": true, + "scenarioIds": [] +} +``` + +## Responses + +### 200 + +Simulation execution started successfully. + +- **status**: string + Example: `success` +- **data**: object + - **message**: string + Example: `Simulation execution started successfully` + - **executionId**: string (UUID) + The test execution ID created. + - **runTestId**: string (UUID) + - **status**: string + Example: `pending` + - **totalScenarios**: integer + - **totalCalls**: integer + - **scenarioIds**: array of string (UUIDs) + +### 400 + +Bad Request. Possible reasons: +- Prompt version has been deleted. +- Execution failed to start due to configuration issues. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The prompt template or simulation run could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/{run_test_id}/execute/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"selectAll": true, "scenarioIds": []}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/{run_test_id}/execute/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "selectAll": True, + "scenarioIds": [] +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/{run_test_id}/execute/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "selectAll": true, + "scenarioIds": [] + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/prompt-simulations/getsimulationdetails.mdx b/src/pages/docs/api/prompt-simulations/getsimulationdetails.mdx new file mode 100644 index 00000000..2b6d0532 --- /dev/null +++ b/src/pages/docs/api/prompt-simulations/getsimulationdetails.mdx @@ -0,0 +1,112 @@ +--- +title: "Get prompt simulation details" +description: "Retrieves detailed information about a specific prompt simulation run, including its scenarios, prompt version, and evaluation configurations." +--- + +# Get prompt simulation details + +Retrieves detailed information about a specific prompt simulation run, including its associated scenarios, prompt version, and evaluation configurations. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `prompt_template_id` | string (UUID) | Yes | The UUID of the prompt template. | +| `run_test_id` | string (UUID) | Yes | The UUID of the simulation run. | + +## Responses + +### 200 + +Prompt simulation details returned successfully. + +- **id**: string (UUID) +- **name**: string +- **description**: string or null +- **source_type**: string +- **source_type_display**: string +- **prompt_template**: string (UUID) +- **prompt_template_detail**: object + Contains `id`, `name`, `description`, `variable_names`. +- **prompt_version**: string (UUID) +- **prompt_version_detail**: object + Contains `id`, `template_version`, `is_default`, `commit_message`. +- **scenarios**: array of string (UUIDs) +- **scenarios_detail**: array of objects +- **dataset_row_ids**: array of string +- **simulate_eval_configs**: array of string (UUIDs) +- **simulate_eval_configs_detail**: array of objects +- **enable_tool_evaluation**: boolean +- **created_at**: string (datetime) +- **updated_at**: string (datetime) +- **last_run_at**: string (datetime) or null + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The prompt template or simulation run could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/{run_test_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/{run_test_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/{run_test_id}/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/prompt-simulations/listscenarios.mdx b/src/pages/docs/api/prompt-simulations/listscenarios.mdx new file mode 100644 index 00000000..996e887f --- /dev/null +++ b/src/pages/docs/api/prompt-simulations/listscenarios.mdx @@ -0,0 +1,112 @@ +--- +title: "List prompt simulation scenarios" +description: "Retrieves a paginated list of available scenarios for prompt simulations." +--- + +# List prompt simulation scenarios + +Retrieves a paginated list of scenarios available for prompt simulations, with optional search filtering. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `search` | string | No | - | Search scenarios by name (case-insensitive). | +| `limit` | integer | No | 20 | Number of items per page. | +| `page` | integer | No | 1 | Page number. | + +## Responses + +### 200 + +A paginated list of prompt simulation scenarios. + +- **status**: string + Example: `success` +- **data**: object + - **count**: integer + - **page**: integer + - **limit**: integer + - **results**: array of objects + Each object contains: + - **id**: string (UUID) + - **name**: string + - **description**: string or null + - **scenario_type**: string (one of: `graph`, `script`, `dataset`) + - **dataset_id**: string (UUID) or null + - **created_at**: string (datetime) + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. Organization could not be determined. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/prompt-simulations/scenarios/?limit=20&page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/prompt-simulations/scenarios/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "limit": 20, + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ limit: "20", page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/prompt-simulations/scenarios/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/prompt-simulations/listsimulations.mdx b/src/pages/docs/api/prompt-simulations/listsimulations.mdx new file mode 100644 index 00000000..a0cd7055 --- /dev/null +++ b/src/pages/docs/api/prompt-simulations/listsimulations.mdx @@ -0,0 +1,133 @@ +--- +title: "List simulations for prompt template" +description: "Retrieves a paginated list of simulation runs for a specific prompt template, with optional filtering by prompt version." +--- + +# List simulations for prompt template + +Retrieves a paginated list of simulation runs associated with a specific prompt template, with optional filtering by prompt version. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `prompt_template_id` | string (UUID) | Yes | The UUID of the prompt template. | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `version_id` | string (UUID) | No | - | Filter by specific prompt version. | +| `limit` | integer | No | 10 | Number of items per page. | +| `page` | integer | No | 1 | Page number. | + +## Responses + +### 200 + +A paginated list of simulations. + +- **status**: string + Example: `success` +- **data**: object + - **count**: integer + - **page**: integer + - **limit**: integer + - **prompt_template**: object + - **id**: string (UUID) + - **name**: string + - **results**: array of objects + Each object contains: + - **id**: string (UUID) + - **name**: string + - **description**: string or null + - **source_type**: string + - **source_type_display**: string + - **prompt_template**: string (UUID) + - **prompt_template_detail**: object + Contains `id`, `name`, `description`, `variable_names`. + - **prompt_version**: string (UUID) + - **prompt_version_detail**: object + Contains `id`, `template_version`, `is_default`, `commit_message`. + - **scenarios**: array of string (UUIDs) + - **scenarios_detail**: array of objects + - **dataset_row_ids**: array of string + - **enable_tool_evaluation**: boolean + - **created_at**: string (datetime) + - **updated_at**: string (datetime) + - **last_run_at**: string (datetime) or null + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The prompt template could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/?limit=10&page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "limit": 10, + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ limit: "10", page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/prompt-templates/{prompt_template_id}/simulations/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` From a442217fa319d88d1369407bc18387115ce248ba Mon Sep 17 00:00:00 2001 From: sarthak Date: Fri, 3 Apr 2026 18:15:29 +0530 Subject: [PATCH 3/9] call executions apis --- src/lib/api-navigation.ts | 15 ++ src/lib/navigation.ts | 7 + .../getcallexecutiondetails.mdx | 159 ++++++++++++++++++ .../call-executions/getsessioncomparison.mdx | 114 +++++++++++++ src/pages/docs/api/index.mdx | 2 +- 5 files changed, 296 insertions(+), 1 deletion(-) create mode 100644 src/pages/docs/api/call-executions/getcallexecutiondetails.mdx create mode 100644 src/pages/docs/api/call-executions/getsessioncomparison.mdx diff --git a/src/lib/api-navigation.ts b/src/lib/api-navigation.ts index 05bee466..1b2cc2be 100644 --- a/src/lib/api-navigation.ts +++ b/src/lib/api-navigation.ts @@ -171,6 +171,21 @@ export const apiNavigation: ApiNavGroup[] = [ "title": "Execute a test run", "href": "/docs/api/run-tests/executeruntest", "method": "POST" + { + "title": "Call Executions", + "items": [ + { + "title": "Get call execution details", + "href": "/docs/api/call-executions/getcallexecutiondetails", + "method": "GET" + }, + { + "title": "Compare execution sessions", + "href": "/docs/api/call-executions/getsessioncomparison", + "method": "GET" + } + ] + }, { "title": "Prompt Simulations", "items": [ diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index 7321825a..bd8e0646 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -963,6 +963,13 @@ export const tabNavigation: NavTab[] = [ items: [ { title: 'Create Run Test', href: '/docs/api/run-tests/createruntest' }, { title: 'Execute Run Test', href: '/docs/api/run-tests/executeruntest' }, + { + title: 'Call Executions', + items: [ + { title: 'Get Call Details', href: '/docs/api/call-executions/getcallexecutiondetails' }, + { title: 'Compare Sessions', href: '/docs/api/call-executions/getsessioncomparison' }, + ] + }, { title: 'Prompt Simulations', items: [ diff --git a/src/pages/docs/api/call-executions/getcallexecutiondetails.mdx b/src/pages/docs/api/call-executions/getcallexecutiondetails.mdx new file mode 100644 index 00000000..acd12296 --- /dev/null +++ b/src/pages/docs/api/call-executions/getcallexecutiondetails.mdx @@ -0,0 +1,159 @@ +--- +title: "Get call execution details" +description: "Retrieves detailed information about a specific call execution, including transcripts, evaluation outputs, cost breakdown, and conversation metrics." +--- + +# Get call execution details + +Retrieves detailed information about a specific call execution, including its transcript, evaluation outputs, cost breakdown, and conversation metrics. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `call_execution_id` | string (UUID) | Yes | The UUID of the call execution. | + +## Responses + +### 200 + +Call execution details returned successfully. + +- **id**: string (UUID) +- **service_provider_call_id**: string or null +- **session_id**: string or null +- **status**: string (one of: `pending`, `queued`, `ongoing`, `completed`, `failed`, `analyzing`, `cancelled`) +- **duration**: number or null + Duration in seconds. +- **start_time**: string (datetime) or null +- **timestamp**: string (datetime) +- **call_type**: string or null + `Inbound` or `Outbound`. +- **transcript**: array of objects + Each contains: + - **role**: string (`agent` or `user`) + - **content**: string +- **scenario**: string + Scenario name. +- **scenario_id**: string (UUID) or null +- **scenario_columns**: array of objects + Scenario dataset column values. +- **overall_score**: number or null +- **response_time**: number or null + Response time in seconds. +- **eval_outputs**: object or null + Structured evaluation results keyed by evaluation name. +- **eval_metrics**: object or null +- **audio_url**: string or null + URL of the call recording. +- **recordings**: object or null + Provider-specific recording URLs. +- **customer_name**: string or null +- **call_summary**: string or null +- **ended_reason**: string or null +- **simulatorAgentName**: string or null +- **simulatorAgentId**: string (UUID) or null +- **agent_definition_used_name**: string or null +- **agent_definition_used_id**: string (UUID) or null +- **tool_outputs**: object or null +- **rerun_snapshots**: array of objects + Historical snapshots from previous reruns. + +**Voice conversation metrics:** + +- **avg_agent_latency**: number or null +- **user_interruption_count**: integer or null +- **user_interruption_rate**: number or null +- **user_wpm**: number or null +- **bot_wpm**: number or null +- **talk_ratio**: number or null +- **ai_interruption_count**: integer or null +- **ai_interruption_rate**: number or null +- **avg_stop_time_after_interruption**: number or null + +**Chat metrics (within conversation_metrics_data):** + +- **total_tokens**: integer or null +- **input_tokens**: integer or null +- **output_tokens**: integer or null +- **avg_latency_ms**: number or null +- **turn_count**: integer or null +- **csat_score**: number or null + +**Cost breakdown:** + +- **stt_cost**: number or null +- **llm_cost**: number or null +- **tts_cost**: number or null +- **storage_cost**: number or null +- **total_cost**: number or null + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The call execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/call-executions/{call_execution_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/call-executions/{call_execution_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/call-executions/{call_execution_id}/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/call-executions/getsessioncomparison.mdx b/src/pages/docs/api/call-executions/getsessioncomparison.mdx new file mode 100644 index 00000000..9ae77363 --- /dev/null +++ b/src/pages/docs/api/call-executions/getsessioncomparison.mdx @@ -0,0 +1,114 @@ +--- +title: "Compare execution sessions" +description: "Compares the current call execution with its most recent rerun snapshot, showing differences in metrics, transcripts, and evaluation results." +--- + +# Compare execution sessions + +Compares the current call execution session with its most recent rerun snapshot. Returns side-by-side metric comparisons, transcript differences, and evaluation result changes. The response format varies based on the agent type (voice or text). + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `call_execution_id` | string (UUID) | Yes | The UUID of the call execution. | + +## Responses + +### 200 + +Session comparison data returned successfully. The response structure depends on the agent type. + +**Voice agent response:** + +- **metrics_comparison**: object + Side-by-side comparison of voice metrics between current and previous sessions. +- **transcript_comparison**: object + Comparison of conversation transcripts. +- **recording_urls**: object + Recording URLs for both current and previous sessions. +- **eval_comparison**: object + Comparison of evaluation results. + +**Text/chat agent response:** + +- **metrics_comparison**: object + Side-by-side comparison of chat metrics (tokens, latency, turn count). +- **transcript_comparison**: object + Comparison of chat messages. +- **eval_comparison**: object + Comparison of evaluation results. + +### 400 + +Bad Request. No rerun snapshot available for comparison. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The call execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/call-executions/{call_execution_id}/session-comparison/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/call-executions/{call_execution_id}/session-comparison/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/call-executions/{call_execution_id}/session-comparison/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/index.mdx b/src/pages/docs/api/index.mdx index d40f1690..25571c49 100644 --- a/src/pages/docs/api/index.mdx +++ b/src/pages/docs/api/index.mdx @@ -53,7 +53,7 @@ Get your API key from the [Future AGI Dashboard](https://app.futureagi.com/setti Test execution tracking and analytics - + Individual call execution details From 2f39a256719c9fca2995928243b98c33886dffe6 Mon Sep 17 00:00:00 2001 From: sarthak Date: Fri, 3 Apr 2026 18:26:39 +0530 Subject: [PATCH 4/9] test-execution apis --- src/lib/api-navigation.ts | 35 ++++ src/lib/navigation.ts | 11 ++ src/pages/docs/api/index.mdx | 2 +- .../api/test-executions/cancelexecution.mdx | 117 ++++++++++++++ .../getevalexplanationsummary.mdx | 99 ++++++++++++ .../docs/api/test-executions/getkpis.mdx | 132 ++++++++++++++++ .../test-executions/getperformancesummary.mdx | 105 ++++++++++++ .../gettestexecutiondetails.mdx | 130 +++++++++++++++ .../docs/api/test-executions/reruncalls.mdx | 149 ++++++++++++++++++ 9 files changed, 779 insertions(+), 1 deletion(-) create mode 100644 src/pages/docs/api/test-executions/cancelexecution.mdx create mode 100644 src/pages/docs/api/test-executions/getevalexplanationsummary.mdx create mode 100644 src/pages/docs/api/test-executions/getkpis.mdx create mode 100644 src/pages/docs/api/test-executions/getperformancesummary.mdx create mode 100644 src/pages/docs/api/test-executions/gettestexecutiondetails.mdx create mode 100644 src/pages/docs/api/test-executions/reruncalls.mdx diff --git a/src/lib/api-navigation.ts b/src/lib/api-navigation.ts index 1b2cc2be..fda07b44 100644 --- a/src/lib/api-navigation.ts +++ b/src/lib/api-navigation.ts @@ -171,6 +171,41 @@ export const apiNavigation: ApiNavGroup[] = [ "title": "Execute a test run", "href": "/docs/api/run-tests/executeruntest", "method": "POST" + { + "title": "Test Executions", + "items": [ + { + "title": "Get test execution details", + "href": "/docs/api/test-executions/gettestexecutiondetails", + "method": "GET" + }, + { + "title": "Get execution KPIs", + "href": "/docs/api/test-executions/getkpis", + "method": "GET" + }, + { + "title": "Get performance summary", + "href": "/docs/api/test-executions/getperformancesummary", + "method": "GET" + }, + { + "title": "Get eval explanation summary", + "href": "/docs/api/test-executions/getevalexplanationsummary", + "method": "GET" + }, + { + "title": "Cancel test execution", + "href": "/docs/api/test-executions/cancelexecution", + "method": "POST" + }, + { + "title": "Rerun call executions", + "href": "/docs/api/test-executions/reruncalls", + "method": "POST" + } + ] + }, { "title": "Call Executions", "items": [ diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index bd8e0646..9a00e0fc 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -963,6 +963,17 @@ export const tabNavigation: NavTab[] = [ items: [ { title: 'Create Run Test', href: '/docs/api/run-tests/createruntest' }, { title: 'Execute Run Test', href: '/docs/api/run-tests/executeruntest' }, + { + title: 'Test Executions', + items: [ + { title: 'Get Execution Details', href: '/docs/api/test-executions/gettestexecutiondetails' }, + { title: 'Get Execution KPIs', href: '/docs/api/test-executions/getkpis' }, + { title: 'Get Performance Summary', href: '/docs/api/test-executions/getperformancesummary' }, + { title: 'Get Eval Explanation', href: '/docs/api/test-executions/getevalexplanationsummary' }, + { title: 'Cancel Execution', href: '/docs/api/test-executions/cancelexecution' }, + { title: 'Rerun Calls', href: '/docs/api/test-executions/reruncalls' }, + ] + }, { title: 'Call Executions', items: [ diff --git a/src/pages/docs/api/index.mdx b/src/pages/docs/api/index.mdx index 25571c49..1210d193 100644 --- a/src/pages/docs/api/index.mdx +++ b/src/pages/docs/api/index.mdx @@ -50,7 +50,7 @@ Get your API key from the [Future AGI Dashboard](https://app.futureagi.com/setti Test execution management - + Test execution tracking and analytics diff --git a/src/pages/docs/api/test-executions/cancelexecution.mdx b/src/pages/docs/api/test-executions/cancelexecution.mdx new file mode 100644 index 00000000..23b0064a --- /dev/null +++ b/src/pages/docs/api/test-executions/cancelexecution.mdx @@ -0,0 +1,117 @@ +--- +title: "Cancel test execution" +description: "Cancels an active test execution. The execution transitions to cancelling status and then to cancelled once fully stopped." +--- + +# Cancel test execution + +Cancels an active test execution. The execution status transitions to `cancelling` and eventually to `cancelled` once all running calls are stopped. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `test_execution_id` | string (UUID) | Yes | The UUID of the test execution to cancel. | + +## Request Body + +No request body required. Send an empty JSON object. + +### Example + +```json +{} +``` + +## Responses + +### 200 + +Cancellation initiated successfully. + +- **success**: boolean +- **message**: string + Example: `Test execution cancellation initiated` +- **test_execution_id**: string (UUID) + +### 400 + +Bad Request. The execution could not be cancelled. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +- **error**: string + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/cancel/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/cancel/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} + +response = requests.post(url, headers=headers, json={}) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/test-executions/{test_execution_id}/cancel/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({}) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/test-executions/getevalexplanationsummary.mdx b/src/pages/docs/api/test-executions/getevalexplanationsummary.mdx new file mode 100644 index 00000000..69d9a6ff --- /dev/null +++ b/src/pages/docs/api/test-executions/getevalexplanationsummary.mdx @@ -0,0 +1,99 @@ +--- +title: "Get eval explanation summary" +description: "Retrieves the evaluation explanation summary for a test execution, including critical issues analysis. Triggers async generation if not yet available." +--- + +# Get eval explanation summary + +Retrieves the evaluation explanation summary for a specific test execution. If the summary has not been generated yet, it triggers an asynchronous calculation and returns the current status. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `test_execution_id` | string (UUID) | Yes | The UUID of the test execution. | + +## Responses + +### 200 + +Eval explanation summary returned successfully. + +- **data**: object + - **response**: object or null + The evaluation explanation summary content. `null` if not yet generated. + - **last_updated**: string (datetime) or null + When the summary was last updated. + - **status**: string (one of: `pending`, `running`, `completed`, `failed`) + Current status of summary generation. +- **success**: boolean + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/eval-explanation-summary/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/eval-explanation-summary/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/test-executions/{test_execution_id}/eval-explanation-summary/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/test-executions/getkpis.mdx b/src/pages/docs/api/test-executions/getkpis.mdx new file mode 100644 index 00000000..a2005170 --- /dev/null +++ b/src/pages/docs/api/test-executions/getkpis.mdx @@ -0,0 +1,132 @@ +--- +title: "Get execution KPIs" +description: "Retrieves aggregated KPI metrics for a specific test execution, including call statistics, conversation metrics, and evaluation averages." +--- + +# Get execution KPIs + +Retrieves aggregated KPI metrics for a specific test execution. Returns different metrics depending on the agent type (voice or text). + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `test_execution_id` | string (UUID) | Yes | The UUID of the test execution. | + +## Responses + +### 200 + +KPI metrics returned successfully. Fields vary by agent type. + +**Common fields:** + +- **total_calls**: integer +- **avg_score**: number +- **avg_response**: number +- **callsAttempted**: integer +- **connectedCalls**: integer +- **callsConnectedPercentage**: number +- **failed_calls**: integer +- **total_duration**: integer +- **agent_type**: string (`voice` or `text`) +- **is_inbound**: boolean or null +- **scenarioGraphs**: object + +**Voice agent fields:** + +- **avg_agent_latency**: number +- **avg_user_interruption_count**: number +- **avg_user_interruption_rate**: number +- **avg_user_wpm**: number +- **avg_bot_wpm**: number +- **avg_talk_ratio**: number +- **avg_ai_interruption_count**: number +- **avg_ai_interruption_rate**: number +- **avg_stop_time_after_interruption**: number +- **agentTalkPercentage**: number +- **customerTalkPercentage**: number + +**Text/chat agent fields:** + +- **avg_total_tokens**: number +- **avg_input_tokens**: number +- **avg_output_tokens**: number +- **avg_chat_latency_ms**: number +- **avg_turn_count**: number +- **avg_csat_score**: number + +**Dynamic evaluation averages** (based on configured evaluations): + +- **avg_[metric_name]**: number + Dynamically generated averages for each evaluation metric. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/kpis/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/kpis/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/test-executions/{test_execution_id}/kpis/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/test-executions/getperformancesummary.mdx b/src/pages/docs/api/test-executions/getperformancesummary.mdx new file mode 100644 index 00000000..912cb7f8 --- /dev/null +++ b/src/pages/docs/api/test-executions/getperformancesummary.mdx @@ -0,0 +1,105 @@ +--- +title: "Get performance summary" +description: "Retrieves performance summary data for a test execution, including pass/fail rates and top performing scenarios." +--- + +# Get performance summary + +Retrieves performance summary data for a specific test execution, including test run metrics and the top performing scenarios ranked by average score. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `test_execution_id` | string (UUID) | Yes | The UUID of the test execution. | + +## Responses + +### 200 + +Performance summary returned successfully. + +- **test_run_performance_metrics**: object + - **pass_rate**: number + Percentage of completed calls. + - **total_test_runs**: integer + Total number of calls in the execution. + - **latest_fail_rate**: number + Percentage of failed calls. +- **top_performing_scenarios**: array of objects + Up to 4 scenarios sorted by performance score (descending). Each contains: + - **scenario_name**: string + - **test_count**: integer + Number of calls for this scenario. + - **performance_score**: number + Average score for the scenario (0-10). + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/performance-summary/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/performance-summary/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/test-executions/{test_execution_id}/performance-summary/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/test-executions/gettestexecutiondetails.mdx b/src/pages/docs/api/test-executions/gettestexecutiondetails.mdx new file mode 100644 index 00000000..c2d0e27b --- /dev/null +++ b/src/pages/docs/api/test-executions/gettestexecutiondetails.mdx @@ -0,0 +1,130 @@ +--- +title: "Get test execution details" +description: "Retrieves detailed information about a specific test execution, including paginated call executions with filtering and grouping support." +--- + +# Get test execution details + +Retrieves detailed information about a specific test execution, including its status, metrics, and a paginated list of associated call executions. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `test_execution_id` | string (UUID) | Yes | The UUID of the test execution. | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `search` | string | No | - | Search string to filter call executions. | +| `page` | integer | No | 1 | Page number for call executions. | +| `filters` | string (JSON) | No | - | JSON array of filter objects for call executions. | +| `row_groups` | string (JSON) | No | - | JSON array of column IDs to group results by. | +| `group_keys` | string (JSON) | No | - | JSON array of group keys for grouped results. | + +## Responses + +### 200 + +Test execution details returned successfully. + +- **id**: string (UUID) +- **run_test**: string (UUID) +- **run_test_name**: string +- **agent_definition_name**: string +- **status**: string (one of: `pending`, `running`, `completed`, `failed`, `cancelled`, `cancelling`, `evaluating`) +- **error_reason**: string or null +- **started_at**: string (datetime) +- **completed_at**: string (datetime) or null +- **total_scenarios**: integer +- **total_calls**: integer +- **completed_calls**: integer +- **failed_calls**: integer +- **execution_metadata**: object +- **duration_seconds**: integer or null +- **success_rate**: number or null +- **calls**: array of objects + Paginated list of call executions, each containing call details, transcripts, evaluation outputs, and metrics. +- **created_at**: string (datetime) +- **scenario_ids**: array of string (UUIDs) +- **simulator_agent_name**: string or null +- **simulator_agent_id**: string (UUID) or null +- **agent_definition_used_name**: string or null +- **agent_definition_used_id**: string (UUID) or null +- **calls_attempted**: integer +- **calls_connected_percentage**: number + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/?page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/test-executions/{test_execution_id}/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/test-executions/reruncalls.mdx b/src/pages/docs/api/test-executions/reruncalls.mdx new file mode 100644 index 00000000..8c610e23 --- /dev/null +++ b/src/pages/docs/api/test-executions/reruncalls.mdx @@ -0,0 +1,149 @@ +--- +title: "Rerun call executions" +description: "Reruns call executions within a test execution, either re-evaluating only or re-executing calls and evaluations." +--- + +# Rerun call executions + +Reruns one or more call executions within a specific test execution. Supports two modes: evaluation-only rerun or full call-and-evaluation rerun. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `test_execution_id` | string (UUID) | Yes | The UUID of the test execution. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `rerunType` | string | Yes | `eval_only` (re-evaluate existing data) or `call_and_eval` (re-execute calls then evaluate). | +| `callExecutionIds` | array of string (UUIDs) | Conditional | Specific call IDs to rerun. Required when `selectAll` is `false`. | +| `selectAll` | boolean | No | Default `false`. When `true`, reruns all calls in the execution. | + +### Validations + +- Provide either `selectAll: true` or a non-empty `callExecutionIds`. +- Execution must be in a terminal status (not `pending`, `running`, or `cancelling`). +- Text/chat agents only support `eval_only`. + +### Example + +```json +{ + "rerunType": "eval_only", + "callExecutionIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"], + "selectAll": false +} +``` + +## Responses + +### 200 + +Rerun initiated successfully. + +- **message**: string +- **testExecutionId**: string (UUID) +- **rerunType**: string +- **totalProcessed**: integer +- **successfulReruns**: array of string (UUIDs) +- **failedReruns**: array of objects + Each contains: + - **callExecutionId**: string (UUID) + - **error**: string +- **successCount**: integer +- **failureCount**: integer + +### 400 + +Bad Request. Possible reasons: +- Missing `rerunType`. +- Neither `callExecutionIds` nor `selectAll` provided. +- Test execution is still running. +- Text agents do not support `call_and_eval` rerun. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test execution with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/rerun-calls/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"rerunType": "eval_only", "callExecutionIds": ["call-uuid-1"], "selectAll": false}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/test-executions/{test_execution_id}/rerun-calls/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "rerunType": "eval_only", + "callExecutionIds": ["call-uuid-1"], + "selectAll": False +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/test-executions/{test_execution_id}/rerun-calls/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "rerunType": "eval_only", + "callExecutionIds": ["call-uuid-1"], + "selectAll": false + }) +}); + +const data = await response.json(); +console.log(data); +``` From 420177ddc9f6fb2a4e4ebc8093dfb6c5a8ba6200 Mon Sep 17 00:00:00 2001 From: sarthak Date: Fri, 3 Apr 2026 18:43:22 +0530 Subject: [PATCH 5/9] Run test apis --- src/lib/api-navigation.ts | 78 +++++++++ src/lib/navigation.ts | 17 ++ .../docs/api/run-tests/addevalconfigs.mdx | 157 ++++++++++++++++++ .../api/run-tests/compareevalsummaries.mdx | 106 ++++++++++++ .../docs/api/run-tests/createruntest.mdx | 29 ++-- .../docs/api/run-tests/deleteevalconfig.mdx | 102 ++++++++++++ .../docs/api/run-tests/deleteruntest.mdx | 101 +++++++++++ .../api/run-tests/deletetestexecutions.mdx | 136 +++++++++++++++ .../docs/api/run-tests/executeruntest.mdx | 11 +- .../docs/api/run-tests/getcallexecutions.mdx | 128 ++++++++++++++ .../docs/api/run-tests/getevalsummary.mdx | 99 +++++++++++ .../docs/api/run-tests/getruntestdetails.mdx | 115 +++++++++++++ .../docs/api/run-tests/gettestexecutions.mdx | 125 ++++++++++++++ .../docs/api/run-tests/gettestscenarios.mdx | 112 +++++++++++++ src/pages/docs/api/run-tests/listruntests.mdx | 114 +++++++++++++ .../api/run-tests/reruntestexecutions.mdx | 134 +++++++++++++++ .../run-tests/runnewevalsontestexecution.mdx | 142 ++++++++++++++++ .../docs/api/run-tests/updateevalconfig.mdx | 146 ++++++++++++++++ .../api/run-tests/updatetestcomponents.mdx | 131 +++++++++++++++ 19 files changed, 1959 insertions(+), 24 deletions(-) create mode 100644 src/pages/docs/api/run-tests/addevalconfigs.mdx create mode 100644 src/pages/docs/api/run-tests/compareevalsummaries.mdx create mode 100644 src/pages/docs/api/run-tests/deleteevalconfig.mdx create mode 100644 src/pages/docs/api/run-tests/deleteruntest.mdx create mode 100644 src/pages/docs/api/run-tests/deletetestexecutions.mdx create mode 100644 src/pages/docs/api/run-tests/getcallexecutions.mdx create mode 100644 src/pages/docs/api/run-tests/getevalsummary.mdx create mode 100644 src/pages/docs/api/run-tests/getruntestdetails.mdx create mode 100644 src/pages/docs/api/run-tests/gettestexecutions.mdx create mode 100644 src/pages/docs/api/run-tests/gettestscenarios.mdx create mode 100644 src/pages/docs/api/run-tests/listruntests.mdx create mode 100644 src/pages/docs/api/run-tests/reruntestexecutions.mdx create mode 100644 src/pages/docs/api/run-tests/runnewevalsontestexecution.mdx create mode 100644 src/pages/docs/api/run-tests/updateevalconfig.mdx create mode 100644 src/pages/docs/api/run-tests/updatetestcomponents.mdx diff --git a/src/lib/api-navigation.ts b/src/lib/api-navigation.ts index fda07b44..494bc69f 100644 --- a/src/lib/api-navigation.ts +++ b/src/lib/api-navigation.ts @@ -162,15 +162,93 @@ export const apiNavigation: ApiNavGroup[] = [ { "title": "Run Tests", "items": [ + { + "title": "List test runs", + "href": "/docs/api/run-tests/listruntests", + "method": "GET" + }, { "title": "Create a New Test Run", "href": "/docs/api/run-tests/createruntest", "method": "POST" }, + { + "title": "Get test run details", + "href": "/docs/api/run-tests/getruntestdetails", + "method": "GET" + }, + { + "title": "Delete a test run", + "href": "/docs/api/run-tests/deleteruntest", + "method": "DELETE" + }, { "title": "Execute a test run", "href": "/docs/api/run-tests/executeruntest", "method": "POST" + }, + { + "title": "Update test run components", + "href": "/docs/api/run-tests/updatetestcomponents", + "method": "PATCH" + }, + { + "title": "Get test executions", + "href": "/docs/api/run-tests/gettestexecutions", + "method": "GET" + }, + { + "title": "Get scenarios for a test run", + "href": "/docs/api/run-tests/gettestscenarios", + "method": "GET" + }, + { + "title": "Get call executions for a test run", + "href": "/docs/api/run-tests/getcallexecutions", + "method": "GET" + }, + { + "title": "Get evaluation summary", + "href": "/docs/api/run-tests/getevalsummary", + "method": "GET" + }, + { + "title": "Compare evaluation summaries", + "href": "/docs/api/run-tests/compareevalsummaries", + "method": "GET" + }, + { + "title": "Add evaluation configurations", + "href": "/docs/api/run-tests/addevalconfigs", + "method": "POST" + }, + { + "title": "Update evaluation configuration", + "href": "/docs/api/run-tests/updateevalconfig", + "method": "PATCH" + }, + { + "title": "Delete evaluation configuration", + "href": "/docs/api/run-tests/deleteevalconfig", + "method": "DELETE" + }, + { + "title": "Run new evaluations on test executions", + "href": "/docs/api/run-tests/runnewevalsontestexecution", + "method": "POST" + }, + { + "title": "Rerun test executions", + "href": "/docs/api/run-tests/reruntestexecutions", + "method": "POST" + }, + { + "title": "Delete test executions", + "href": "/docs/api/run-tests/deletetestexecutions", + "method": "POST" + } + ] + }, { "title": "Test Executions", "items": [ diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index 9a00e0fc..17fe8a89 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -961,8 +961,25 @@ export const tabNavigation: NavTab[] = [ { title: 'Run Tests', items: [ + { title: 'List Test Runs', href: '/docs/api/run-tests/listruntests' }, { title: 'Create Run Test', href: '/docs/api/run-tests/createruntest' }, + { title: 'Get Test Run Details', href: '/docs/api/run-tests/getruntestdetails' }, + { title: 'Delete Test Run', href: '/docs/api/run-tests/deleteruntest' }, { title: 'Execute Run Test', href: '/docs/api/run-tests/executeruntest' }, + { title: 'Update Components', href: '/docs/api/run-tests/updatetestcomponents' }, + { title: 'Get Test Executions', href: '/docs/api/run-tests/gettestexecutions' }, + { title: 'Get Test Scenarios', href: '/docs/api/run-tests/gettestscenarios' }, + { title: 'Get Call Executions', href: '/docs/api/run-tests/getcallexecutions' }, + { title: 'Get Eval Summary', href: '/docs/api/run-tests/getevalsummary' }, + { title: 'Compare Eval Summaries', href: '/docs/api/run-tests/compareevalsummaries' }, + { title: 'Add Eval Configs', href: '/docs/api/run-tests/addevalconfigs' }, + { title: 'Update Eval Config', href: '/docs/api/run-tests/updateevalconfig' }, + { title: 'Delete Eval Config', href: '/docs/api/run-tests/deleteevalconfig' }, + { title: 'Run New Evals', href: '/docs/api/run-tests/runnewevalsontestexecution' }, + { title: 'Rerun Test Executions', href: '/docs/api/run-tests/reruntestexecutions' }, + { title: 'Delete Test Executions', href: '/docs/api/run-tests/deletetestexecutions' }, + ] + }, { title: 'Test Executions', items: [ diff --git a/src/pages/docs/api/run-tests/addevalconfigs.mdx b/src/pages/docs/api/run-tests/addevalconfigs.mdx new file mode 100644 index 00000000..2aa2d5ee --- /dev/null +++ b/src/pages/docs/api/run-tests/addevalconfigs.mdx @@ -0,0 +1,157 @@ +--- +title: "Add evaluation configurations" +description: "Adds one or more evaluation configurations to a test run." +--- + +# Add evaluation configurations + +Adds one or more evaluation configurations to a test run. Each configuration links an evaluation template with field mappings and settings. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `evaluationsConfig` | array of objects | Yes | Evaluation configurations to add. | + +Each eval config object: + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `templateId` | string (UUID) | Yes | Evaluation template ID. | +| `name` | string | Yes | Config name. Must be unique within the test run. | +| `config` | object | No | Evaluation configuration parameters. | +| `mapping` | object | No | Field mapping configuration. | +| `filters` | object | No | Filter criteria. | +| `errorLocalizer` | boolean | No | Enable error localization. Default: `false`. | +| `model` | string | No | Model for evaluation. | + +### Example + +```json +{ + "evaluationsConfig": [ + { + "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Tone Check", + "config": {}, + "mapping": {}, + "errorLocalizer": false, + "model": "turing_large" + } + ] +} +``` + +## Responses + +### 200 + +Evaluation configurations added successfully. + +### 400 + +Bad Request. Possible reasons: +- Invalid template ID. +- Duplicate config name within the test run. +- Missing required fields. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"evaluationsConfig": [{"templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Tone Check", "config": {}, "mapping": {}}]}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "evaluationsConfig": [ + { + "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Tone Check", + "config": {}, + "mapping": {} + } + ] +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "evaluationsConfig": [ + { + "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "Tone Check", + "config": {}, + "mapping": {} + } + ] + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/compareevalsummaries.mdx b/src/pages/docs/api/run-tests/compareevalsummaries.mdx new file mode 100644 index 00000000..bf4acc24 --- /dev/null +++ b/src/pages/docs/api/run-tests/compareevalsummaries.mdx @@ -0,0 +1,106 @@ +--- +title: "Compare evaluation summaries" +description: "Compares evaluation summaries across multiple test executions for a given test run." +--- + +# Compare evaluation summaries + +Compares evaluation summaries across multiple test executions within a test run. Useful for tracking evaluation performance changes across runs. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +### Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `execution_ids` | string (JSON array) | Yes | JSON-encoded array of test execution UUIDs to compare. Example: `["uuid1","uuid2"]` | + +## Responses + +### 200 + +Comparison results returned successfully. Returns a dictionary keyed by execution ID, each containing evaluation summary metrics for that execution. + +### 400 + +Bad Request. Missing or invalid `execution_ids` parameter. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-summary-comparison/?execution_ids=%5B%22uuid1%22%2C%22uuid2%22%5D" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests +import json + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-summary-comparison/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "execution_ids": json.dumps(["execution-uuid-1", "execution-uuid-2"]) +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const executionIds = JSON.stringify(["execution-uuid-1", "execution-uuid-2"]); +const params = new URLSearchParams({ execution_ids: executionIds }); +const response = await fetch(`https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-summary-comparison/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/createruntest.mdx b/src/pages/docs/api/run-tests/createruntest.mdx index fd068c3e..c036d9bc 100644 --- a/src/pages/docs/api/run-tests/createruntest.mdx +++ b/src/pages/docs/api/run-tests/createruntest.mdx @@ -26,24 +26,17 @@ All requests require authentication via API keys: ## Request Body -- **name** (required): string - A unique name for the test run. -- **description**: string - An optional description for the test run. -- **scenarioIds** (required): array of string - A list of scenario UUIDs to be included in this test run. -- **agentDefinitionId** (required): string - The UUID of the agent definition to be tested. -- **agentVersion**: string - The specific UUID of the agent version to be tested. If not provided, the active version will be used. -- **evalConfigIds**: array of string - A list of existing evaluation configuration UUIDs to associate with this test run. -- **evaluationsConfig**: array of any - A list of new, detailed evaluation configurations to create and associate with this test run. -- **datasetRowIds**: array of string - A list of specific dataset row UUIDs to test against. -- **enableToolEvaluation**: boolean - Flag to enable tool evaluation for this test run. +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Test run name. Max 255 chars. | +| `description` | string | No | Optional description. | +| `scenarioIds` | array of string | Yes | Scenario UUIDs to include. Must be non-empty. | +| `agentDefinitionId` | string (UUID) | Yes | Agent definition to test. | +| `agentVersion` | string (UUID) | No | Specific agent version. Defaults to active version. | +| `evalConfigIds` | array of string | No | Existing eval config UUIDs to associate. | +| `evaluationsConfig` | array of objects | No | New eval configs to create and associate. Each needs `template_id`, `name`, `config`, `mapping`. | +| `datasetRowIds` | array of string | No | Specific dataset row UUIDs to test against. | +| `enableToolEvaluation` | boolean | No | Enable tool evaluation. Default: `false`. | ### Example diff --git a/src/pages/docs/api/run-tests/deleteevalconfig.mdx b/src/pages/docs/api/run-tests/deleteevalconfig.mdx new file mode 100644 index 00000000..eafe67e2 --- /dev/null +++ b/src/pages/docs/api/run-tests/deleteevalconfig.mdx @@ -0,0 +1,102 @@ +--- +title: "Delete evaluation configuration" +description: "Removes an evaluation configuration from a test run. Cannot delete the last remaining eval config." +--- + +# Delete evaluation configuration + +Removes an evaluation configuration from a test run. The test run must have at least one remaining evaluation configuration after deletion. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | +| `eval_config_id` | string (UUID) | Yes | The UUID of the evaluation configuration to delete. | + +### Validations + +- Cannot delete the last evaluation configuration in a test run. + +## Responses + +### 200 + +Evaluation configuration deleted successfully. + +- **message**: string + Example: `Evaluation config deleted successfully` + +### 400 + +Bad Request. Cannot delete the last eval config in the test run. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run or eval config with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X DELETE "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/{eval_config_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/{eval_config_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.delete(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/{eval_config_id}/", { + method: "DELETE", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/deleteruntest.mdx b/src/pages/docs/api/run-tests/deleteruntest.mdx new file mode 100644 index 00000000..9e3072ce --- /dev/null +++ b/src/pages/docs/api/run-tests/deleteruntest.mdx @@ -0,0 +1,101 @@ +--- +title: "Delete a test run" +description: "Soft-deletes a test run. Cannot delete a test run that has running executions." +--- + +# Delete a test run + +Soft-deletes a test run by marking it as deleted. The test run cannot be deleted if it has any currently running test executions. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run to delete. | + +### Validations + +- Cannot delete a test run that has `RUNNING` test executions. + +## Responses + +### 200 + +Test run deleted successfully. + +- **message**: string + Example: `Run test deleted successfully` + +### 400 + +Bad Request. The test run has running executions and cannot be deleted. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X DELETE "https://api.futureagi.com/simulate/run-tests/{run_test_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.delete(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/", { + method: "DELETE", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/deletetestexecutions.mdx b/src/pages/docs/api/run-tests/deletetestexecutions.mdx new file mode 100644 index 00000000..40e58383 --- /dev/null +++ b/src/pages/docs/api/run-tests/deletetestexecutions.mdx @@ -0,0 +1,136 @@ +--- +title: "Delete test executions" +description: "Bulk-deletes test executions from a test run. Cannot delete executions that are currently running, pending, or cancelling." +--- + +# Delete test executions + +Bulk-deletes one or more test executions from a test run. Supports deleting specific executions by ID or all executions at once. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `testExecutionIds` | array of string (UUIDs) | Conditional | Execution IDs to delete. Required when `selectAll` is `false`. | +| `selectAll` | boolean | No | Default `false`. When `true`, deletes all eligible executions. | + +### Validations + +- Provide either `selectAll: true` or a non-empty `testExecutionIds`. +- Cannot delete executions with status `RUNNING`, `PENDING`, or `CANCELLING`. + +### Example + +```json +{ + "testExecutionIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"], + "selectAll": false +} +``` + +## Responses + +### 200 + +Test executions deleted successfully. + +- **message**: string + Example: `Successfully deleted 2 test execution(s).` +- **runTestId**: string (UUID) +- **deletedCount**: integer +- **deletedIds**: array of string (UUIDs) + +### 400 + +Bad Request. Possible reasons: +- Neither `testExecutionIds` nor `selectAll` provided. +- Attempted to delete running/pending/cancelling executions. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/run-tests/{run_test_id}/delete-test-executions/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"testExecutionIds": ["execution-uuid-1"], "selectAll": false}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/delete-test-executions/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "testExecutionIds": ["execution-uuid-1"], + "selectAll": False +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/delete-test-executions/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "testExecutionIds": ["execution-uuid-1"], + "selectAll": false + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/executeruntest.mdx b/src/pages/docs/api/run-tests/executeruntest.mdx index 380bad97..8df7254a 100644 --- a/src/pages/docs/api/run-tests/executeruntest.mdx +++ b/src/pages/docs/api/run-tests/executeruntest.mdx @@ -34,12 +34,11 @@ All requests require authentication via API keys: ## Request Body -- **selectAll**: boolean - Determines how `scenarioIds` is interpreted. If `true`, all scenarios *except* those in `scenarioIds` will be executed. If `false`, *only* the scenarios in `scenarioIds` will be executed. If `scenarioIds` is empty, all scenarios will run regardless of this flag. -- **scenarioIds**: array of string - A list of scenario UUIDs to either include or exclude from the execution, based on the `selectAll` flag. -- **simulatorId**: string - An optional UUID of a specific simulator to use for the test run. +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `selectAll` | boolean | No | If `true`, runs all scenarios *except* those in `scenarioIds`. If `false`, runs *only* those in `scenarioIds`. If `scenarioIds` is empty, all scenarios run regardless. | +| `scenarioIds` | array of string | No | Scenario UUIDs to include or exclude based on `selectAll`. | +| `simulatorId` | string (UUID) | No | Specific simulator to use for execution. | ### Example diff --git a/src/pages/docs/api/run-tests/getcallexecutions.mdx b/src/pages/docs/api/run-tests/getcallexecutions.mdx new file mode 100644 index 00000000..4180de45 --- /dev/null +++ b/src/pages/docs/api/run-tests/getcallexecutions.mdx @@ -0,0 +1,128 @@ +--- +title: "Get call executions for a test run" +description: "Retrieves a paginated list of all call executions across all test executions for a specific test run." +--- + +# Get call executions for a test run + +Retrieves a paginated list of all call executions (individual simulation calls) across all test executions for a specific test run, with optional search and status filtering. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `search` | string | No | - | Filter by phone number or scenario name. | +| `status` | string | No | - | Filter by call status. | +| `limit` | integer | No | 10 | Number of items per page. | +| `page` | integer | No | 1 | Page number. | + +## Responses + +### 200 + +A paginated list of call executions. + +- **count**: integer +- **next**: string or null +- **previous**: string or null +- **results**: array of objects + Each object contains: + - **id**: string (UUID) + - **session_id**: string or null + - **status**: string + - **duration**: number or null + - **start_time**: string (datetime) or null + - **transcript**: array of objects + - **scenario**: object or null + - **overall_score**: number or null + - **eval_outputs**: object or null + - **eval_metrics**: object or null + - **customer_name**: string or null + - **call_summary**: string or null + - **ended_reason**: string or null + - **avg_agent_latency**: number or null + - **scenario_id**: string (UUID) or null + - **is_snapshot**: boolean + - **rerun_type**: string or null + - **created_at**: string (datetime) + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/run-tests/{run_test_id}/call-executions/?limit=10&page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/call-executions/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "limit": 10, + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ limit: "10", page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/run-tests/{run_test_id}/call-executions/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/getevalsummary.mdx b/src/pages/docs/api/run-tests/getevalsummary.mdx new file mode 100644 index 00000000..d7dd8f5d --- /dev/null +++ b/src/pages/docs/api/run-tests/getevalsummary.mdx @@ -0,0 +1,99 @@ +--- +title: "Get evaluation summary" +description: "Retrieves the evaluation summary statistics for a test run, optionally filtered by a specific execution." +--- + +# Get evaluation summary + +Retrieves the aggregated evaluation summary statistics for a test run. Can be filtered to a specific test execution. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +### Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `execution_id` | string (UUID) | No | Filter results to a specific test execution. | + +## Responses + +### 200 + +Evaluation summary returned successfully. Contains aggregated metrics and scores for all evaluations run against the test. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-summary/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-summary/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "execution_id": "optional-execution-uuid" # optional +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-summary/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/getruntestdetails.mdx b/src/pages/docs/api/run-tests/getruntestdetails.mdx new file mode 100644 index 00000000..abad5521 --- /dev/null +++ b/src/pages/docs/api/run-tests/getruntestdetails.mdx @@ -0,0 +1,115 @@ +--- +title: "Get test run details" +description: "Retrieves detailed information about a specific test run, including associated scenarios, agent definition, and evaluation configurations." +--- + +# Get test run details + +Retrieves detailed information about a specific test run, including its associated scenarios, agent definition, simulator agent, and evaluation configurations. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run to retrieve. | + +## Responses + +### 200 + +Test run details returned successfully. + +- **id**: string (UUID) +- **name**: string +- **description**: string +- **agent_definition**: string (UUID) or null +- **agent_version**: string (UUID) or null +- **agent_definition_detail**: object or null +- **source_type**: string +- **source_type_display**: string +- **prompt_template**: string (UUID) or null +- **prompt_template_detail**: object or null +- **prompt_version**: string (UUID) or null +- **prompt_version_detail**: object or null +- **scenarios**: array of string (UUIDs) +- **scenarios_detail**: array of objects +- **dataset_row_ids**: array of string +- **simulator_agent**: string (UUID) or null +- **simulator_agent_detail**: object or null +- **simulate_eval_configs**: array of string (UUIDs) +- **simulate_eval_configs_detail**: array of objects +- **evals_detail**: array of objects +- **enable_tool_evaluation**: boolean +- **created_at**: string (datetime) +- **updated_at**: string (datetime) +- **last_run_at**: string (datetime) or null + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/run-tests/{run_test_id}/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} + +response = requests.get(url, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/", { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/gettestexecutions.mdx b/src/pages/docs/api/run-tests/gettestexecutions.mdx new file mode 100644 index 00000000..8060f494 --- /dev/null +++ b/src/pages/docs/api/run-tests/gettestexecutions.mdx @@ -0,0 +1,125 @@ +--- +title: "Get test executions" +description: "Retrieves a paginated list of test executions for a specific test run, with optional filtering by status or search." +--- + +# Get test executions + +Retrieves a paginated list of test executions for a specific test run. Each execution represents one run of the test and includes call metrics. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `search` | string | No | - | Filter by status or scenario name. | +| `status` | string | No | - | Filter by execution status (e.g., `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`). | +| `limit` | integer | No | 10 | Number of items per page. | +| `page` | integer | No | 1 | Page number. | + +## Responses + +### 200 + +A paginated list of test executions. + +- **count**: integer +- **next**: string or null +- **previous**: string or null +- **results**: array of objects + Each object contains: + - **id**: string (UUID) + - **run_test**: string (UUID) + - **status**: string + - **started_at**: string (datetime) or null + - **completed_at**: string (datetime) or null + - **total_scenarios**: integer + - **total_calls**: integer + - **completed_calls**: integer + - **failed_calls**: integer + - **duration_seconds**: number or null + - **success_rate**: number or null + - **scenario_ids**: array of string (UUIDs) + - **simulator_agent_name**: string or null + - **agent_definition_used_name**: string or null + - **created_at**: string (datetime) + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/run-tests/{run_test_id}/executions/?limit=10&page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/executions/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "limit": 10, + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ limit: "10", page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/run-tests/{run_test_id}/executions/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/gettestscenarios.mdx b/src/pages/docs/api/run-tests/gettestscenarios.mdx new file mode 100644 index 00000000..eb4b7fd3 --- /dev/null +++ b/src/pages/docs/api/run-tests/gettestscenarios.mdx @@ -0,0 +1,112 @@ +--- +title: "Get scenarios for a test run" +description: "Retrieves a paginated list of scenarios associated with a specific test run." +--- + +# Get scenarios for a test run + +Retrieves a paginated list of scenarios associated with a specific test run, with optional search filtering. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `search` | string | No | - | Filter by scenario name, source, or type. | +| `limit` | integer | No | 10 | Number of items per page. | +| `page` | integer | No | 1 | Page number. | + +## Responses + +### 200 + +A paginated list of scenarios for the test run. + +- **count**: integer +- **next**: string or null +- **previous**: string or null +- **results**: array of objects + Each object contains: + - **id**: string (UUID) + - **name**: string + - **row_count**: integer + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/run-tests/{run_test_id}/scenarios/?limit=10&page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/scenarios/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "limit": 10, + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ limit: "10", page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/run-tests/{run_test_id}/scenarios/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/listruntests.mdx b/src/pages/docs/api/run-tests/listruntests.mdx new file mode 100644 index 00000000..ad690589 --- /dev/null +++ b/src/pages/docs/api/run-tests/listruntests.mdx @@ -0,0 +1,114 @@ +--- +title: "List test runs" +description: "Retrieves a paginated list of all test runs for the authenticated user's organization, with optional search and filtering." +--- + +# List test runs + +Retrieves a paginated list of all test runs for the authenticated user's organization, with optional search and filtering. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Query Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `search` | string | No | - | Filter by test run name or agent definition name (case-insensitive). | +| `limit` | integer | No | 10 | Number of items per page. | +| `page` | integer | No | 1 | Page number. | +| `simulation_type` | string | No | - | Filter by source type. Values: `agent_definition`, `prompt`. | +| `prompt_template_id` | string (UUID) | No | - | Filter by prompt template. | + +## Responses + +### 200 + +A paginated list of test runs. + +- **count**: integer +- **next**: string or null +- **previous**: string or null +- **results**: array of objects + Each object contains: + - **id**: string (UUID) + - **name**: string + - **description**: string + - **agent_definition**: string (UUID) or null + - **agent_definition_detail**: object or null + - **source_type**: string + - **source_type_display**: string + - **scenarios**: array of string (UUIDs) + - **enable_tool_evaluation**: boolean + - **created_at**: string (datetime) + - **updated_at**: string (datetime) + - **last_run_at**: string (datetime) or null + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X GET "https://api.futureagi.com/simulate/run-tests/?search=test&limit=10&page=1" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" +} +params = { + "search": "test", + "limit": 10, + "page": 1 +} + +response = requests.get(url, headers=headers, params=params) +print(response.json()) +``` + +### JavaScript + +```javascript +const params = new URLSearchParams({ search: "test", limit: "10", page: "1" }); +const response = await fetch(`https://api.futureagi.com/simulate/run-tests/?${params}`, { + method: "GET", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY" + } +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/reruntestexecutions.mdx b/src/pages/docs/api/run-tests/reruntestexecutions.mdx new file mode 100644 index 00000000..85168d9a --- /dev/null +++ b/src/pages/docs/api/run-tests/reruntestexecutions.mdx @@ -0,0 +1,134 @@ +--- +title: "Rerun test executions" +description: "Reruns one or more test executions, either re-evaluating only or re-executing calls and evaluations." +--- + +# Rerun test executions + +Reruns one or more test executions from a test run. Supports two modes: evaluation-only rerun or full call-and-evaluation rerun. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `rerunType` | string | Yes | `eval_only` (re-run evals only) or `call_and_eval` (re-execute calls + evals). | +| `testExecutionIds` | array of string (UUIDs) | Conditional | Execution IDs to rerun. Required when `selectAll` is `false`. | +| `selectAll` | boolean | No | Default `false`. When `true`, reruns all executions for this test run. | + +### Validations + +- Provide either `selectAll: true` or a non-empty `testExecutionIds`. + +### Example + +```json +{ + "rerunType": "eval_only", + "testExecutionIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"], + "selectAll": false +} +``` + +## Responses + +### 200 + +Rerun initiated successfully. Returns details of the rerun operation. + +### 400 + +Bad Request. Possible reasons: +- Missing `rerunType`. +- Neither `testExecutionIds` nor `selectAll` provided. +- Invalid rerun type value. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/run-tests/{run_test_id}/rerun-test-executions/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"rerunType": "eval_only", "testExecutionIds": ["execution-uuid-1"], "selectAll": false}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/rerun-test-executions/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "rerunType": "eval_only", + "testExecutionIds": ["execution-uuid-1"], + "selectAll": False +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/rerun-test-executions/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "rerunType": "eval_only", + "testExecutionIds": ["execution-uuid-1"], + "selectAll": false + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/runnewevalsontestexecution.mdx b/src/pages/docs/api/run-tests/runnewevalsontestexecution.mdx new file mode 100644 index 00000000..4272d252 --- /dev/null +++ b/src/pages/docs/api/run-tests/runnewevalsontestexecution.mdx @@ -0,0 +1,142 @@ +--- +title: "Run new evaluations on test executions" +description: "Triggers new evaluations on completed test executions using specified evaluation configurations." +--- + +# Run new evaluations on test executions + +Triggers new evaluations on one or more completed test executions using the specified evaluation configurations. Only works on executions with `COMPLETED` status. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `testExecutionIds` | array of string (UUIDs) | Conditional | Execution IDs to evaluate. Required when `selectAll` is `false`. | +| `selectAll` | boolean | No | Default `false`. When `true`, evaluates all completed executions. | +| `evalConfigIds` | array of string (UUIDs) | Yes | Eval config IDs to run. Must not be empty. | +| `enableToolEvaluation` | boolean | No | Enable tool evaluation. | + +### Validations + +- Provide either `selectAll: true` or a non-empty `testExecutionIds`. +- Only `COMPLETED` executions are eligible. + +### Example + +```json +{ + "testExecutionIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"], + "selectAll": false, + "evalConfigIds": ["d4e5f6a7-b8c9-0123-def0-123456789abc"] +} +``` + +## Responses + +### 200 + +Evaluations started successfully. + +- **message**: string + Example: `Evaluations started successfully` +- **run_test_id**: string (UUID) +- **call_execution_count**: integer + Number of call executions being evaluated. + +### 400 + +Bad Request. Possible reasons: +- Neither `test_execution_ids` nor `select_all` provided. +- `eval_config_ids` is empty. +- No completed test executions found. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X POST "https://api.futureagi.com/simulate/run-tests/{run_test_id}/run-new-evals/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"testExecutionIds": ["execution-uuid-1"], "selectAll": false, "evalConfigIds": ["eval-config-uuid-1"]}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/run-new-evals/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "testExecutionIds": ["execution-uuid-1"], + "selectAll": False, + "evalConfigIds": ["eval-config-uuid-1"] +} + +response = requests.post(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/run-new-evals/", { + method: "POST", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "testExecutionIds": ["execution-uuid-1"], + "selectAll": false, + "evalConfigIds": ["eval-config-uuid-1"] + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/updateevalconfig.mdx b/src/pages/docs/api/run-tests/updateevalconfig.mdx new file mode 100644 index 00000000..d1f9e3dd --- /dev/null +++ b/src/pages/docs/api/run-tests/updateevalconfig.mdx @@ -0,0 +1,146 @@ +--- +title: "Update evaluation configuration" +description: "Updates an evaluation configuration for a test run, with an optional flag to trigger a rerun of the evaluation." +--- + +# Update evaluation configuration + +Updates an existing evaluation configuration for a test run. Optionally triggers a rerun of the evaluation on a specific test execution. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run. | +| `eval_config_id` | string (UUID) | Yes | The UUID of the evaluation configuration to update. | + +## Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `config` | object | No | Updated config with nested `config` and `mapping` objects. | +| `mapping` | object | No | Updated field mapping. | +| `model` | string | No | Model for evaluation. | +| `errorLocalizer` | boolean | No | Enable/disable error localization. | +| `kbId` | string (UUID) | No | Knowledge base file reference. | +| `name` | string | No | Updated config name. | +| `run` | boolean | No | If `true`, triggers a rerun on the specified execution. | +| `testExecutionId` | string (UUID) | Conditional | Test execution to rerun on. Required if `run` is `true`. | + +### Example + +```json +{ + "config": { + "config": {}, + "mapping": {} + }, + "model": "turing_large", + "name": "Updated Config Name", + "run": false +} +``` + +## Responses + +### 200 + +Evaluation configuration updated successfully. + +- If `run` is `false`: + - **message**: string + Example: `Evaluation config updated successfully` +- If `run` is `true`: + - **message**: string + Example: `Evaluation config updated and rerun triggered successfully` + +### 400 + +Bad Request. Invalid data or missing `test_execution_id` when `run` is `true`. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run or eval config could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X PATCH "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/{eval_config_id}/update/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"config": {"config": {}, "mapping": {}}, "model": "turing_large", "name": "Updated Config", "run": false}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/{eval_config_id}/update/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "config": {"config": {}, "mapping": {}}, + "model": "turing_large", + "name": "Updated Config", + "run": False +} + +response = requests.patch(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/eval-configs/{eval_config_id}/update/", { + method: "PATCH", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "config": {"config": {}, "mapping": {}}, + "model": "turing_large", + "name": "Updated Config", + "run": false + }) +}); + +const data = await response.json(); +console.log(data); +``` diff --git a/src/pages/docs/api/run-tests/updatetestcomponents.mdx b/src/pages/docs/api/run-tests/updatetestcomponents.mdx new file mode 100644 index 00000000..d26e9131 --- /dev/null +++ b/src/pages/docs/api/run-tests/updatetestcomponents.mdx @@ -0,0 +1,131 @@ +--- +title: "Update test run components" +description: "Updates the components of a test run, such as the agent definition, version, simulator agent, or scenarios." +--- + +# Update test run components + +Updates the components of an existing test run, including the agent definition, agent version, simulator agent, associated scenarios, and tool evaluation settings. + + + +## Authentication + +All requests require authentication via API keys: + +| Header | Description | +|--------|-------------| +| `X-Api-Key` | Your API key | +| `X-Secret-Key` | Your secret key | + +## Parameters + +### Path Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `run_test_id` | string (UUID) | Yes | The UUID of the test run to update. | + +## Request Body + +All fields are optional. Only provided fields are updated. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `agentDefinitionId` | string (UUID) | No | New agent definition. | +| `version` | string (UUID) | No | Specific agent version. | +| `simulatorAgentId` | string (UUID) | No | Simulator agent to use. | +| `scenarios` | array of string (UUIDs) | No | Updated scenario IDs. | +| `enableToolEvaluation` | boolean | No | Enable tool evaluation. Agent must have API key and assistant ID configured. | + +### Example + +```json +{ + "agentDefinitionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "scenarios": ["scenario-uuid-1", "scenario-uuid-2"], + "enableToolEvaluation": false +} +``` + +## Responses + +### 200 + +Test run components updated successfully. Returns the updated test run object. + +### 400 + +Bad Request. Possible reasons: +- `enable_tool_evaluation` set to `true` but agent is missing `api_key` or `assistant_id`. +- Invalid UUID references. + +### 401 + +Unauthorized. Authentication credentials were not provided or are invalid. + +### 404 + +Not Found. The test run with the specified ID could not be found. + +### 500 + +Internal Server Error. An unexpected error occurred. + +## Code Examples + +### cURL + +```bash +curl -X PATCH "https://api.futureagi.com/simulate/run-tests/{run_test_id}/components/" \ + -H "X-Api-Key: YOUR_API_KEY" \ + -H "X-Secret-Key: YOUR_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"scenarios": ["scenario-uuid-1", "scenario-uuid-2"], "enableToolEvaluation": false}' +``` + +### Python + +```python +import requests + +url = "https://api.futureagi.com/simulate/run-tests/{run_test_id}/components/" +headers = { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" +} +data = { + "scenarios": ["scenario-uuid-1", "scenario-uuid-2"], + "enableToolEvaluation": False +} + +response = requests.patch(url, headers=headers, json=data) +print(response.json()) +``` + +### JavaScript + +```javascript +const response = await fetch("https://api.futureagi.com/simulate/run-tests/{run_test_id}/components/", { + method: "PATCH", + headers: { + "X-Api-Key": "YOUR_API_KEY", + "X-Secret-Key": "YOUR_SECRET_KEY", + "Content-Type": "application/json" + }, + body: JSON.stringify({ + "scenarios": ["scenario-uuid-1", "scenario-uuid-2"], + "enableToolEvaluation": false + }) +}); + +const data = await response.json(); +console.log(data); +``` From 6a8a795137fccd4eaa4de56ba73de5cc45b477cb Mon Sep 17 00:00:00 2001 From: sarthak Date: Sun, 5 Apr 2026 14:19:19 +0530 Subject: [PATCH 6/9] Refactor API documentation for test executions --- src/components/Sidebar.astro | 30 +- src/components/docs/ApiCollapsible.astro | 44 +- .../createagentdefinition.mdx | 1 + .../fetchassistantfromprovider.mdx | 3 +- .../agent-definitions/getagentdefinition.mdx | 26 +- .../listagentdefinitions.mdx | 67 +++- .../api/agent-versions/createagentversion.mdx | 3 +- .../api/agent-versions/getagentversion.mdx | 54 ++- .../getversioncallexecutions.mdx | 68 +++- .../api/agent-versions/listagentversions.mdx | 46 ++- .../getcallexecutiondetails.mdx | 377 +++++++++++------- .../call-executions/getsessioncomparison.mdx | 208 +++++----- .../docs/api/eval-tasks/get-eval-task.mdx | 15 +- .../eval-tasks/list-eval-tasks-filtered.mdx | 28 +- .../docs/api/eval-tasks/update-eval-task.mdx | 28 +- src/pages/docs/api/personas/createpersona.mdx | 287 +++++++------ src/pages/docs/api/personas/deletepersona.mdx | 136 +++---- .../docs/api/personas/duplicatepersona.mdx | 182 ++++----- src/pages/docs/api/personas/listpersonas.mdx | 247 ++++++------ src/pages/docs/api/personas/updatepersona.mdx | 267 ++++++------- .../prompt-simulations/executesimulation.mdx | 228 +++++------ .../getsimulationdetails.mdx | 223 ++++++----- .../api/prompt-simulations/listscenarios.mdx | 189 ++++----- .../prompt-simulations/listsimulations.mdx | 222 +++++------ .../docs/api/run-tests/addevalconfigs.mdx | 208 +++------- .../api/run-tests/compareevalsummaries.mdx | 143 +++---- .../docs/api/run-tests/createruntest.mdx | 215 ++++------ .../docs/api/run-tests/deleteevalconfig.mdx | 136 +++---- .../docs/api/run-tests/deleteruntest.mdx | 131 ++---- .../api/run-tests/deletetestexecutions.mdx | 183 +++------ .../docs/api/run-tests/executeruntest.mdx | 197 ++++----- .../docs/api/run-tests/getcallexecutions.mdx | 239 +++++------ .../docs/api/run-tests/getevalsummary.mdx | 150 +++---- .../docs/api/run-tests/getruntestdetails.mdx | 211 +++++----- .../docs/api/run-tests/gettestexecutions.mdx | 227 ++++++----- .../docs/api/run-tests/gettestscenarios.mdx | 174 ++++---- src/pages/docs/api/run-tests/listruntests.mdx | 193 +++++---- .../api/run-tests/reruntestexecutions.mdx | 175 +++----- .../run-tests/runnewevalsontestexecution.mdx | 192 +++------ .../docs/api/run-tests/updateevalconfig.mdx | 206 ++++------ .../api/run-tests/updatetestcomponents.mdx | 178 +++------ src/pages/docs/api/scenarios/getscenario.mdx | 10 +- .../docs/api/scenarios/listscenarios.mdx | 40 +- .../api/test-executions/cancelexecution.mdx | 162 +++----- .../getevalexplanationsummary.mdx | 151 +++---- .../docs/api/test-executions/getkpis.mdx | 268 +++++++------ .../test-executions/getperformancesummary.mdx | 165 ++++---- .../gettestexecutiondetails.mdx | 300 ++++++++------ .../docs/api/test-executions/reruncalls.mdx | 222 ++++------- 49 files changed, 3464 insertions(+), 3991 deletions(-) diff --git a/src/components/Sidebar.astro b/src/components/Sidebar.astro index fced9666..f6f1d739 100644 --- a/src/components/Sidebar.astro +++ b/src/components/Sidebar.astro @@ -370,38 +370,38 @@ function getIconPath(icon?: string): string { } } - var SCROLL_KEY = 'sidebar-scroll'; - - function saveScroll() { + function scrollToActiveItem() { var nav = document.querySelector('#sidebar nav'); - if (nav) sessionStorage.setItem(SCROLL_KEY, nav.scrollTop); - } - - function restoreScroll() { - var saved = sessionStorage.getItem(SCROLL_KEY); - if (saved !== null) { - var nav = document.querySelector('#sidebar nav'); - if (nav) nav.scrollTop = parseInt(saved, 10); + if (!nav) return; + // Find the active link — it has font-medium + bg-hover styling applied server-side + var active = nav.querySelector('a.font-medium'); + if (!active) return; + // Calculate position relative to the nav scroll container + var navRect = nav.getBoundingClientRect(); + var activeRect = active.getBoundingClientRect(); + // Only scroll if the active item is outside the visible area + if (activeRect.top < navRect.top || activeRect.bottom > navRect.bottom) { + var offset = active.offsetTop - nav.offsetTop - navRect.height / 3; + nav.scrollTop = Math.max(0, offset); } } setupSidebar(); - restoreScroll(); + scrollToActiveItem(); // Register global listeners only once (script re-executes on view transitions) if (!window.__sidebarListenersReady) { window.__sidebarListenersReady = true; - document.addEventListener('astro:before-swap', saveScroll); - document.addEventListener('astro:page-load', function() { setupSidebar(); - restoreScroll(); + scrollToActiveItem(); }); // Re-init after FastNav swaps sidebar innerHTML window.addEventListener('fastnav', function() { setupSidebar(); + scrollToActiveItem(); }); } diff --git a/src/components/docs/ApiCollapsible.astro b/src/components/docs/ApiCollapsible.astro index 0a99c257..957dcc84 100644 --- a/src/components/docs/ApiCollapsible.astro +++ b/src/components/docs/ApiCollapsible.astro @@ -28,29 +28,31 @@ const cid = `apic-${Math.random().toString(36).slice(2, 8)}`; -