/
Intent Based Diagnostics API Documentation

Intent Based Diagnostics API Documentation

Intent-Based Diagnostics feature is not enabled by default. It is only available to customers who have purchased this feature.

The Intent-Based Diagnostics feature in AGILITY allows users to perform detailed network diagnostics through various pre-configured scenarios. It enables the evaluation of variety of scenarios defined by 3GPP and ETSI while allowing users to bring their own scenarios.

 

Disclaimer: You can access the full OpenAPI (Swagger) specification directly in the AGILITY UI. To do this, click the user menu (top right), then select Public API Specification from the dropdown menu.

image-20250418-153654.png

Concepts Overview

Before using the API, it is important to understand the core entities and concepts:

  • Evaluation Scenario: A reusable test definition describing a diagnostic intent. It contains metadata (name, category, description), a set of steps (actions/assertions), and parameters needed to execute the scenario. Scenarios can be cloned, listed, and customized.

  • Evaluation: An execution instance of an evaluation scenario against a specific dataset or context. Evaluations record results, status, and outputs for later review or automation.

  • Custom Test Case ID: An optional identifier or set of IDs that can be associated with evaluation scenarios for linking to external test management systems or for custom automation workflows.

  • Step: A single action, check, or assertion within a scenario. Steps are executed in sequence as part of an evaluation, and each step may have parameters and produce results.

  • Catalog: The full set of available diagnostic steps supported by the platform. The catalog allows developers to discover which steps can be used when building or customizing evaluation scenarios.

User Journeys

This section provides practical, step-by-step guides for common workflows using the Intent Based Diagnostics API. Each journey illustrates the sequence of API calls, expected payloads, and typical server responses for real-world use cases.

Journey 1: Search, Evaluate, and Retrieve Results

A user wants to find an existing scenario, submit it for evaluation, and retrieve the results when the evaluation is complete.

Step 1: Search for a Scenario

  • Endpoint: GET /v1/intent-based-diagnostic/evaluation-scenarios

  • Example Request:

curl -X 'GET' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluation-scenarios?name=VoLTE' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN' \ -H 'userId: user123'

  • Expected Response:

{ "items": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "VoLTE Call Setup", ... } ], "total": 1 }

Step 2: Submit an Evaluation

  • Endpoint: POST /v1/intent-based-diagnostic/evaluations

  • Example Request:

{ "scenario_id": "123e4567-e89b-12d3-a456-426614174000", "analysis_id": "123e4567-e89b-12d3-a456-426614174001", "file_paths": null, "analysis_profile_id": null, "parameter_values_override": { "caller": "12345", "callee": "67890" } }

  • Example cURL:

curl -X 'POST' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluations' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN' \ -H 'Content-Type: application/json' \ -d @payload.json

  • Expected Response:

{ "id": "123e4567-e89b-12d3-a456-426614174002", "analysis_id": "123e4567-e89b-12d3-a456-426614174001" }

Step 3: Poll for Evaluation Completion

  • Endpoint: GET /v1/intent-based-diagnostic/evaluations/{id}

  • Example Request:

curl -X 'GET' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluations/123e4567-e89b-12d3-a456-426614174002' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN'

  • Expected Response (in progress):

{ "id": "123e4567-e89b-12d3-a456-426614174002", "status": "PROCESSING" }

  • Expected Response (completed):

{ "id": "123e4567-e89b-12d3-a456-426614174002", "status": "COMPLETED", "results": { ... } }

Journey 2: Clone, Edit, and Evaluate a Scenario

A user wants to clone an existing scenario, modify its steps, and then use it for evaluation.

Step 1: Clone the Scenario

  • Endpoint: POST /v1/intent-based-diagnostic/evaluation-scenarios/{id}/clone

  • Example Request:

curl -X 'POST' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluation-scenarios/123e4567-e89b-12d3-a456-426614174000/clone' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN' \ -H 'userId: user123'

  • Expected Response:

{ "id": "cloned-scenario-uuid", ... }

Step 2: Edit the Cloned Scenario

  • Endpoint: PUT /v1/intent-based-diagnostic/evaluation-scenarios/{id}

  • Example Request:

