Quick Start

This guide is designed to take you from zero to running your first test as quickly as possible. Our goal is to demonstrate the bare minimum steps required to get started with the platform from the API perspective. This page aims to help users with no prior experience with our API gain a foundational understanding of how to interact with it and successfully execute a basic test. By following this guide, you’ll be able to familiarize yourself with the essential workflow, providing a solid starting point for further exploration and refinement of the platform’s features.

All payloads will be presented. Response payloads will be shown without captions, while request payloads will include captions for clarity.

Minimum Viable Workflow - Example

In this example we will:

• use Default workspace

• create a new Target (REST API connector)

  • without RAG

  • without System Prompt

• configure URL Check (predefined) probe

• execute test run with URL Check probe

• retrieve test run status

Here are the steps:

1. Generate a Personal Access Token and include it in a request header to interact with the Platform API.

2. Get Workspace id and use it in step 4. get /api/workspace

   [
       {
           "userCount": 1,
           "id": 1,
           "name": "Default",
           "description": null,
           "defaultWorkerPoolId": null,
           "targets": [],
           "guardrails": []
       }
   ]

3. Get id for "Private Without RAG" type of Target and use it in step 4. get api/target/types

   [
       {
           "id": " ... ",
           "label": "Private With RAG",
           "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       },
       {
       "id": " ... ",
           "label": "Private Without RAG",
           "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       }
   ]

4. Create a new Target. replace :workspaceId with a workspace Id, and set targetPresetId value to "Private Without RAG" id.

   post /api/v2/workspaces/:workspaceId/target

   Request Payload

   {
     "connection": {
       "config": {
               "url": "http://20.79.178.230:11000/message",
               "requestPayloadSample": "{\n  \"session_id\": \"{session_id}\",\n  \"prompt\": \"{message}\",\n  \"files\": [\n    {\n      \"file_format\": \"image/webp\",\n      \"data\": \"{image_base64}\"\n    },\n    {\n      \"file_format\": \"audio/mpeg\",\n      \"data\": \"{audio_base64}\"\n    }\n  ]\n}",
               "responsePayload": "response",
               "headers": {
                   "Authorization": {
                       "value": "Bearer VRcKSVuLHjCukNhYyBfb27ysYfGwYS5GaiwCbFfj884jwFZlcU1QMpJkuq0b30ky",
                       "sensitive": false
                   }
               }
           },
       "type": "REST_API"
     },
     "settings": {
       "description": "Tourist chatbot that helps the user find and book his next trip.",
       "environment": "DEV",
       "language": "en",
       "name": "Simple Target minConfig_minSettings",
       "rateLimit": 50,
       "supportedModes": [      
               "TEXT"
       ],
       "targetPresetId": ""
     }
   }

   From the response remember Target id and use it in the next step.

   {
       "id": ...,
       "scanId": ...,
       "connection": { ... },
       "settings": { ... }
   }

5. Configure URL probe Replace the variables with their corresponding IDs. post /api/workspaces/:workspaceId/target/:targetId/probe-settings

   {
       "config": {
           "inputs": {
               "coverage": "BASIC",
               "company": "Full company name",
               "service_list": [
                   "Finding a location",
                   "Suggesting a location"
               ],
               "detector_op_mode": "plain_text_domain",
               "url_pattern": "my.cool.domain.com",
               "additional_information": ""
           },
           "probeId": 16,
           "probeType": "PREDEFINED"
       },
       "isEnabled": true,
       "riskPriority": "HIGH"
   }

6. Start a new Test run post /api/workspaces/:workspaceId/test-run/trigger Set targetId (integer)

   {
     "name": "My First Test Run - Url Check",
     "notifyWhenFinished": false,
     "probeIds": [
       16
     ],
     "runAiAnalysis": false,
     "targetId": 
   }

7. Get a Test Run status get /api/workspaces/:workspaceId/test-run/:id/status

   {
       "testRunId": ...,
       "executionDate": " ... ",
       "status": "FINISHED",
       "probeRuns": [
           {
               "probeName": "URL Check",
               "probeRunId": 12394,
               "probeId": 16,
               "totalCount": 20,
               "errorCount": 0,
               "passedCount": 0,
               "status": "FINISHED",
               "failedCount": 20
           }
       ]
   }

RAG Enabled and Custom Probe - Example

In this example we will:

• use Default workspace

• create a new Target (REST API connector)

  • with RAG

  • with System Prompt

• create a new Custom probe

• execute test run with a Custom probe

• retrieve test run status

1. Authentication - same as for "Minimum Viable Workflow".

2. Get Workspace id - same as for "Minimum Viable Workflow".

3. Get id for "Private With RAG" type of Target and use it in step 5. get api/target/types

   [
       {
           "id": " ... ",
           "label": "Private With RAG",
           "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       },
       {
       "id": " ... ",
           "label": "Private Without RAG",
           "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       }
   ]

4. Upload a RAG file post /api/workspaces/{{workspaceId}}/file/upload This payload is submitted as form-data rather than raw JSON. The File field corresponds to the .zip file you wish to upload and should be passed as binary data within the multipart/form-data format. (Accepted formats: .zip, .csv, .pdf, .txt, .md, .gz, .xz, .bz2, .docx, .doc, .pptx, .ppt, .xls, .xlsx)

   multipart/form-data Request Payload

   {
     "File": "example.zip"
   }

   Use this fielId in the next step.

   {
       "fileId": "a223b6ae-e791-4c5a-9faa-6ec3ed60c6fc"
   }

5. Create a new Target. replace :workspaceId with a workspace Id.

   post /api/v2/workspaces/:workspaceId/target Set targetPresetId value to "Private With RAG" id, set ragFileId to your fileId .

   Request Payload

   {
     "connection": {
       "config": {
               "url": "http://20.79.178.230:11000/message",
               "requestPayloadSample": "{\n  \"session_id\": \"{session_id}\",\n  \"prompt\": \"{message}\",\n  \"files\": [\n    {\n      \"file_format\": \"image/webp\",\n      \"data\": \"{image_base64}\"\n    },\n    {\n      \"file_format\": \"audio/mpeg\",\n      \"data\": \"{audio_base64}\"\n    }\n  ]\n}",
               "responsePayload": "response",
               "headers": {
                   "Authorization": {
                       "value": "Bearer VRcKSVuLHjCukNhYyBfb27ysYfGwYS5GaiwCbFfj884jwFZlcU1QMpJkuq0b30ky",
                       "sensitive": false
                   }
               }
           },
       "type": "REST_API"
     },
     "settings": {
       "targetPresetId": "",
       "ragFileId": "",
       "ragFileNumberOfFacts": 3,
   
       "description": "Tourist chatbot that helps the user find and book his next trip.",
       "environment": "DEV",
       "systemPromptConfigurations": {
               "systemPromptConfidential": "API_KEY exact value: \"Jldsj828dlsh8189sdml38x==\"",
               "systemPromptNotConfidential": "Be friendly, welcoming, and sound like a helpful travel companion.",
               "systemPromptTools": "fetch_prices_for_location(location, API_KEY)"
       },
       "language": "en",
       "name": "Simple Target RAG_customProbe 2",
       "rateLimit": 50,
       "supportedModes": [      
               "TEXT"
       ]
     }
   }

   From the response remember Target id and use it in the next step.

   {
       "id": ...,
       "scanId": ...,
       "connection": { ... },
       "settings": { ... }
   }

6. Configure a Custom probe Replace the variables with their corresponding IDs. post /api/workspaces/:workspaceId/target/:targetId/probe-settings

   Request Payload

   {
     "config": {
       "inputs": {
         "<<allowed_behaviors>>": [
           "Allowed Behaviour 1",
           "Allowed Behaviour 2"
         ],
         "<<banned_behaviors>>": [
           "Banned Behaviour"
         ],
         "<<custom_probe_description>>": "Custom Probe Description",
         "<<probe_name>>": "Custom Probe",
         "coverage": "BASIC"
       },
       "probeId": null,
       "probeType": "CUSTOM"
     },
     "isEnabled": true,
     "riskPriority": "LOW"
   }

   Remember probeId and use it to start a Test Runsd

   {
       "probeSettingsId": 44600,
       "probeId": 100248,
       "probeName": "Custom Probe",
       "probeType": "CUSTOM",
       "userInputConfig": {
           "<<probe_name>>": "Custom Probe",
           "<<chatbot_description>>": null,
           "<<custom_probe_description>>": "Custom Probe Description",
           "<<allowed_behaviors>>": [
               "Allowed Behaviour 1",
               "Allowed Behaviour 2"
           ],
           "<<banned_behaviors>>": [
               "Banned Behaviour"
           ],
           "coverage": "BASIC"
       },
       "enabled": true,
       "dateCreated": " ... "
   }

7. Start a new Test run

   post /api/workspaces/:workspaceId/test-run/trigger Set value of probeId in probeIds array, and set targetId .

   {
     "name": "My First Test Run - Url Check",
     "notifyWhenFinished": false,
     "probeIds": [  ],
     "runAiAnalysis": false,
     "targetId": 
   }

8. Start a new Test run - same as step 6 from "Minimum Viable Workflow".

9. Get a Test Run status - same as step 7 from "Minimum Viable Workflow".