# 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](https://docs.probe.splx.ai/platform-api/authentication) to interact with the Platform API. 

2. Get Workspace id and use it in step 4.\
   `get /api/workspace`<br>

   ```json
   [
       {
           "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`<br>

   <pre class="language-json"><code class="lang-json">[
       {
           "id": " ... ",
           "label": "Private With RAG",
           "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       },
       {
   <strong>    "id": " ... ",
   </strong><strong>        "label": "Private Without RAG",
   </strong>        "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       }
   ]
   </code></pre>

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`<br>

   <pre class="language-json" data-title="Request Payload"><code class="lang-json">{
     "connection": {
       "config": {
               "url": "...",
               "requestPayloadSample": "{ ... }",
               "responsePayload": "...",
               "headers": {
                   "Authorization": {
                       "value": "Bearer ...",
                       "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"
       ],
   <strong>    "targetPresetId": ""
   </strong>  }
   }
   </code></pre>

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

   <pre class="language-json"><code class="lang-json">{
   <strong>    "id": ...,
   </strong>    "scanId": ...,
       "connection": { ... },
       "settings": { ... }
   }
   </code></pre>

5. Configure URL probe\
   Replace the variables with their corresponding IDs.\
   &#x20;`post /api/workspaces/:workspaceId/target/:targetId/probe-settings`<br>

   <pre class="language-json"><code class="lang-json">{
       "config": {
           "inputs": {
               "coverage": "BASIC",
               "company": "Full company name",
               "service_list": [
                   "service1",
                   "service2",
                   "service3"
               ],
               "detector_op_mode": "plain_text_domain", //regex_domain, regex_entire_url
               "url_pattern": "my.cool.domain.com",
               "additional_information": "Any additional information"
           },
   <strong>        "probeId": 16,
   </strong>        "probeType": "PREDEFINED"
       },
       "isEnabled": true,
       "riskPriority": "HIGH"
   }
   </code></pre>

6. Start a new Test run\
   `post /api/workspaces/:workspaceId/test-run/trigger`\
   \
   Set `targetId` (integer) and `probeIds` from enabled probes (url check probe id is 16).

   <pre class="language-json"><code class="lang-json">{
     "name": "My First Test Run - Url Check",
     "notifyWhenFinished": false,
     "probeIds": [
   <strong>    16
   </strong>  ],
     "runAiAnalysis": false,
   <strong>  "targetId": {{targetId}}
   </strong>}
   </code></pre>

7. Get a Test Run status\
   `get /api/workspaces/:workspaceId/test-run/:id/status`<br>

   ```json
   {
       "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`<br>

   <pre class="language-json"><code class="lang-json">[
       {
   <strong>        "id": " ... ",
   </strong><strong>        "label": "Private With RAG",
   </strong>        "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       },
       {
       "id": " ... ",
           "label": "Private Without RAG",
           "details": [ ... ]
       },
       {
           "id": " ... ",
           "label": "Public With RAG",
           "details": [ ... ]
       }
   ]
   </code></pre>

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)

   <pre data-title="multipart/form-data Request Payload"><code>{
     "File": "example.zip"
   }
   </code></pre>

   \
   Use this `fileId` in the next step.

   ```json
   {
       "fileId": "a223b6ae-e791-4c5a-9faa-a223b6ae"
   }
   ```

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` .

   <pre class="language-json" data-title="Request Payload"><code class="lang-json">{
     "connection": {
       "config": {
               "url": "...",
               "requestPayloadSample": "{ ... }",
               "responsePayload": "...",
               "headers": {
                   "Authorization": {
                       "value": "Bearer ...",
                       "sensitive": false
                   }
               }
           },
       "type": "REST_API"
     },
     "settings": {
   <strong>    "targetPresetId": "",
   </strong><strong>    "ragFileId": "",
   </strong>    "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"
       ]
     }
   }
   </code></pre>

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

   <pre class="language-json"><code class="lang-json">{
   <strong>    "id": ...,
   </strong>    "scanId": ...,
       "connection": { ... },
       "settings": { ... }
   }
   </code></pre>

6. Configure a Custom probe\
   Replace the variables with their corresponding IDs.\
   &#x20;`post /api/workspaces/:workspaceId/target/:targetId/probe-settings`<br>

   <pre class="language-json" data-title="Request Payload"><code class="lang-json">{
       "config": {
           "inputs": {
               "allowedBehaviors": [
                   "Give recommendations for travel locations on Earth.",
                   "todo2"
               ],
               "bannedBehaviors": [
                   "Recommending travel options to locations on Mars, such as Olympus Mons. 2. Recommending travel to the moons of Jupiter, such as Europa and Ganymede"
               ],
               "customProbeDescription": "Custom Probe Description",
               "probeName": "Custom Probe 1"
           },
           "probeId": null,
           "probeType": "CUSTOM"
       },
       "isEnabled": true,
       "riskPriority": "LOW"
   }
   }
   </code></pre>

   \
   Remember `probeId` and use it to start a Test Runsd

   ```json
   {
       "probeSettingsId": 55368,
       "probeId": 100418,
       "probeName": "Custom Probe 1",
       "probeCategoryName": null,
       "probeType": "CUSTOM",
       "userInputConfig": {
           "coverage": "BASIC",
           "probeName": "Custom Probe 1",
           "bannedBehaviors": [
               "Recommending travel options to locations on Mars, such as Olympus Mons. 2. Recommending travel to the moons of Jupiter, such as Europa and Ganymede"
           ],
           "allowedBehaviors": [
               "Give recommendations for travel locations on Earth.",
               "todo2"
           ],
           "customProbeDescription": "Custom Probe Description"
       },
       "enabled": true,
       "dateCreated": "...",
       "files": [],
       "tags": [
           {
               "name": "Custom Probe",
               "color": "pink"
           }
       ],
       "riskPriority": {
           "weight": "LOW",
           "defaultWeight": "MEDIUM",
           "isRecommended": false
       }
   }
   }
   ```

7. Start a new Test run

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

   <pre class="language-json"><code class="lang-json">{
     "name": "My First Test Run",
     "notifyWhenFinished": false,
   <strong>  "probeIds": [ 100418 ],
   </strong>  "runAiAnalysis": false,
   <strong>  "targetId": {{targetId}}
   </strong>}
   </code></pre>

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

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

## Custom Dataset - Example

Follow steps 1-5 from the [Minimum Viable Workflow](#minimum-viable-workflow-example)

6. Create [custom datased CSV file](https://docs.probe.splx.ai/ai-red-teaming/probe/probe-configuration/custom-probes#custom-dataset)

7. Upload custom dataset CSV file\
   `post /api/workspaces/:workspaceId/probe/custom/dataset/upload`\
   \
   \
   This payload is submitted as form-data rather than raw JSON. The File field corresponds to the .csv file you wish to upload and should be passed as binary data within the multipart/form-data format.

   <pre class="language-json" data-title="multipart/form-data Request Payload"><code class="lang-json">{
   "File": "example.csv"
   }
   </code></pre>

   \
   Use this fieId in the next step.

   <pre class="language-json" data-title=""><code class="lang-json">{
   <strong>    "fileId": "9aabf78d-cb04-419b-b225-9aabf78d",
   </strong>    "entriesRowCount": 7,
       "fileName": "custom_dataset.csv"
   }
   </code></pre>

8. Configure Custom Dataset probe\
   Replace the variables with their corresponding IDs.\
   &#x20;`post /api/workspaces/:workspaceId/target/:targetId/probe-settings`\
   \
   Replace `{{file_id}}` with the file\_id you copied earlier.

   <pre class="language-json" data-title="Request Payload"><code class="lang-json">{
     "isEnabled": true,
     "riskPriority": "CRITICAL",
     "config": {
       "probeType": "CUSTOM_DATASET",
       "probeId": null,
       "inputs": {
         "probeName": "Custom Dataset 1 _postman",
         "intent": "Custom Dataset Intent",
         "custom_on_domain": true,
         "custom_adversarial": true,
         "languages": [
           "en",
           "hr"
         ],
         "variationList": [
           "leet",
           "multilanguage",
           "rag"
         ],
         "strategyList": [
           "one_shot_w_retry",
           "multishot",
           "delayed_attack"
         ],
         "fileId": "{{file_id}}",
         "entriesCount": 7,
         "fileName": "custom_dataset.csv",
         "conversationDepth": 5,
         "attackMultiplier": 10
       }
     }
   }
   </code></pre>

   \
   Copy probeId for next step.

   <pre class="language-json" data-title=""><code class="lang-json">{
       "probeSettingsId": ...,
   <strong>    "probeId": 100001,
   </strong>    "probeName": "Custom Dataset 1 _postman",
       "probeCategoryName": null,
       "probeType": "CUSTOM_DATASET",
       "userInputConfig": {
           "fileId": "9aabf78d-cb04-419b-b225-0f4439ba52f5",
           "intent": "Custom Dataset Intent",
           "languages": [
               "en",
               "hr"
           ],
           "probeName": "Custom Dataset 1 _postman",
           "entriesCount": 7,
           "strategyList": [
               "one_shot_w_retry",
               "multishot",
               "delayed_attack"
           ],
           "variationList": [
               "leet",
               "multilanguage",
               "rag"
           ],
           "customOnDomain": false,
           "attackMultiplier": 10,
           "conversationDepth": 5,
           "customAdversarial": false
       },
       "enabled": true,
       "dateCreated": "...",
       "files": [
           {
               "fileName": "custom_dataset.csv",
               "fileId": "...",
               "link": "...",
               "token": ""
           }
       ],
       "tags": [
           {
               "name": "Custom Dataset",
               "color": "blue"
           }
       ],
       "riskPriority": {
           "weight": "CRITICAL",
           "defaultWeight": "MEDIUM",
           "isRecommended": false
       }
   }
   </code></pre>

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

10. &#x20;Get a Test Run status - same as step 7 from "Minimum Viable Workflow".

## Custom Q\&A Probe - Example

Follow steps 1-5 from the [Minimum Viable Workflow](#minimum-viable-workflow-example)

6. Create [custom datased Q\&A probe file](https://docs.probe.splx.ai/ai-red-teaming/probe/probe-configuration/custom-probes#custom-q-and-a-probe)

7. Upload custom Q\&A CSV file\
   `post /api/workspaces/:workspaceId/probe/custom/qa/upload`\
   \
   This payload is submitted as form-data rather than raw JSON. The File field corresponds to the .csv file you wish to upload and should be passed as binary data within the multipart/form-data format.

   <pre class="language-json" data-title="multipart/form-data Request Payload"><code class="lang-json">{
   "File": "example.csv"
   }
   </code></pre>

   \
   Use this fieIds in the next step.

   <pre class="language-json" data-title=""><code class="lang-json">{
   <strong>    "fileId": "32e5baba-f436-4074-9564-32e5baba",
   </strong><strong>    "entriesRowCount": 12,
   </strong>    "fileName": "qna_probe.csv"
   }

   </code></pre>

8. Configure Custom Dataset probe\
   Replace the variables with their corresponding IDs.\
   &#x20;`post /api/workspaces/:workspaceId/target/:targetId/probe-settings`\
   \
   Replace `{{file_id}}` and `{{entriesRowCount}}` with the data you copied earlier.

   <pre class="language-json" data-title="Request Payload"><code class="lang-json">{
     "isEnabled": true,
     "riskPriority": "MEDIUM",
     "config": {
       "probeType": "Q_A",
       "probeId": null,
       "inputs": {
         "probeName": "Custom Q&#x26;A Probe",
         "companyName": "Company Name",
   <strong>      "fileId": "{{fileId}}",
   </strong><strong>      "entriesCount": {{entriesRowCount}}
   </strong>    }
     }
   }
   </code></pre>

   \
   Copy probeId for next step.

   <pre class="language-json" data-title=""><code class="lang-json">{
       "probeSettingsId": ...,
       "probeId": 100002,
       "probeName": "Custom Q&#x26;A Probe _postman",
       "probeCategoryName": null,
       "probeType": "Q_A",
       "userInputConfig": {
           "fileId": "...",
           "probeName": "Custom Q&#x26;A Probe",
           "companyName": "Company Name",
           "entriesCount": 12
       },
       "enabled": true,
       "dateCreated": "...",
       "files": [
           {
               "fileName": "qna_probe.csv",
               "fileId": "...",
               "link": "...",
               "token": ""
           }
       ],
       "tags": [
           {
               "name": "Q&#x26;A",
               "color": "red"
           }
       ],
       "riskPriority": {
           "weight": "MEDIUM",
           "defaultWeight": "MEDIUM",
           "isRecommended": false
       }
   }
   </code></pre>

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

10. &#x20;Get a Test Run status - same as step 7 from "Minimum Viable Workflow".