{ "name": "VoLTE Call Setup (Custom)", "description": "Custom VoLTE scenario with modified steps.", "category": "VoLTE", "evaluation_script": { "tag": "call-setup", "scenario": "VoLTE Custom", "steps": [ "Given a SIP INVITE is sent", "When the call is established", "Then the call should be released successfully" ], "parameters": { "caller": "54321", "callee": "09876" } }, "service_keys": "volte" }

  • Example cURL:

curl -X 'PUT' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluation-scenarios/cloned-scenario-uuid' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN' \ -H 'userId: user123' \ -H 'Content-Type: application/json' \ -d @payload.json

  • Expected Response:

{ "id": "cloned-scenario-uuid", ... }

Step 3: Submit the Edited Scenario for Evaluation

  • Continue with Steps 2–3 from Journey 1, using the new scenario ID.

Journey 3: Create Scenario from Scratch Using the Step Catalog

A user wants to build a new scenario, starting from the available steps in the catalog, ensuring the correct Gherkin order, and then use it for evaluation.

Step 1: Get the Steps Catalog

  • Endpoint: GET /v1/intent-based-diagnostic/steps/catalog

  • Example Request:

curl -X 'GET' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/steps/catalog' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN'

  • Expected Response:

{ "steps": [ { "name": "Given a SIP INVITE is sent", ... }, { "name": "When the call is established", ... }, { "name": "Then the call should be released successfully", ... } ] }

Step 2: Create a New Scenario (with correct Gherkin order)

  • Endpoint: POST /v1/intent-based-diagnostic/evaluation-scenarios

  • Note: The scenario must start with one or more Given steps, followed by When, then Then. If the order is incorrect, the server will return an error message.

  • Example Request:

{ "name": "Custom VoLTE Scenario", "description": "Scenario built from catalog steps.", "category": "VoLTE", "evaluation_script": { "tag": "call-setup", "scenario": "VoLTE Custom", "steps": [ "Given a SIP INVITE is sent", "When the call is established", "Then the call should be released successfully" ], "parameters": { "caller": "55555", "callee": "66666" } }, "service_keys": "volte" }

  • Example cURL:

curl -X 'POST' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluation-scenarios' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN' \ -H 'userId: user123' \ -H 'Content-Type: application/json' \ -d @payload.json

  • Expected Error Response (if order is wrong):

{ "detail": "Scenario steps must start with one or more 'Given', followed by 'When', then 'Then'." }

Step 3: Submit the New Scenario for Evaluation

  • Continue with Steps 2–3 from Journey 1, using the new scenario ID.

Endpoints Overview

The following sections describe the API endpoints for managing these entities and performing intent-based diagnostics.

Method

Path

Summary

Method

Path

Summary

GET

/v1/intent-based-diagnostic/evaluation-scenarios

List evaluation scenarios

POST

/v1/intent-based-diagnostic/evaluation-scenarios

Create evaluation scenario

GET

/v1/intent-based-diagnostic/evaluation-scenarios/{id}

Get a specific evaluation scenario

PUT

/v1/intent-based-diagnostic/evaluation-scenarios/{id}

Update an evaluation scenario

DELETE

/v1/intent-based-diagnostic/evaluation-scenarios/{id}

Delete an evaluation scenario

POST

/v1/intent-based-diagnostic/evaluation-scenarios/{id}/clone

Clone an evaluation scenario

PATCH

/v1/intent-based-diagnostic/evaluation-scenarios/{id}/custom-test-case-ids

Update custom test case IDs for a scenario

GET

/v1/intent-based-diagnostic/evaluation-scenarios/{id}/custom-test-case-ids

List custom test case IDs for a scenario

GET

/v1/intent-based-diagnostic/evaluation-scenarios/{id}/meta-data

Get scenario metadata

POST

/v1/intent-based-diagnostic/evaluation-scenarios/{id}/override

Override scenario parameters

GET

/v1/intent-based-diagnostic/evaluation-scenarios/{id}/steps

List steps in a scenario

POST

/v1/intent-based-diagnostic/evaluation-scenarios/{id}/parameter-override

Override scenario step parameters

GET

/v1/intent-based-diagnostic/evaluations

List evaluations (with filtering & pagination)

GET

/v1/intent-based-diagnostic/evaluations/{id}

Get a specific evaluation

POST

/v1/intent-based-diagnostic/evaluations

Create a new evaluation

GET

/v1/intent-based-diagnostic/evaluations/file

Download evaluation result file

GET

/v1/intent-based-diagnostic/steps/catalog

Get the catalog of available diagnostic steps

List Evaluation Scenarios

Endpoint

GET /v1/intent-based-diagnostic/evaluation-scenarios

Description

Retrieve a paginated list of evaluation scenarios, with optional filters by name, category, scenario type, and creator.

Query Parameters

Name

Type

Description

Name

Type

Description

name

string

Filter scenarios by name (partial match)

category

string

Filter scenarios by category

scenarioType

string

Filter by scenario type (SYSTEM or USER)

createdByCurrentUser

boolean

Filter scenarios created by the current user

editedByCurrentUser

boolean

Filter scenarios edited by the current user

lastModifiedDateFrom

string (date-time)

Filter scenarios modified on or after this date

lastModifiedDateTo

string (date-time)

Filter scenarios modified on or before this date

customTestCaseId

string

Filter scenarios by custom test case ID

formatSteps

boolean

Format steps with parameter values

page

integer

Page number (default: 1)

size

integer

Page size (default: 50, max: 100)

Headers

Name

Type

Required

Description

Name

Type

Required

Description

userId

string

Yes

The username of the user making the request

Example Request

curl -X 'GET' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluation-scenarios?name=VoLTE' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN' \ -H 'userId: user123'

Response Model

Returns a paginated list of evaluation scenarios.

Create Evaluation Scenario

Endpoint

POST /v1/intent-based-diagnostic/evaluation-scenarios

Description

Create a new evaluation scenario.

Headers

Name

Type

Required

Description

Name

Type

Required

Description

userId

string

Yes

The username of the user making the request

Request Body Fields

Field

Type

Required

Description

Field

Type

Required

Description

name

string

Yes

Name of the scenario

description

string

Yes

Description of the scenario

category

string

Yes

Category of the scenario

evaluation_script

object (see below)

Yes

Evaluation script including steps and parameters

custom_test_case_id

array of string

No

Custom test case IDs for automated testing

service_keys

string

Yes

Service keys to include in the evaluation

evaluation_script object fields:

Field

Type

Required

Description

Field

Type

Required

Description

tag

string

No

Optional tag for the script

scenario

string

No

Optional scenario name

steps

array of string

Yes

List of evaluation steps

parameters

object (key-value)

No

Step parameters as key-value pairs

Request Body Example

{ "name": "VoLTE Call Setup", "description": "Validates VoLTE call setup and teardown.", "category": "VoLTE", "evaluation_script": { "tag": "call-setup", "scenario": "VoLTE Basic", "steps": [ "Given a SIP INVITE is sent", "When the call is established", "Then the call should be released successfully" ], "parameters": { "caller": "12345", "callee": "67890" } }, "custom_test_case_id": ["TC-1234", "TC-5678"], "service_keys": "volte" }

Example Request

curl -X 'POST' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluation-scenarios' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN' \ -H 'userId: user123' \ -H 'Content-Type: application/json' \ -d @payload.json

Get Evaluation Scenario by ID

Endpoint

GET /v1/intent-based-diagnostic/evaluation-scenarios/{id}

Description

Get a specific evaluation scenario by its ID.

Path Parameters

Name

Type

Required

Description

Name

Type

Required

Description

id

string

Yes

Scenario UUID

Query Parameters

Name

Type

Description

Name

Type

Description

formatSteps

boolean

Format steps with parameter values

Example Request

curl -X 'GET' \ 'https://agility-dev.b-yond.com/cv/api/v1/intent-based-diagnostic/evaluation-scenarios/123e4567-e89b-12d3-a456-426614174000' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_ID_TOKEN'

Update Evaluation Scenario

Endpoint

PUT /v1/intent-based-diagnostic/evaluation-scenarios/{id}

Description

Update an existing evaluation scenario (only allowed for non-system scenarios by their creator or admin).

Path Parameters

Name

Type

Required

Description

Name

Type

Required

Description

id

string

Yes

Scenario UUID

Headers

Name

Type

Required

Description

Name

Type

Required

Description

userId

string

Yes

The username of the user making the request

Request Body Fields

Field

Type

Required

Description

Field

Type

Required

Description

name

string

Yes

Name of the scenario

description

string

Yes

Description of the scenario

category